OpenClaw 常见错误排查
本文档整理了 OpenClaw 在安装、初始化、运行及使用过程中的常见问题与解决方案，帮助用户快速定位并解决问题。
各大模型厂商 API 地址
注意： Base URL 地址需兼容 OpenAI API 协议。
火山方舟
Base URL：
https://ark.cn-beijing.volces.com/api/v3
详情参考官方文档：https://www.volcengine.com/docs/82379/1298459?lang=zh
DeepSeek
Base URL：
https://api.deepseek.com/v1
详情参考官方文档：https://api-docs.deepseek.com/zh-cn/
阿里云百炼
Base URL：
https://dashscope.aliyuncs.com/compatible-mode/v1
模型 ID 获取地址：https://bailian.console.aliyun.com/cn-beijing/?tab=model#/model-market
详情参考官方文档：https://bailian.console.aliyun.com/cn-beijing/?tab=doc#/doc
Coding Plan Base URL：
https://coding.dashscope.aliyuncs.com/v1
月之暗面（Kimi）
Base URL：
https://api.moonshot.cn/v1
详情参考官方文档：https://platform.moonshot.cn/docs/overview
联通元景
Base URL：
https://maas-api.ai-yuanjing.com/openapi/compatible-mode/v1
详情参考官方文档：https://maas.ai-yuanjing.com/doc/pages/216543011/
基础问题排查
当 OpenClaw 出现异常时，首先查看日志是否有报错。
如需进入未启动的 OpenClaw 容器进行排查，可执行以下命令：
docker-compose -f /www/dk_project/dk_app/dk_openclaw/docker-compose.yml run --rm --entrypoint /bin/bash -u root openclaw-cli
进入容器后，执行以下命令进行诊断：
openclaw health # 检查系统健康状态
openclaw status # 查看服务运行状态
openclaw doctor # 自动诊断常见问题
安装问题
插件未安装
解决方案：
重新安装插件。可能因网络波动等原因导致安装不完整。
docker-compose 服务异常
解决方案：
执行 docker-compose ls 检查状态，以下为正常输出：
root@debian12:~# docker-compose ls
NAME STATUS CONFIG FILES
dk_openclaw running(1) /www/dk_project/dk_app/dk_openclaw/docker-compose.yml
如状态异常，请重新安装 Docker。
初始化失败
排查思路：
-
检查容器拉取是否正常
执行
docker ps -a查看容器状态：root@debian12:~# docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6641ccad9864 docker.cnb.cool/btpanel/openclaw "docker-entrypoint.s…" About an hour ago Up About an hour (healthy) 0.0.0.0:18789-18790->18789-18790/tcp, [::]:18789-18790->18789-18790/tcp dk_openclaw-openclaw-gateway-1拉取异常时，进入
/www/dk_project/dk_app/dk_openclaw目录执行docker pull，查看镜像拉取是否成功。拉取不成功时，尝试设置镜像加速源后重试。
-
安装应用时不勾选自动初始化
此步骤用于排查是否因系统资源不足，导致初始化进程被系统终止。
-
手动执行初始化命令
若上一步安装成功，说明是系统资源不足导致初始化失败，需手动执行初始化命令。
进入容器后，执行
openclaw onboard：
建议服务器配置为 2 核 4G，以获得更佳体验。
终极方案
当上述操作均无法安装成功时，删除 OpenClaw 插件，更新软件商店列表，重新安装。
前提是没有重要数据。如有重要数据，请加 QQ 群 574292667 联系管理员协助处理。
使用问题
LLM 请求超时（LLM request time out）
问题原因：
请求大模型超时，通常由网络问题或请求上下文过大导致。
解决方案：
请求大模型地址，检查连通性：
curl -vvv [大模型厂商地址]
# 以阿里百炼为例
curl -vvv https://dashscope.aliyuncs.com/compatible-mode/v1
以下为正常输出：
root@debian12:~# curl -v https://api.deepseek.com/v1
* Trying 116.205.40.114:443...
* Connected to api.deepseek.com (116.205.40.114) port 443 (#0)
................
> GET /v1 HTTP/2
> Host: api.deepseek.com
> user-agent: curl/7.88.1
> accept: */*
>
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* old SSL session ID is stale, removing
< HTTP/2 401
< date: Thu, 12 Mar 2026 14:48:05 GMT
< content-length: 31
...
* Connection #0 to host api.deepseek.com left intact
特殊情况：
在 Docker 运行期间启动防火墙，会导致容器网络出现问题，无法访问外网（进而引发 LLM request time out），以及宿主机无法访问容器端口等故障。
原因：Docker 启动时会自动向 iptables 写入规则，容器网络通信均依赖 iptables。启动防火墙会清空所有 iptables 规则链，导致容器网络故障。简而言之：
Docker 先运行 → 写入 iptables 网络规则 → 启动防火墙 → 清空 Docker 规则并关闭转发 → 容器网络彻底失效
解决方案：
-
重启 Docker：
systemctl restart docker -
或先启动防火墙，再启动 Docker。
400 错误（Bad Request）
问题原因：
- 请求参数错误、配置项缺失或语法无效。
- 调用大模型时使用了无效的模型名。
- 请求上下文过长或发送了空提示语。
解决方法：
- 核对模型名是否与厂商官方一致，确保无拼写错误。
- 精简上下文内容，避免超出厂商限制。
- 检查请求配置，补充缺失的参数，确保无空提示，参数格式兼容 OpenAI API 协议。
401 错误（Unauthorized）
报错信息：
Unauthorized（未经授权）Invalid Access Token or Token Expired（无效 Token 或 Token 过期）
问题原因：
- API Key 不正确、已过期或已删除。
- Base URL 填写错误。
- 模型 ID 填写错误。
解决方案：
检查 OpenClaw 配置，修改后需重建容器或重启网关。
-
通过插件查看，检查以下项目：
- API 地址是否正确。
- 密钥是否有效或填写正确。
- 模型名称是否正确。
-
通过配置文件查看：面板安装的 OpenClaw 配置文件路径为
/www/dk_project/dk_app/dk_openclaw/data/config/openclaw.json，以阿里百炼为例："models": {
"mode": "merge",
"providers": {
"detaulf1": {
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"apiKey": "sk-api-key",
"api": "openai-completions",
"headers": {},
"models": [
{
"id": "qwen3-max",
"name": "qwen3-max",
"reasoning": false,
"input": [
"text",
"image"
],
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
},
"contextWindow": 200000,
"maxTokens": 8192
}
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "detaulf1/qwen3-max"
},
"workspace": "/home/node/clawd",
"compaction": {
"mode": "safeguard"
},
"maxConcurrent": 4,
"subagents": {
"maxConcurrent": 8
}
}
},重点配置说明：
baseUrl：模型 API 地址，可替换为所需的兼容 OpenAI API 协议的供应商地址。apiKey：需确保有效。primary：所使用的模型，请根据实际情况替换；如不清楚可用模型，请查阅官方文档。models：内部标识模型 ID 和名称，可自定义。
402 错误（Payment Required）
问题原因：
调用大模型的请求超出免费额度、账户欠费，或未绑定支付方式。
解决方法：
前往对应大模型厂商的控制台，完成账户充值或绑定支付方式。
Device Identity Required
问题原因：
OpenClaw 的 gateway 建立 WebSocket 连接时，请求 URL 未携带 device identity 身份验证信息，多因 直接通过浏览器访问 gateway 或 刷新页面 导致。
解决方法：
在 OpenClaw 插件页面，复制 完整的带 Token 的 URL 重新访问即可。
QQ 机器人无响应
可能原因：
- 未为 OpenClaw 添加 QQ 机器人的 App ID 和 App Secret。
- 填写了错误的 QQ 机器人 App ID 或 App Secret。
机器人之前正常，现在不回复
重启 OpenClaw 网关：
openclaw gateway restart