适用版本： OpenClaw v2026.3
源码位置： src/errors/
错误代码格式
OpenClaw 错误代码采用 MODULE_CODE 格式：
GATEWAY_001
CHANNEL_002
AGENT_003
网关错误 (GATEWAY_*)
| 错误代码 |
错误信息 |
原因 |
解决方案 |
GATEWAY_001 |
Node.js version incompatible |
Node.js 版本低于 22.12 |
升级 Node.js 到 22.12+ |
GATEWAY_002 |
Port already in use |
端口被其他进程占用 |
lsof -i :18789 查找并终止进程 |
GATEWAY_003 |
Config file not found |
配置文件不存在 |
运行 openclaw config init 初始化 |
GATEWAY_004 |
Config validation failed |
配置文件格式错误 |
运行 openclaw config validate 检查 |
GATEWAY_005 |
Authentication failed |
认证失败 |
检查 Token 或密码配置 |
GATEWAY_006 |
Too many connections |
超过最大连接数 |
调整 server.maxConnections |
GATEWAY_007 |
WebSocket handshake failed |
WebSocket 握手失败 |
检查网络和协议版本 |
GATEWAY_008 |
Method not found |
请求的方法不存在 |
检查方法名拼写 |
GATEWAY_009 |
Permission denied |
权限不足 |
检查 Token 权限配置 |
GATEWAY_010 |
Rate limit exceeded |
请求频率超限 |
等待或调整限流配置 |
渠道错误 (CHANNEL_*)
| 错误代码 |
错误信息 |
原因 |
解决方案 |
CHANNEL_001 |
Channel not found |
渠道不存在 |
检查渠道配置 |
CHANNEL_002 |
Authentication required |
渠道需要认证 |
完成渠道认证流程 |
CHANNEL_003 |
Connection lost |
连接断开 |
检查网络，重新连接 |
CHANNEL_004 |
Message send failed |
消息发送失败 |
检查接收者 ID 和网络 |
CHANNEL_005 |
Media download failed |
媒体下载失败 |
检查存储空间和网络 |
CHANNEL_006 |
Rate limited by platform |
被平台限流 |
降低发送频率 |
CHANNEL_007 |
Session key parse error |
Session 键解析错误 |
检查消息格式 |
CHANNEL_008 |
Duplicate message |
重复消息 |
正常现象，已去重 |
CHANNEL_009 |
Group not found |
群组不存在 |
检查群组 ID |
CHANNEL_010 |
Pairing required |
需要配对 |
完成 DM 配对流程 |
Agent 错误 (AGENT_*)
| 错误代码 |
错误信息 |
原因 |
解决方案 |
AGENT_001 |
Session not found |
会话不存在 |
创建会话或检查 sessionKey |
AGENT_002 |
Agent not available |
Agent 不可用 |
检查 Agent 配置 |
AGENT_003 |
Turn timeout |
Turn 执行超时 |
增加 agents.defaults.turnTimeout |
AGENT_004 |
Tool call failed |
工具调用失败 |
检查工具实现和参数 |
AGENT_005 |
Tool timeout |
工具执行超时 |
优化工具实现或增加超时 |
AGENT_006 |
Tool not found |
工具不存在 |
检查工具名称或注册工具 |
AGENT_007 |
Tool permission denied |
工具权限拒绝 |
检查 tools.permissions 配置 |
AGENT_008 |
Sandbox violation |
沙箱违规 |
检查沙箱配置或工具权限 |
AGENT_009 |
Memory limit exceeded |
内存超限 |
清理会话或增加限制 |
AGENT_010 |
ACP disabled |
ACP 被禁用 |
启用 acp.enabled |
AGENT_011 |
Subagent forbidden |
Subagent 被禁止 |
检查 acp.agents.allowed |
AGENT_012 |
Provider unavailable |
Provider 不可用 |
检查 API Key 和网络 |
Provider 错误 (PROVIDER_*)
| 错误代码 |
错误信息 |
原因 |
解决方案 |
PROVIDER_001 |
Invalid API key |
API Key 无效 |
检查并更新 API Key |
PROVIDER_002 |
Rate limit exceeded |
API 限流 |
等待或升级 API 套餐 |
PROVIDER_003 |
Model not found |
模型不存在 |
检查模型名称 |
PROVIDER_004 |
Context length exceeded |
上下文超长 |
减少 Transcript 长度 |
PROVIDER_005 |
Content filtered |
内容被过滤 |
修改提示词 |
PROVIDER_006 |
Insufficient quota |
配额不足 |
充值或升级套餐 |
PROVIDER_007 |
Service unavailable |
服务不可用 |
稍后重试 |
PROVIDER_008 |
Timeout |
API 超时 |
检查网络或重试 |
存储错误 (STORAGE_*)
| 错误代码 |
错误信息 |
原因 |
解决方案 |
STORAGE_001 |
Database corrupted |
数据库损坏 |
从备份恢复 |
STORAGE_002 |
Disk full |
磁盘已满 |
清理磁盘空间 |
STORAGE_003 |
Permission denied |
文件权限错误 |
检查文件权限 |
STORAGE_004 |
Backup failed |
备份失败 |
检查备份配置和空间 |
STORAGE_005 |
Restore failed |
恢复失败 |
检查备份文件完整性 |
插件错误 (PLUGIN_*)
| 错误代码 |
错误信息 |
原因 |
解决方案 |
PLUGIN_001 |
Plugin not found |
插件不存在 |
检查插件路径 |
PLUGIN_002 |
Plugin load failed |
插件加载失败 |
检查依赖和语法 |
PLUGIN_003 |
Dependency not found |
依赖缺失 |
安装依赖包 |
PLUGIN_004 |
Hook execution failed |
Hook 执行失败 |
检查 Hook 实现 |
PLUGIN_005 |
Skill not found |
Skill 不存在 |
检查 Skill 配置 |
错误处理最佳实践
1. 使用结构化日志
# 启用错误日志
LOG_LEVEL=error LOG_FORMAT=json openclaw gateway start
2. 错误重试策略
// 对于可重试错误
if (error.retryable) {
await sleep(1000 * retryCount);
return retry();
}
// 对于不可重试错误
if (!error.retryable) {
throw new FatalError(error);
}
3. 错误监控
# 配置错误告警
alerting:
rules:
- alert: HighErrorRate
expr: rate(openclaw_errors_total[5m]) > 0.1
severity: warning
4. 错误上报
# 收集诊断信息
openclaw doctor --collect-logs
# 输出文件: openclaw-diagnostic-YYYYMMDD.tar.gz
系列索引： OpenClaw 源码解析：目录索引