一份让你少掉 10086 根头发的 OpenClaw 故障排查手册

适用人群：刚接触 OpenClaw 的萌新、被各种报错逼疯的开发者、以及半夜三点还在 debug 的你 💻🌙

🔑 一、无法认证（token missing）

❌ 症状

• 报错：unauthorized: gateway token missing
• 日志显示 authMode=token，但没给 token

🤔 原因

• 配置启用了 token 认证，但没传或传错了
• 控制面板 URL 缺少有效 token

✅ 解决方案

1. 检查 openclaw.json 中是否设置了 token 字段
2. 重启 OpenClaw 网关使配置生效
3. 正确姿势：使用 openclaw dashboard 命令生成带 token 的 URL（别手敲！）

💡 小贴士：浏览器缓存可能保留旧 token，建议无痕模式访问！

🖥️ 二、无法访问控制面板（页面一直转圈）

❌ 症状

• 打开 http://localhost:18791 → 白屏 or 转圈
• 有时返回 401/403

🤔 原因

• 监听地址不是 0.0.0.0（只绑定了 127.0.0.1）
• 未通过有效 token 认证
• 端口被占用 or 网关根本没启动

✅ 解决方案

1. 确保 openclaw.json 中 bindAddress 为 "0.0.0.0" 或 "127.0.0.1"
2. 使用 openclaw dashboard 获取带 token 的链接（如 http://localhost:18791?token=xxx）
3. 检查端口监听：ss -ltnp | grep 18791
4. 如果在 WSL，注意 Windows 和 Linux 网络隔离问题

🗣️ 三、模型输出语音？我要的是文本！

❌ 症状

• 返回的是 .wav 或语音流，而不是文字
• 明明没开 TTS，却听到“AI 在说话”

🤔 原因

• 配置中启用了 TTS 模块（比如 tts: true）
• 某些 agent 默认开启语音输出

✅ 解决方案

1. 检查 openclaw.json，确保 tts 相关字段设为 false
2. 在调用时加参数：--thinking off（禁用函数调用和语音）
3. 在 agents.defaults 中显式设置：

   "thinking": "off",
   "tts": false

🎙️ 内心 OS：我只想看文字，不想听 AI 唱《青藏高原》！

🦙 四、Ollama 服务器未启动（连接失败）

❌ 症状

• 报错：could not connect to ollama server, run 'ollama serve' to start it

🤔 原因

• Ollama 后台服务没跑起来

✅ 解决方案

# 启动 Ollama 服务（后台运行）
nohup ollama serve > /tmp/ollama.log 2>&1 &

# 验证是否成功
curl http://127.0.0.1:11434/api/tags

✅ 应返回已安装的模型列表（如 llama3, phi3 等）

🛠️ 五、其他高频“翻车”问题速查

1️⃣ CSP 阻止加载 blob 图片

• 报错：Refused to load the image 'blob:...' because it violates Content Security Policy
• 解决：在 CSP 的 img-src 中添加 blob:
  ✅ 正确示例：img-src 'self' data: blob: https:;

2️⃣ 代理连接错误（Connection error）

• 原因：Ollama 没启动 or 网络不通
• 验证：curl http://127.0.0.1:11434/api/tags

3️⃣ 会话文件被锁定（.jsonl.lock）

• 现象：日志提示“session file locked”
• 解决：

  # 查找锁文件
  ls ~/.openclaw/agents/*/sessions/*.lock
  # 删除锁文件 + kill 占用进程
  rm *.lock

4️⃣ 代理命令缺少参数

• 报错：Pass --to <E.164>, --session-id, or --agent...
• 解决：必须指定会话目标，例如：

  openclaw agent --to +15555550123 --message "Hello"

5️⃣ 函数调用解析失败

• 报错：None of the functions in the provided JSON response seem to match
• 解决：加 --thinking off 强制纯文本响应

6️⃣ 配置改了但不生效？

• 原因：thinking 配置未写入 agents.defaults
• 修复：

  "agents": {
    "defaults": {
      "thinking": "off"
    }
  }

  → 然后重启网关！

7️⃣ 端口冲突（网关已在运行）

• 现象：启动失败，提示 address already in use
• 解决：

  # 查 PID
  ss -ltnp | grep 18789
  # 杀进程
  kill <PID>
  # 或 systemd 用户服务
  systemctl --user stop openclaw-gateway.service

---

✅ 终极稳定性检查清单（建议收藏！）

检查项	命令	预期结果
A. 网关是否运行	ss -ltnp | grep 18789	有监听记录
	curl -I http://127.0.0.1:18789	返回 200/401（非 connection refused）
B. Ollama 是否就绪	curl -sS http://127.0.0.1:11434/api/tags	返回 JSON 模型列表
C. 会话锁文件	ls ~/.openclaw/agents/*/sessions/*.lock 2>/dev/null	应无输出（干净）
D. 代理通信测试	openclaw agent --to +15555550123 --thinking off --message 'ping'	返回文本响应
E. 控制面板访问	openclaw dashboard	输出带 token 的 URL，可正常打开

---

🎉 结语：配置一时爽，debug 火葬场？

别怕！OpenClaw 虽然“脾气”有点倔，但只要按步骤排查，99% 的问题都能搞定。