跳到主要内容
版本：latest

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

模型 ID 获取地址：https://help.aliyun.com/zh/model-studio/coding-plan?spm=a2c4g.11186623.help-menu-2400256.d_0_2_0.5e5f689dlJE7MO&scm=20140722.H_3005961._.OR_help-T_cn~zh-V_1

月之暗面（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 服务异常

解决方案：

执行 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。

初始化失败​

初始化失败

排查思路：

  1. 检查容器拉取是否正常

    执行 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，查看镜像拉取是否成功。

    拉取不成功时，尝试设置镜像加速源后重试。

  2. 安装应用时不勾选自动初始化

    此步骤用于排查是否因系统资源不足，导致初始化进程被系统终止。

  3. 手动执行初始化命令

    若上一步安装成功，说明是系统资源不足导致初始化失败，需手动执行初始化命令。

    进入容器后，执行 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）​

问题原因：

  • 请求参数错误、配置项缺失或语法无效。
  • 调用大模型时使用了无效的模型名。
  • 请求上下文过长或发送了空提示语。

解决方法：

  1. 核对模型名是否与厂商官方一致，确保无拼写错误。
  2. 精简上下文内容，避免超出厂商限制。
  3. 检查请求配置，补充缺失的参数，确保无空提示，参数格式兼容 OpenAI API 协议。

401 错误（Unauthorized）​

报错信息：

  • Unauthorized（未经授权）
  • Invalid Access Token or Token Expired（无效 Token 或 Token 过期）

问题原因：

  • API Key 不正确、已过期或已删除。
  • Base URL 填写错误。
  • 模型 ID 填写错误。

解决方案：

检查 OpenClaw 配置，修改后需重建容器或重启网关。

  • 通过插件查看，检查以下项目：

    1. API 地址是否正确。
    2. 密钥是否有效或填写正确。
    3. 模型名称是否正确。

    查看插件配置

  • 通过配置文件查看：面板安装的 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​

Device Identity Required 报错

问题原因：

OpenClaw 的 gateway 建立 WebSocket 连接时，请求 URL 未携带 device identity 身份验证信息，多因 直接通过浏览器访问 gateway 或 刷新页面 导致。

解决方法：

在 OpenClaw 插件页面，复制 完整的带 Token 的 URL 重新访问即可。

复制带 Token 的 URL（步骤一） 复制带 Token 的 URL（步骤二）

QQ 机器人无响应​

可能原因：

  • 未为 OpenClaw 添加 QQ 机器人的 App ID 和 App Secret。
  • 填写了错误的 QQ 机器人 App ID 或 App Secret。

机器人之前正常，现在不回复

重启 OpenClaw 网关：

openclaw gateway restart

修改容器内配置文件​

OpenClaw 的角色设定、身份信息和 Agent 配置分别存储在容器内的以下文件中：

  • SOUL.md：角色设定文件
  • IDENTITY.md：身份信息文件
  • AGENTS.md：Agent 配置文件

文件默认路径​

配置文件的默认目录为：

/home/node/clawd/

进入容器​

通过 OpenClaw 插件安装的应用运行在 Docker 容器中，需要先以 root 身份进入容器：

docker exec -it -u root <容器ID> /bin/bash

查看容器 ID 可执行：

docker ps

编辑配置文件​

进入容器后，使用文本编辑器修改文件。以下以 nano 为例：

nano /home/node/clawd/SOUL.md
nano /home/node/clawd/IDENTITY.md
nano /home/node/clawd/AGENTS.md
提示

如容器内无 nano，可使用 vi 编辑器。修改完成后记得保存文件。

搜索文件位置​

如不确定文件的实际路径，可在容器内执行以下命令搜索：

find / -name SOUL.md 2>/dev/null