OpenClaw 本地配置教程（Windows）

基于实际部署过程整理，包含成功步骤与常见失败点，方便复现和排错。

一、环境与安装

1.1 前置条件

• 操作系统：Windows 10/11
• Node.js：22 及以上（node -v 检查）
• PowerShell：以普通用户或管理员运行均可

1.2 安装 OpenClaw

powershell

npm install -g openclaw@latest

安装后执行 openclaw --version 确认。

1.3 数据目录放到 D 盘（可选，节省 C 盘）

每次新开 PowerShell 先执行（仅当前窗口有效）：

powershell

$env:OPENCLAW_HOME = 'D:\openclaw-home'

若需永久生效，可执行：

powershell

New-Item -ItemType Directory -Path 'D:\openclaw-home' -Force
[Environment]::SetEnvironmentVariable("OPENCLAW_HOME", "D:\openclaw-home", "User")

之后新开终端需重新打开 PowerShell 才能读取新环境变量。建议：教程中以下所有命令前都先执行一遍 $env:OPENCLAW_HOME = 'D:\openclaw-home'。

二、首次配置（Setup / Onboard）

2.1 运行配置向导

powershell

$env:OPENCLAW_HOME = 'D:\openclaw-home'
openclaw setup

（或使用 openclaw onboard --install-daemon，按需选择。）

2.2 向导中的选择

表格

步骤	建议选择	说明
风险提示	输入 yes 回车	不要写成 --install-daemonyes 等连在一起
配置模式	QuickStart	推荐，其余用默认即可
部署方式	Local (this machine)	本机跑网关，手机通过聊天渠道或 Web 访问
模型提供商	Volcano Engine / Doubao（火山引擎 / 豆包）	国内可用，需自备 API Key
默认模型	如 volcengine/doubao-seed-1-8-251228	与火山控制台里「已开通」的模型 ID 对应
API Key	粘贴火山控制台的 API Key	见下文「失败点：Coding 计划 400」
渠道配置	Skip for now 或只配 WebChat	本地教程不依赖 Telegram / 飞书 / WhatsApp

失败点 1：参数和 yes 不要连写报错：unknown option '--install-daemonyes'原因：把 yes 和 --install-daemon 连在一起输入。解决：命令只输入 openclaw onboard --install-daemon，在下一行单独输入 yes 回车。

三、网关启动与 Dashboard 连通

3.1 启动网关

powershell

$env:OPENCLAW_HOME = 'D:\openclaw-home'
openclaw gateway --port 18789

保持该窗口不关闭。看到类似输出即成功：

• [gateway] listening on ws://127.0.0.1:18789
• [canvas] host mounted at http://127.0.0.1:18789/__openclaw__/canvas/

3.2 用带 token 的地址打开聊天页（重要）

浏览器不要只打开 http://127.0.0.1:18789/，否则会一直提示：

• unauthorized: gateway token missing
• Disconnected from gateway

正确做法：使用带 auth-token 的完整地址，例如：

plaintext

http://127.0.0.1:18789/chat?auth-token=你的token&session=agent%3Amain%3Amain

如何拿到 token：

1. 打开 D:\openclaw-home\.openclaw\openclaw.json
2. 搜索 gateway → auth → token，复制引号内的整串字符
3. 替换上面 URL 里的 你的token

示例（仅格式，token 请用自己配置文件里的）：

plaintext

http://127.0.0.1:18789/chat?auth-token=251022929ec86f7a794e4286bd95f69c0905309e69c49bc3&session=agent%3Amain%3Amain

若在 Dashboard 的「设置 → 网关访问」里有「网关令牌」输入框，也可把同一串 token 填进去保存，再访问 http://127.0.0.1:18789/。部分版本会显示 "Schema unavailable"，此时用 URL 带 auth-token 最稳妥。

失败点 2：Missing config报错：Missing config. Run 'openclaw setup' or set gateway.mode=local原因：尚未成功跑完一次 openclaw setup，没有生成 openclaw.json。解决：按第二节完整走一遍 openclaw setup，再启动网关。

失败点 3：Gateway start blocked (gateway.mode)报错：Gateway start blocked: set gateway.mode=local or pass --allow-unconfigured原因：未设置 gateway.mode。解决：通过 openclaw configure → Gateway 相关项设置，或临时使用 openclaw gateway --port 18789 --allow-unconfigured 启动（仅作验证用）。

四、模型与 API Key（豆包 / 火山引擎）

4.1 在火山控制台准备

1. 打开火山引擎 Ark 控制台
2. 在「模型广场」开通需要的模型（如 Doubao-Seed-1.8、Doubao-Seed-2.0-Code）
3. 在「API Key 管理」创建 Key，复制保存

4.2 在 OpenClaw 中填写 Key 与模型

powershell

$env:OPENCLAW_HOME = 'D:\openclaw-home'
openclaw configure

选择 Model → 选 Volcano Engine / Doubao → 选 No 使用新 Key → 粘贴 API Key → 默认模型填如 volcengine/doubao-seed-1-8-251228（与控制台模型 ID 一致）→ 保存并 Continue。

失败点 4：400 Coding 计划 / 订阅过期（非常常见）报错：400 Your account (xxxx) does not have a valid coding plan subscription, or your subscription has expired.原因：

• 账号未开通「Coding 计划」或已过期；
• 或 API Key 所属项目与开通 Coding 计划的项目不一致。解决：

1. 打开报错中的链接，确认「Coding 计划」状态为已开通，且与当前使用的 API Key 所属项目一致；
2. 若已付费仍报错，将完整 400 报错 + 控制台「已开通」截图提交给火山 / 字节客服，请求核查账号与计费状态；
3. 临时可改用其他有免费额度的模型（如通义、Kimi 等），在 openclaw configure → Model 中切换提供商并填写对应 API Key。

五、渠道说明（本地教程不依赖）

本教程以「仅用浏览器访问本地 Dashboard」为目标，不要求配置 Telegram / 飞书 / WhatsApp。

5.1 Telegram

• 国内直连常失败，日志会出现 [telegram] ... Network request failed、deleteWebhook failed 等。
• 若不使用 Telegram：openclaw configure → Channels → Remove channel config → 选择 Telegram 删除，可避免刷屏报错。

5.2 飞书

• 需安装插件：openclaw plugins install @openclaw/feishu。
• 在部分 Windows 环境下，向导内自动安装会报 Error: spawn EINVAL，可先选 Skip for now，仅用本地 Dashboard；飞书可日后单独排查 npm/Node 环境再装。

5.3 WhatsApp

• 需本机网络能稳定访问 WhatsApp 服务（通常需代理），否则会出现 408 等超时；
• 若仅做本地教程，可不配置。

六、多选与菜单操作

• 配置向导中若出现「多选」界面（如同时选 Model、Channels）：
  • 部分版本为单选，空格无效；
  • 可一轮只选一项（如先 Model，保存后再打开 configure 选 Channels）。
• 「Skip for now」是向导内的选项，用方向键选中后回车即可，不要在 PowerShell 里输入 skip for now，否则会报「无法将 skip 项识别为 cmdlet」。

七、当前可用的访问方式总结

完成上述配置后，你可按以下方式使用本地 OpenClaw：

1. 启动网关（每次使用前执行，且保持窗口开启）：

powershell

$env:OPENCLAW_HOME = 'D:\openclaw-home'
openclaw gateway --port 18789

1. 浏览器访问聊天页（将 YOUR_TOKEN 换成 openclaw.json 里 gateway.auth.token 的值）：

plaintext

http://127.0.0.1:18789/chat?auth-token=YOUR_TOKEN&session=agent%3Amain%3Amain

1. 在页面中直接与 Agent 对话即可，无需连接飞书、Telegram 或 WhatsApp。

八、失败点速查表

表格

现象	可能原因	处理方向
unknown option '--install-daemonyes'	把 yes 和参数连写	命令与 yes 分开输入
Missing config	未完成 setup	运行 openclaw setup 走完向导
Gateway start blocked (mode)	未设置 gateway.mode	configure 里设置或加 --allow-unconfigured
Dashboard 一直 gateway token missing	未带 auth-token	用带 ?auth-token=... 的 URL 或设置里填网关令牌
400 coding plan subscription	火山账号 / 计费问题	检查 Coding 计划、项目、联系客服
[telegram] ... failed 刷屏	国内网络无法连 Telegram	删除 Telegram 渠道或忽略
Feishu 安装 spawn EINVAL	向导内 npm 子进程异常	选 Skip，仅用 Dashboard；或单独排查 npm/Node
WhatsApp 408 / 超时	本机无法访问 WhatsApp	使用代理或改用其他渠道
skip 命令不存在	在终端输入了菜单选项	在向导里用方向键选 Skip 并回车

九、配置文件位置（便于排错）

• 主配置：D:\openclaw-home\.openclaw\openclaw.json
• 环境变量（若用 .env）：D:\openclaw-home\.openclaw\.env
• 网关日志：C:\Users\你的用户名\AppData\Local\Temp\openclaw\openclaw-*.log

修改配置后需重启网关（Ctrl+C 停止后重新执行 openclaw gateway --port 18789）才能生效。

教程基于 OpenClaw 2026.2.24 及同期版本，若界面或文案有更新，以官方文档为准。

亲测有效，按步骤走一遍就能跑起来，欢迎大家一起补充修正。