附录 F：常见错误与解决方案

遇事不慌，先查这里。大部分问题不用重新安装，按下面的方法修。

---

🔴 端口占用

报错信息：

Error: listen EADDRINUSE :::18789
// 或
Port 18789 is already in use

原因： Gateway 默认端口 (18789) 已被其他程序占用。

解决方案：

# 方案一：杀掉占用的程序（推荐）
openclaw gateway start --force

# 方案二：换一个端口
openclaw config set gateway.port 19001
openclaw gateway start

# 方案三：查看是谁占用了端口
# macOS / Linux
lsof -i :18789
# 然后手动杀掉
kill -9 <PID>

🔴 认证失败

报错信息：

Error: authentication failed
// 或
401 Unauthorized
// 或
Invalid gateway token

原因： Token 或密码不匹配。

解决方案：

# 1. 重新生成 Token
openclaw doctor --generate-gateway-token

# 2. 查看当前配置的 Token
openclaw config get gateway.auth.token

# 3. 临时去掉认证（仅调试！）
openclaw gateway start --auth none

# 4. 确认环境变量
echo $OPENCLAW_GATEWAY_TOKEN

注意：如果同时设置了配置文件和环境变量，优先使用环境变量。

🔴 配置错误

报错信息：

Error: invalid configuration
// 或
JSON parse error
// 或
Schema validation failed

原因： openclaw.json 格式有问题或字段不对。

解决方案：

# 1. 用内置工具验证配置
openclaw config validate

# 2. 检查 JSON 格式（常见：多了一个逗号）
cat ~/.openclaw/openclaw.json | python3 -m json.tool

# 3. 确认配置文件路径
openclaw config file

# 4. 查看正确格式
openclaw config schema | head -50

# 5. 备份后重配
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
openclaw configure

常见 JSON 错误：

// ❌ 错误：多了一个逗号
{
    "port": 18789,   ← 最后一项不能有逗号
}

// ✅ 正确
{
    "port": 18789
}

🔴 模型调用失败

报错信息：

Error: model provider returned error
// 或
429 Too Many Requests
// 或
401 Invalid API Key
// 或
Connection timeout

原因与解决方案：

错误	原因	解决
401 Invalid API Key	API Key 不对	检查 openclaw config get models
429 Too Many Requests	频率限制	等一会儿再试，或降频
Connection timeout	网络不通	检查代理、VPN、网络
Insufficient balance	余额不足	去对应平台充值
Model not found	模型名写错了	openclaw models list 确认可用模型

# 查看模型配置和状态
openclaw models status

# 切换默认模型
openclaw models set deepseek/deepseek-v4-flash

# 设置模型 API Key
openclaw config set models.providers.deepseek.apiKey "你的 Key"

🔴 Gateway 启动失败

报错信息：

Error: failed to start gateway
// 或
Could not start service
// 或
gateway: service start failed

排查步骤：

# 1. 用前台模式启动看详细错误
openclaw gateway run --verbose

# 2. 检查配置文件
openclaw config validate

# 3. 完整诊断
openclaw doctor --fix

# 4. 查看服务状态
openclaw gateway status

# 5. 查看日志
openclaw logs

# 6. 重新安装服务
openclaw gateway uninstall
openclaw gateway install
openclaw gateway start

常见原因：

• 配置文件损坏 → 跑 openclaw config validate
• 端口被占用 → lsof -i :18789
• 权限不够 → 用 sudo 或检查日志权限
• 依赖缺失 → openclaw doctor --fix

🔴 通道连接失败

报错信息：

Error: channel telegram: connect failed
// 或
Channel disconnected

解决方案：

# 1. 检查通道状态
openclaw status --deep

# 2. 查看通道日志
openclaw channels logs --channel <通道名>

# 3. 重新登录
openclaw channels login --channel <通道名>

# 4. 重新配置
openclaw channels add --channel <通道名> <参数>

各通道常见问题：

通道	常见问题	检查要点
飞书	应用没发布、权限不足	开放平台 → 安全设置 → IP 白名单
Telegram	Token 过期、Bot 被停	跟 @BotFather 说 /mybots 检查
Discord	Intents 没开、Token 过期	Developer Portal → Bot → Privileged Intents
企业微信	URL 不通、IP 白名单	确保 Gateway URL 可以被企微访问
WhatsApp	二维码过期	重新登录 openclaw channels login
Slack	Socket Mode 没开	API 页面 → Socket Mode 开启

🔴 Agent 无响应

问题表现： 通道配好了，消息发出去了，但 Agent 没回。

排查步骤：

# 1. 看 Agent 有没有收到消息
openclaw sessions --active 10

# 2. 看 Agent 状态
openclaw agents list

# 3. 检查路由绑定
openclaw agents bindings

# 4. 看模型是否正常工作
openclaw models status

🟡 性能问题

问题表现： 响应慢、经常超时。

解决方法：

# 换个更快的模型
openclaw models set deepseek/deepseek-v4-flash

# 查看当前会话量
openclaw sessions --active 60

# 清理旧会话数据
openclaw sessions cleanup

---

📋 错误排查五步法

遇到问题不要慌，按这个顺序查：

1️⃣ openclaw status         → 看整体状态
2️⃣ openclaw doctor --fix   → 自动修复
3️⃣ openclaw config validate → 检查配置
4️⃣ openclaw gateway run --verbose → 前台看错误
5️⃣ 翻这个附录 👆

如果还解决不了：

• openclaw docs <关键词> — 搜在线文档
• 去 OpenClaw 社区或 GitHub Issues 提问
• 把 openclaw status --all 的输出贴出来，别人更容易帮你

---

💡 大部分问题跑 openclaw doctor --fix 就能搞定，先试试这个！