1. 为什么 Win10 用户部署 OpenClaw 总卡在第一步OpenClaw小龙虾 AI是一个本地运行的 AI 智能体框架它能听懂自然语言指令后自动拆解任务、调用工具完成整理文件、浏览器自动化、表格生成这类操作。适合谁适合不想写代码、但想让电脑自己干活的 Windows 用户。它的 Logo 是一只红色龙虾所以圈内把部署调教叫「养虾」。但我在 Win10 上帮朋友部署时发现真正卡住新手的从来不是 OpenClaw 本身而是三个系统级拦路虎SmartScreen 拦截未签名程序、杀毒软件把键鼠模拟组件当木马隔离、以及中文路径导致配置文件写入失败。这三个问题任意一个出现表现都是「双击没反应」或「Gateway 一直离线」新手根本不知道从哪查。这篇就按 v2.7.5 一键部署包的实际落地流程走一遍从解压到可视化界面首次启动每一步都给可复制的目录结构、启动脚本和配置片段。你跟着做遇到报错直接跳到第 5 节对照排查。全程不需要命令行基础但我会把背后发生了什么讲清楚这样你遇到变体报错也能自己判断。先说清楚部署包的定位它内置了 Python 运行时、Node 依赖、浏览器控制驱动和键鼠模拟工具所以体积约 361MB。你不需要单独装任何环境这也是它和「手动 clone 源码再 pip install」最大的区别。代价是首次启动要初始化 Gateway 服务会慢一点1 到 3 分钟属于正常范围。2. 部署前必须做的三件系统准备含 SmartScreen 与杀毒误报处理这一节是整篇成功率的关键。我试过在没做任何准备的情况下直接双击启动程序结果核心文件被实时防护静默删除安装程序走到一半报「文件缺失」重装三次都一样。后来把下面三件事做完一次通过。第一件处理杀毒软件误报。OpenClaw 需要读写文件、模拟键鼠、控制浏览器这些行为在杀毒软件眼里和恶意程序高度相似所以会被误报。你需要把解压后的整个Openclaw-win文件夹加入白名单而不是只关掉杀毒软件——关掉只是临时的重启后防护恢复照样删文件。以 Windows Defender 为例设置 → 隐私和安全性 → Windows 安全中心 → 病毒和威胁防护 → 管理设置 → 排除项 → 添加排除项 → 文件夹选中你的Openclaw-win目录。360、火绒、腾讯管家的操作类似都是在「信任区」或「白名单」里加文件夹。第二件解除 SmartScreen 拦截。Win10 默认拦截未签名程序双击Openclaw Windows 一键启动.exe会弹「Windows 已保护你的电脑」。正确做法不是关掉 SmartScreen那会影响整机安全而是对这个文件单独放行右键程序 → 属性 → 常规 → 勾选底部的「解除锁定」→ 确定。这样后续启动就不会再弹拦截窗口。如果已经弹了点「更多信息」→「仍要运行」也能过但每次都要点不如直接解除锁定省事。第三件选对安装路径。Win10 对中文、空格、特殊字符路径的权限处理很严格D:\软件\小龙虾这种路径会在写.env配置文件时失败。推荐用纯英文短路径比如D:\OpenClaw或E:\AI\OpenClaw。同时确认目标磁盘空闲空间 ≥ 4G别装 C 盘——C 盘默认权限最严UAC 拦截概率最高。注意不要直接在压缩包里双击运行程序。Win10 自带解压工具对压缩包内文件的读取权限有限必须先完整解压到本地磁盘再操作否则会出现「文件读取失败」或配置写入被拒。这三件事做完你的环境就算准备好了。下面进入实际部署。3. 一键部署包解压与启动脚本配置可复制目录结构 settings 片段下载完成后你会得到一个Openclaw-Windows-2.7.5.zip。用 WinRAR 或 7-Zip 解压Win10 自带解压工具容易出权限问题右键选择「解压到 Openclaw-Windows-2.7.5」。解压完成后目录结构应该是这样的Openclaw-win/ ├── Openclaw Windows 一键启动.exe # 主启动程序红色龙虾图标 ├── runtime/ # 内置 Python Node 运行时 │ ├── python/ │ └── node/ ├── tools/ # 键鼠模拟、浏览器控制驱动 │ ├── browser_driver/ │ └── input_sim/ ├── config/ │ ├── default.env # 默认配置模板 │ └── settings.json # 可视化界面配置 └── logs/ # 运行日志排障看这里启动程序后安装向导会让你确认安装路径和生成配置文件。如果你想跳过向导手动预置配置可以在config/下新建settings.json内容如下路径按你的实际安装位置改{ install_path: D:\\OpenClaw, gateway: { host: 127.0.0.1, port: 8765, auto_start: true }, model: { provider: taotoken, base_url: https://taotoken.net/api, api_key: sk-你的Key, model_id: claude-sonnet-4-5 }, permissions: { file_access: true, input_sim: true, browser_control: true }, log_level: info }这里三个字段必须成对出现缺一个 Gateway 就起不来Base URL 填https://taotoken.net/apiAPI Key 填你申请到的 KeyModel ID 填你要用的模型标识。如果你用 Claude Code 那套配置习惯对应的settings.json路径在C:\Users\你的用户名\.claude\settings.json字段名一致可以直接复用。default.env里还有几个环境变量值得改# 安装根目录必须纯英文 OPENCLAW_HOMED:\OpenClaw # Gateway 监听端口被占用就换 8766 GATEWAY_PORT8765 # 日志级别排障时改成 debug LOG_LEVELinfo # 首次启动初始化超时单位秒 INIT_TIMEOUT180改完保存再双击启动程序向导会读取你的配置而不是用默认值。这一步能省掉向导里反复填路径的麻烦也避免手滑输错中文路径。4. 首次启动验证Gateway 在线判定与模型请求实测安装向导跑完后会自动启动主程序。首次启动因为要初始化系统服务、注册键鼠驱动、拉起 Gateway会慢一些。界面会显示「正在等待 Gateway 就绪...」这时候别关窗口等 1 到 3 分钟。怎么判断真的成功了看主界面右上角显示「Gateway 在线」才算部署完成。如果一直转圈或者显示离线先别急着重装按第 5 节排查。Gateway 在线后先做一次模型请求验证确认 API 链路是通的。打开可视化界面底部的输入框发一条最简单的指令帮我列出 D:\OpenClaw 目录下的所有文件如果 OpenClaw 返回了文件列表说明三件事都正常Gateway 服务在跑、模型 API 能调通、文件访问权限已授予。这一步比任何「部署成功」提示都可靠因为它走完了完整的「指令 → 模型 → 工具调用 → 返回结果」链路。想更直接地验证 API 配置可以用 curl 打一次 Gateway 的健康检查接口curl -X POST http://127.0.0.1:8765/v1/chat/completions ^ -H Content-Type: application/json ^ -H Authorization: Bearer sk-你的Key ^ -d {\model\:\claude-sonnet-4-5\,\messages\:[{\role\:\user\,\content\:\ping\}]}返回里如果有choices字段和正常内容说明模型侧配置无误。如果返回 401是 Key 不对如果连接被拒是 Gateway 没起来如果返回里choices为空多半是 Model ID 填错了。这三种报错在第 5 节都有对照。验证通过后你可以试几条 Win10 上实测有效的指令直接复制到输入框帮我整理 D:\Downloads 文件夹图片按日期分类文档按格式分类新建文件夹存放 打开浏览器搜索 AI 智能体发展趋势整理成表格保存到桌面 清理桌面无用快捷方式把 Word 文档移到 D:\工作文档指令越具体OpenClaw 拆解任务越准。模糊的「帮我整理电脑」它也能做但结果可能不符合你预期。5. 部署报错对照排查401、local proxy failed、reading choices、OAuth这一节按真实报错来。你遇到哪个直接对号入座。报错一401 Unauthorized。模型请求返回 401说明 API Key 无效或没带上。检查settings.json里api_key字段是否填了完整 Key有没有多余空格。如果你用的是环境变量方式确认OPENCLAW_API_KEY已导出且进程能读到。还有一种情况是 Key 过期或被禁用去控制台重新生成一个。报错二local proxy failed / 连接被拒。这个报错指向 Gateway 没起来或端口被占。先看logs/目录下最新的日志文件搜gateway关键字。常见原因是 8765 端口被其他程序占用改GATEWAY_PORT为 8766 重启即可。另一个原因是杀毒软件把 Gateway 进程隔离了去白名单确认Openclaw-win整个文件夹在列恢复被隔离文件后重启。报错三reading choices of undefined。这个报错说明 API 返回结构里没有choices字段通常是 Model ID 填错或者 Base URL 指向了不兼容的端点。确认base_url是https://taotoken.net/apimodel_id是你实际有权限调用的模型。如果 Base URL 末尾多了斜杠或路径也会导致返回结构异常。报错四OAuth 相关报错。如果你在配置里启用了需要 OAuth 的模型提供方但没完成授权流程会报 OAuth token 缺失。OpenClaw 的模型配置支持 API Key 和 OAuth 两种方式用 API Key 方式就不需要走 OAuth。检查settings.json里provider字段确认你用的是 Key 方式而不是 OAuth 方式。报错五Gateway 一直离线重启无效。按顺序查杀毒软件和 Defender 实时防护是否已把整个文件夹加白安装路径是否纯英文无空格右键桌面快捷方式 → 属性 → 兼容性 → 勾选「以管理员身份运行此程序」。这三步能解决九成离线问题。报错六首次启动卡在加载中超过 3 分钟。关掉后台占内存的程序浏览器、微信、其他 AI 工具重新以管理员身份启动。首次启动需要少量网络做初始化断网会导致卡住。如果还是不行把INIT_TIMEOUT调到 300 再试。排障时记住一个原则先看logs/目录的日志再对照上面的报错。日志里会写明具体是哪个环节失败比界面提示精确得多。6. 部署完成后的接入配置与后续扩展部署跑通只是起点。OpenClaw 的可视化界面能直接用但如果你想把它接入自己的工具链或者换模型、加技能需要动配置。这一节给几个实际会用到的接入点。换模型。改settings.json里的model块Base URL、API Key、Model ID 三件套一起换。比如你想换成更便宜的模型做批量任务只改model_id即可Base URL 和 Key 不变。改完重启 Gateway 生效。接入 Coding Plan 做长期编码任务。如果你想让 OpenClaw 承担持续的代码生成和 Agent 任务可以在配置里指向 Coding Plan 的端点。配置方式和上面一致把base_url换成对应的接入地址Key 用 Coding Plan 的 Key。这样 OpenClaw 就能在本地帮你跑代码相关的自动化流程。查看可用模型和调试对话。模型对话页面可以直接测试不同模型的返回效果确认 Model ID 写对没。接入文档里有完整的字段说明和示例配置卡住时对照着看比猜快。API Key 管理。Key 泄露了或者想换一个去 API Keys 页面重新生成然后更新settings.json里的api_key字段重启 Gateway。别把 Key 硬编码在会提交到 Git 的文件里用环境变量或本地配置文件。技能扩展。OpenClaw 支持通过工具目录扩展能力tools/下新增的驱动会被自动加载。后续想加 PDF 转 Word、批量磁盘清理这类功能往对应目录放工具包即可具体格式参考接入文档。最后说个实际经验部署完成后先把logs/目录的日志级别设成info跑几天确认稳定后再改回warn。这样万一出问题日志里有足够信息定位。另外桌面快捷方式建议右键 → 属性 → 兼容性 → 勾选「以管理员身份运行」避免每次手动提权。配置改完记得重启 Gateway不是重启整个程序。可视化界面右上角有重启服务的按钮比重开程序快。