配置参考与故障排除（企业微信）

本文档提供 Docker Compose + 企业微信部署的完整配置参考和故障排除指南。这是 Docker Compose + 企业微信部署指南的配套文档。

openclaw.json 完整示例

json5

{
  // Agent 配置
  "agents": {
    "defaults": {
      "workspace": "/home/node/.openclaw/workspace",
      // 使用下方自定义模型提供商的别名
      "model": { "primary": "custom-claude/claude-sonnet-4-5-20250929" }
    }
  },

  // 自定义模型提供商
  "models": {
    "providers": {
      "custom-claude": {
        "baseUrl": "${ANTHROPIC_BASE_URL}",
        "apiKey": "${ANTHROPIC_AUTH_TOKEN}",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-sonnet-4-5-20250929",
            "name": "Claude Sonnet 4.5",
            "contextWindow": 200000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },

  // 插件配置
  "plugins": {
    "entries": {
      "wecom": {
        "enabled": true
      }
    }
  },

  // 企业微信通道
  "channels": {
    "wecom": {
      "enabled": true,
      "token": "${WECOM_TOKEN}",
      "encodingAesKey": "${WECOM_ENCODING_AES_KEY}",
      "adminUsers": [],
      "commands": {
        "enabled": true,
        "allowlist": ["/new", "/status", "/help", "/compact"]
      },
      "dynamicAgents": {
        "enabled": true
      },
      "dm": {
        "createAgentOnFirstMessage": true
      },
      "groupChat": {
        "enabled": true,
        "requireMention": true
      }
    }
  },

  // 网关配置
  "gateway": {
    "mode": "local",
    "port": 18789,
    "auth": { "token": "${OPENCLAW_GATEWAY_TOKEN}" }
  }
}

配置参考

Agents 配置

配置项	说明	默认值
`agents.defaults.workspace`	Agent 工作区路径	`~/.openclaw/workspace`
`agents.defaults.model.primary`	主模型，格式 `provider/model-id`	—

模型提供商配置

配置项	说明	默认值
`models.providers.<name>.baseUrl`	API 基地址	—
`models.providers.<name>.apiKey`	API 密钥	—
`models.providers.<name>.api`	API 协议（`anthropic-messages`、`openai` 等）	—
`models.providers.<name>.models`	可用模型列表。模型 `id` 应使用完整的带日期后缀的 ID（如 `claude-sonnet-4-5-20250929`），短别名可能导致 422 错误	—

插件配置

配置项	类型	说明	默认值
`plugins.entries.wecom.enabled`	boolean	启用插件（必填）	—

企业微信通道配置

配置项	类型	说明	默认值
`channels.wecom.enabled`	boolean	启用/禁用企业微信通道	—
`channels.wecom.token`	string	企业微信机器人 Token（必填）	—
`channels.wecom.encodingAesKey`	string	消息加密密钥，43 字符（必填）	—
`channels.wecom.adminUsers`	array	管理员用户 ID 列表（绕过命令白名单和动态路由）	`[]`
`channels.wecom.commands.enabled`	boolean	启用命令白名单	—
`channels.wecom.commands.allowlist`	array	允许的命令列表	—
`channels.wecom.dynamicAgents.enabled`	boolean	启用动态 Agent 路由	`true`
`channels.wecom.dm.createAgentOnFirstMessage`	boolean	私聊时使用动态 Agent	`true`
`channels.wecom.groupChat.enabled`	boolean	启用群聊处理	`true`
`channels.wecom.groupChat.requireMention`	boolean	群聊中是否需要 @提及	`true`

注意：CorpID、AgentID 和 Secret 在企业微信管理后台管理，不需要配置到 openclaw.json 中。企业微信回调使用 Token + EncodingAESKey 进行签名验证，不需要 Gateway Auth Token。

网关配置

配置项	说明	默认值
`gateway.mode`	网关运行模式（`"local"` 或 `"remote"`）。需设为 `"local"` 才能启动网关（Docker 镜像通过 `--allow-unconfigured` 可绕过此限制，但建议显式设置）	未设置
`gateway.port`	网关监听端口	`18789`
`gateway.auth.token`	网关认证令牌	—

更多配置项请参阅网关配置和网关配置示例。

Docker Compose 详解

完整的 docker-compose.yml

yaml

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw_wecom
    restart: unless-stopped
    network_mode: host
    env_file:
      - .env
    volumes:
      # 整个 .openclaw 目录（配置文件 + 持久化数据）
      - ./openclaw-data:/home/node/.openclaw

为什么使用 network_mode: host？ 网关绑定到容器内的 127.0.0.1，标准 Docker 端口映射（ports:）通过桥接网络转发流量，网关会拒绝非 localhost 来源的连接。使用 network_mode: host 让容器直接共享宿主机网络栈。macOS 用户需要在 Docker Desktop 设置中启用 "Enable host networking"。
企业微信回调端口：与飞书不同，企业微信使用 HTTP 回调而非 WebSocket 长连接。使用 network_mode: host 时，网关直接监听宿主机端口（默认 18789），企业微信的回调请求需要能访问该端口。确保防火墙和安全组允许企业微信服务器的入站连接。
为什么挂载整个目录而非单独文件？ 网关运行时需要在 .openclaw 目录下创建多个子目录（identity/、credentials/、canvas/ 等）并写入临时文件。单独挂载 openclaw.json 文件会导致该文件成为独立挂载点，无法被原子重命名覆盖（报 EBUSY 错误），同时容器也无法在父目录创建新文件（报 EACCES 错误）。

使用反向代理的替代方案

如果您需要通过反向代理（如 Nginx）暴露回调端口，或使用 HTTPS，可以采用以下方案：

yaml

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw_wecom
    restart: unless-stopped
    network_mode: host
    env_file:
      - .env
    volumes:
      - ./openclaw-data:/home/node/.openclaw

  nginx:
    image: nginx:alpine
    container_name: openclaw_wecom_nginx
    restart: unless-stopped
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - openclaw

以上为参考配置，Nginx 需要将 /webhooks/wecom 路径转发到 OpenClaw 网关端口。注意：/webhooks/wecom 路径不需要 Gateway Auth Token，可以配置认证豁免。

卷挂载说明

挂载	容器路径	说明
`./openclaw-data/`	`/home/node/.openclaw`	整个 OpenClaw 数据目录，包含配置文件（`openclaw.json`）、Agent 工作区（`workspace/`）、网关状态（`state/`）、Agent 会话数据（`agents/`）、身份信息（`identity/`）、凭据（`credentials/`）等

权限说明

Docker 镜像默认以 node 用户（uid 1000）运行。挂载目录必须对该用户可读写。

在 Linux 上创建并设置目录权限：

bash

mkdir -p ./openclaw-data
sudo chown -R 1000:1000 ./openclaw-data

环境变量

通过 .env 文件传递的环境变量：

变量	说明
`OPENCLAW_GATEWAY_TOKEN`	网关认证令牌
`WECOM_TOKEN`	接收消息回调验证 Token
`WECOM_ENCODING_AES_KEY`	接收消息回调加密密钥（43 字符）
`ANTHROPIC_AUTH_TOKEN`	模型 API Token
`ANTHROPIC_BASE_URL`	模型 API 基地址

在 openclaw.json 中通过 ${VAR_NAME} 语法引用环境变量。这些变量由 OpenClaw 在运行时从容器的进程环境中读取（由 Docker Compose 的 env_file 注入），而非 Docker Compose 自身的变量替换。

端口配置

默认端口为 18789。由于使用 network_mode: host，容器直接监听宿主机端口，无需 ports: 映射。如需修改端口：

更新 openclaw-data/openclaw.json 中的 gateway.port
重启容器：docker compose up -d
更新企业微信管理后台中的回调 URL 端口

多实例部署：如果同一台服务器上已运行其他 OpenClaw 实例（如飞书版 openclaw_feishu），默认端口 18789 会冲突。请为每个实例分配不同端口（如飞书用 18789，企业微信用 18790）。

故障排除

回调 URL 验证失败

症状：在企业微信管理后台保存接收消息配置时提示验证失败。

排查步骤：

确认网关已启动：docker compose logs -f，检查是否有 [gateway] listening
确认回调 URL 可访问：从外部网络尝试访问回调 URL
bash
```
curl -v http://<your-public-ip>:18789/webhooks/wecom
```
1
检查 Token 和 EncodingAESKey：确保管理后台中填写的值与 .env 文件中完全一致
检查防火墙：确保服务器防火墙和云安全组允许入站连接到端口 18789
检查内网穿透：如果使用 ngrok 等工具，确认穿透通道仍在运行

IP 白名单错误

症状：API 调用返回错误，日志中出现 IP 相关的错误信息，或消息发送/接收静默失败。

排查步骤：

检查服务器公网 IP：
bash
```
curl ifconfig.me
```
1
确认该 IP 已添加到企业微信管理后台的 企业可信IP 列表
如果使用 NAT 网关或代理，填写实际出口 IP
IP 变更后需及时更新白名单

常见陷阱：云服务器重启后公网 IP 可能会变化（如使用动态 IP）。建议使用弹性公网 IP（EIP）并绑定到服务器。

消息未收到

症状：用户在企业微信中向应用发送消息，但服务器未收到任何回调请求。

排查步骤：

确认回调 URL 已配置并验证通过 — 在应用详情页检查接收消息设置
确认应用可见范围正确 — 发送消息的用户必须在可见范围内
检查服务器网络 — 确保企业微信能访问您的回调 URL
检查容器日志 — docker compose logs -f，查看是否有收到但处理失败的请求
确认插件已加载 — openclaw plugins list 检查 wecom 是否在列表中

消息未发送

症状：收到用户消息，但回复未发送到企业微信。

排查步骤：

检查 API 权限 — 确认"消息推送"权限已开启
检查可信 IP — 确认服务器 IP 在白名单中
检查 access_token — 查看日志中是否有 token 相关错误
检查应用状态 — 确认应用未被禁用或停用

access_token 过期

症状：日志中出现 access_token expired 或 invalid access_token 错误。

企业微信的 access_token 有效期为 2 小时，过期后需要重新获取。

@sunnoy/wecom 插件自动处理 access_token 的获取和刷新。如果频繁出现此错误，可能是时钟同步问题。

排查步骤：

确认服务器时钟同步（NTP）：
bash
```
date
```
1
重启容器以强制重新获取 token：
bash
```
docker compose restart
```
1

60011 错误（无权限）

症状：API 返回错误码 60011，提示"no privilege to access/binduser"。

原因：发送消息的用户不在应用的可见范围内。

解决方案：

登录企业微信管理后台
进入 应用管理 → 选择应用
修改 可见范围，添加目标用户或部门
保存后立即生效，无需重启容器

40029 错误（不合法的 oauth_code）

症状：API 返回错误码 40029，提示"invalid code"。

原因：OAuth 授权码无效或已过期。这通常出现在需要 OAuth 认证的场景中。

排查步骤：

确认 OAuth 回调 URL 配置正确
授权码只能使用一次，确认没有重复使用
授权码有效期较短（5 分钟），确认及时使用

容器启动失败

症状：docker compose up -d 后容器立即退出，或日志中出现 Gateway failed to start: another gateway instance is already listening。

排查步骤：

检查容器日志：docker compose logs
检查 .env 文件中的变量是否正确填写
检查 openclaw.json 语法是否正确（JSON5 格式允许注释和尾逗号）
检查端口是否被占用：lsof -i :18789
多实例冲突：如果同一台服务器上已运行其他 OpenClaw 实例（如飞书版），端口 18789 会被占用。修改 openclaw.json 中的 gateway.port 为其他值（如 18790），并更新企业微信回调 URL 中的端口

权限错误（EACCES / EBUSY）

症状：日志中出现 EACCES: permission denied 或 EBUSY: resource busy or locked 错误。

EACCES：Docker 镜像以 node（uid 1000）运行。确保挂载目录权限正确：

bash

sudo chown -R 1000:1000 ./openclaw-data

EBUSY：如果您将 openclaw.json 作为单独文件挂载（而非挂载整个目录），容器无法原子替换该文件。解决方案：改为挂载整个 openclaw-data 目录（参见上方 Docker Compose 详解）。

插件未找到 / 容器重启循环

症状：日志中反复出现以下错误，容器不断重启：

plugins.entries.wecom: plugin not found: wecom
channels.wecom: unknown channel id: wecom

原因：OpenClaw 在启动时验证配置。如果 openclaw.json 中引用了尚未安装的插件，验证会失败，容器进入重启循环。

解决方案：

停止容器：docker compose down
将 openclaw.json 中的 plugins 和 channels 部分暂时移除，只保留 agents、models、gateway

使用临时容器安装插件：

bash

docker compose run --rm --entrypoint sh openclaw -c \
  "node /app/openclaw.mjs plugins install @sunnoy/wecom"

恢复完整配置（保留安装器写入的 plugins.installs 部分）
重新启动：docker compose up -d

注意：不要使用 docker compose exec 安装插件——如果容器处于重启循环中，exec 会报错 container is restarting。使用 docker compose run 可以启动一个独立的临时容器来执行命令。

EncodingAESKey 长度验证失败

症状：启动时报 EncodingAESKey 验证错误。

排查步骤：

检查配置键名：确保使用正确的键名 encodingAesKey（区分大小写）
检查长度：EncodingAESKey 必须恰好 43 个字符
bash
```
echo -n "your-key" | wc -c
```
1
检查空格/换行：确保密钥字符串首尾没有多余的空格或换行

控制面板无法访问（ERR_EMPTY_RESPONSE）

症状：浏览器打开 http://127.0.0.1:<端口>/ 时显示 ERR_EMPTY_RESPONSE 或 "didn't send any data"，但容器日志显示 [gateway] listening。

原因：网关绑定到容器内的 127.0.0.1，标准 Docker 端口映射通过桥接网络转发流量（来源 IP 不是 localhost），网关拒绝连接。

解决方案：

在 docker-compose.yml 中使用 network_mode: host（并移除 ports: 配置）
macOS 用户需在 Docker Desktop 设置中启用 "Enable host networking"（设置 → 资源 → 网络）
重新创建容器：docker compose down && docker compose up -d

控制面板显示 "unauthorized: gateway token missing"

症状：控制面板页面加载成功，但显示 WebSocket 断开连接，提示 "unauthorized: gateway token missing"。

解决方案：通过 URL 传递令牌访问控制面板：

http://127.0.0.1:<端口>/?token=<your-gateway-token>

将 <your-gateway-token> 替换为 .env 中的 OPENCLAW_GATEWAY_TOKEN 值。

模型 422 错误（model not found）

症状：发送消息时返回 HTTP 422: model not found。

原因：自定义端点不识别短模型别名。大多数自定义/代理端点需要完整的带日期后缀的模型 ID。

解决方案：在 openclaw-data/openclaw.json 中将模型 ID 更新为完整格式（如 claude-sonnet-4-5-20250929 而非 claude-3-5-sonnet），同时更新 agents.defaults.model.primary 和 models.providers.<name>.models[].id。

Docker Compose + 企业微信部署指南 — 快速开始和部署概览
企业微信应用配置详解 — 企业微信管理后台配置步骤

配置参考与故障排除（企业微信） ​

openclaw.json 完整示例 ​

配置参考 ​

Agents 配置 ​

模型提供商配置 ​

插件配置 ​

企业微信通道配置 ​

网关配置 ​

Docker Compose 详解 ​

完整的 docker-compose.yml ​

使用反向代理的替代方案 ​

卷挂载说明 ​

权限说明 ​

环境变量 ​

端口配置 ​

故障排除 ​

回调 URL 验证失败 ​

IP 白名单错误 ​

消息未收到 ​

消息未发送 ​

access_token 过期 ​

60011 错误（无权限） ​

40029 错误（不合法的 oauth_code） ​

容器启动失败 ​

权限错误（EACCES / EBUSY） ​

插件未找到 / 容器重启循环 ​

EncodingAESKey 长度验证失败 ​

控制面板无法访问（ERR_EMPTY_RESPONSE） ​

控制面板显示 "unauthorized: gateway token missing" ​

模型 422 错误（model not found） ​

返回 ​

相关文档 ​

配置参考与故障排除（企业微信）

openclaw.json 完整示例

配置参考

Agents 配置

模型提供商配置

插件配置

企业微信通道配置

网关配置

Docker Compose 详解

完整的 docker-compose.yml

使用反向代理的替代方案

卷挂载说明

权限说明

环境变量

端口配置

故障排除

回调 URL 验证失败

IP 白名单错误

消息未收到

消息未发送

access_token 过期

60011 错误（无权限）

40029 错误（不合法的 oauth_code）

容器启动失败

权限错误（EACCES / EBUSY）

插件未找到 / 容器重启循环

EncodingAESKey 长度验证失败

控制面板无法访问（ERR_EMPTY_RESPONSE）

控制面板显示 "unauthorized: gateway token missing"

模型 422 错误（model not found）

返回

相关文档