Skip to content
宝塔面板官方文档

OpenClaw 常见错误与故障排查

宝塔面板（BT Panel）OpenClaw 插件在安装、初始化、运行及使用过程中常见问题的排查与解决方案，含各大模型厂商 API 地址、插件升级、Docker 重启等。

更新于 查看 Markdown

OpenClaw 常见错误排查

本文档整理了 OpenClaw 在安装、初始化、运行及使用过程中的常见问题与解决方案，帮助用户快速定位并解决问题。

各大模型厂商 API 地址

注意： Base URL 地址需兼容 OpenAI API 协议。

火山方舟

Base URL：

https://ark.cn-beijing.volces.com/api/v3

详情参考火山方舟官方文档。

DeepSeek

Base URL：

https://api.deepseek.com/v1

详情参考DeepSeek 官方文档。

阿里云百炼

Base URL：

https://dashscope.aliyuncs.com/compatible-mode/v1

模型 ID 获取地址：阿里云百炼模型广场。

详情参考阿里云百炼文档。

Coding Plan Base URL：

https://coding.dashscope.aliyuncs.com/v1

模型 ID 获取方式参考 Coding Plan 官方文档。

月之暗面（Kimi）

Base URL：

https://api.moonshot.cn/v1

详情参考月之暗面官方文档。

联通元景

Base URL：

https://maas-api.ai-yuanjing.com/openapi/compatible-mode/v1

详情参考联通元景官方文档。

基础问题排查

当 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": {
      "default1": {
        "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": "default1/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

搜索文件位置

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

find / -name SOUL.md 2>/dev/null
编辑此页
Navigation

Type to search…

↑↓ navigate↵ selectEsc close