OpenClaw 常见问题与故障排查

使用方式

先按“现象”找到对应条目，再按“处理方法”操作。

1. http://127.0.0.1:18791/ 打不开

现象

• 浏览器访问 http://127.0.0.1:18791/
• 页面打不开，或者提示未授权

本机实测

• http://127.0.0.1:18789/：返回 200
• http://127.0.0.1:18791/：返回 401 Unauthorized

结论

• 18791 不是当前机器上应该直接打开的 Dashboard 首页地址
• 当前正确地址是：

http://127.0.0.1:18789/

正确确认方法

openclaw status
openclaw dashboard --no-open

Tip

以命令输出的 Dashboard 地址为准，不要自己猜端口。

2. 提示 unauthorized: gateway token mismatch

现象

unauthorized: gateway token mismatch

常见原因

• 打开的不是当前正确的 Dashboard 地址
• 浏览器里缓存了旧 token
• Gateway 重启后 token 已变化，但页面还在用旧设置
• 直接访问了 18791 等非主 Dashboard 端口

处理方法

先执行：

openclaw dashboard --no-open

然后按顺序处理：

1. 关闭当前 OpenClaw 页面
2. 新开一个浏览器无痕窗口
3. 直接粘贴 openclaw dashboard --no-open 刚复制的完整链接

如果仍然报错，再执行：

openclaw gateway restart
openclaw dashboard --no-open

如果还是不行，清理浏览器中 127.0.0.1:18789 的站点数据：

• Local Storage
• Session Storage
• Cookie

Warning

openclaw dashboard --no-open 输出的是带 token 的完整链接，不要公开分享。

3. 安装脚本提示 Gateway install failed: access denied

现象

Gateway install failed: schtasks create failed: access denied

本机实际情况

• OpenClaw Gateway 计划任务最终已存在
• 直接触发计划任务后，Gateway 可以正常运行

判断

• 更像是安装阶段的误报、时序问题，或者任务创建 / 刷新阶段的权限提示
• 不代表 OpenClaw 安装失败

排查方式

Get-ScheduledTask | Where-Object { $_.TaskName -like '*OpenClaw*' }
Start-ScheduledTask -TaskName "OpenClaw Gateway"
openclaw gateway status --json

4. 安装脚本提示 unknown option --probe

现象

error: unknown option '--probe'

判断

• 当前 CLI 版本里，probe 是 gateway 的子命令
• 安装脚本和当前 CLI 参数形式有小范围不一致

影响

• 不影响 CLI 安装完成
• 不影响后续手动验证 Gateway

5. doctor 提示 gateway.mode 未设置

处理方法

openclaw config set gateway.mode local
openclaw doctor --non-interactive

6. Gateway 没自动起来

排查顺序

1. 看状态：

openclaw status
openclaw gateway status --json

1. 手动拉起计划任务：

Start-ScheduledTask -TaskName "OpenClaw Gateway"

1. 再测健康检查：

Invoke-WebRequest http://127.0.0.1:18789/health

本机参考结果

• 返回 StatusCode: 200
• 返回体：{"ok":true,"status":"live"}

7. doctor 提示未配置 embedding provider

现象

• 提示缺少 OPENAI_API_KEY、GEMINI_API_KEY、VOYAGE_API_KEY 或 MISTRAL_API_KEY

影响

• 影响 memory search / embedding 相关功能
• 不影响 OpenClaw 基础安装
• 不影响 Gateway 和 Dashboard 可用性

处理建议

• 后续按需配置模型 API Key
• 或关闭对应 memory search 配置

8. WSL 安装超时

现象

wsl --install -d Ubuntu

执行很久后超时。

本机结论

• 超时不代表失败
• 复查后 Ubuntu 已成功安装

复查命令

wsl --list --verbose

9. 已配置 Codex，但聊天仍提示 No API key found for provider "openai-codex"

现象

• openclaw models status --json 已能看到 openai-codex OAuth profile
• 但 Dashboard 发消息时仍报：

No API key found for provider "openai-codex"

原因

• Gateway 进程仍在使用旧的 auth store 快照
• 新写入的 auth-profiles.json 尚未被运行中的 Gateway 进程重新加载

处理方法

openclaw gateway restart

如果 CLI 提示重启超时，但端口已被新进程占用，不要只看超时文案，继续检查：

openclaw gateway status --json
openclaw health

本机验证结果

重启后执行：

openclaw agent --to +10000000000 --message "Reply with OK only." --json --timeout 120

结果：

• 返回成功
• provider 为 openai-codex
• model 为 gpt-5.3-codex

Success

这类报错不一定说明 Codex 没配好，很多时候只是 Gateway 还没加载到新的认证文件。

---

分类：OpenClaw