# OpenClaw 常见错误与故障排查

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

# 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 出现异常时，首先查看日志是否有报错。

![查看日志](https://docs.bt.cn/img/faq/openclaw-troubleshooting/image-20260312231507794.png)

如需进入未启动的 OpenClaw 容器进行排查，可执行以下命令：

```bash
docker-compose -f /www/dk_project/dk_app/dk_openclaw/docker-compose.yml run --rm --entrypoint /bin/bash -u root openclaw-cli
```

进入容器后，执行以下命令进行诊断：

```bash
openclaw health     # 检查系统健康状态
openclaw status     # 查看服务运行状态
openclaw doctor     # 自动诊断常见问题
```

## 安装问题

### 插件未安装

![插件未安装](https://docs.bt.cn/img/faq/openclaw-troubleshooting/image-20260312024600805.png)

**解决方案：**

重新安装插件。可能因网络波动等原因导致安装不完整。

### docker-compose 服务异常

![docker-compose 服务异常](https://docs.bt.cn/img/faq/openclaw-troubleshooting/image-20260310224154626.png)

**解决方案：**

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

### 初始化失败

![初始化失败](https://docs.bt.cn/img/faq/openclaw-troubleshooting/image-20260310231010497.png)

**排查思路：**

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`：

   ![手动执行初始化](https://docs.bt.cn/img/faq/openclaw-troubleshooting/image-20260311015430884.png)

> 建议服务器配置为 2 核 4G，以获得更佳体验。

### 终极方案

当上述操作均无法安装成功时，删除 OpenClaw 插件，更新软件商店列表，重新安装。

> 前提是没有重要数据。如有重要数据，请加 QQ 群 574292667 联系管理员协助处理。

## 使用问题

### LLM 请求超时（LLM request time out）

**问题原因：**

请求大模型超时，通常由网络问题或请求上下文过大导致。

**解决方案：**

请求大模型地址，检查连通性：

```bash
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：

  ```bash
  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. 模型名称是否正确。

  ![查看插件配置](https://docs.bt.cn/img/faq/openclaw-troubleshooting/image-20260312221240386.png)

- 通过配置文件查看：面板安装的 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 报错](https://docs.bt.cn/img/faq/openclaw-troubleshooting/image-20260311020912296.png)

**问题原因：**

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

**解决方法：**

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

![复制带 Token 的 URL（步骤一）](https://docs.bt.cn/img/faq/openclaw-troubleshooting/image-20260311021057551.png)
![复制带 Token 的 URL（步骤二）](https://docs.bt.cn/img/faq/openclaw-troubleshooting/image-20260311021159129.png)

### QQ 机器人无响应

**可能原因：**

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

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

重启 OpenClaw 网关：

```bash
openclaw gateway restart
```

### 修改容器内配置文件

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

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

#### 文件默认路径

配置文件的默认目录为：

```
/home/node/clawd/
```

#### 进入容器

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

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

查看容器 ID 可执行：

```bash
docker ps
```

#### 编辑配置文件

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

```bash
nano /home/node/clawd/SOUL.md
nano /home/node/clawd/IDENTITY.md
nano /home/node/clawd/AGENTS.md
```

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

#### 搜索文件位置

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

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