配置参考与故障排除

本文档提供 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
          }
        ]
      }
    }
  },

  // 飞书通道
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "feishu",
      "accounts": {
        "main": {
          "appId": "${FEISHU_APP_ID}",
          "appSecret": "${FEISHU_APP_SECRET}",
          "botName": "OpenClaw"
        }
      },
      "dmPolicy": "pairing",
      "groupPolicy": "open"
    }
  },

  // 网关配置
  "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 错误	—

飞书通道配置

配置项	说明	默认值
`channels.feishu.enabled`	启用/禁用飞书通道	`true`
`channels.feishu.domain`	API 域名（`feishu` 或 `lark`）	`feishu`
`channels.feishu.accounts.<id>.appId`	飞书应用 App ID	—
`channels.feishu.accounts.<id>.appSecret`	飞书应用 App Secret	—
`channels.feishu.accounts.<id>.botName`	机器人显示名称	—
`channels.feishu.accounts.<id>.domain`	单账户域名覆盖	`feishu`
`channels.feishu.dmPolicy`	私聊策略	`pairing`
`channels.feishu.allowFrom`	私聊白名单（open_id 列表）	—
`channels.feishu.groupPolicy`	群组策略	`open`
`channels.feishu.groupAllowFrom`	群组白名单	—
`channels.feishu.groups.<chat_id>.requireMention`	是否需要 @提及	`true`
`channels.feishu.groups.<chat_id>.enabled`	启用/禁用该群组	`true`
`channels.feishu.textChunkLimit`	消息分块大小	`2000`
`channels.feishu.mediaMaxMb`	媒体文件大小限制（MB）	`30`
`channels.feishu.blockStreaming`	禁用流式传输（飞书不支持消息编辑，默认等待完整回复）	`true`

网关配置

配置项	说明	默认值
`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_feishu
    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"。
为什么挂载整个目录而非单独文件？ 网关运行时需要在 .openclaw 目录下创建多个子目录（identity/、credentials/、canvas/ 等）并写入临时文件。单独挂载 openclaw.json 文件会导致该文件成为独立挂载点，无法被原子重命名覆盖（报 EBUSY 错误），同时容器也无法在父目录创建新文件（报 EACCES 错误）。

卷挂载说明

挂载	容器路径	说明
`./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`	网关认证令牌
`FEISHU_APP_ID`	飞书应用 App ID
`FEISHU_APP_SECRET`	飞书应用 App Secret
`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

故障排除

容器启动失败

症状：docker compose up -d 后容器立即退出。

排查步骤：

检查容器日志：docker compose logs
检查 .env 文件中的变量是否正确填写
检查 openclaw.json 语法是否正确（JSON5 格式允许注释和尾逗号）
检查端口 18789 是否被占用：lsof -i :18789

飞书机器人无响应

症状：在飞书中向机器人发消息，无任何回复。

排查步骤：

确认应用已发布并获批准
确认事件订阅包含 im.message.receive_v1 且已启用长连接
确认应用权限完整（参阅权限配置）
确认网关正在运行：docker compose logs -f，检查是否有 [feishu] connected 日志
检查飞书插件是否已安装

权限错误（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 详解）。

群聊中机器人无响应

症状：机器人在私聊中正常，但在群组中无响应。

排查步骤：

确认机器人已添加到群组
默认需要 @提及机器人才会响应
确认 groupPolicy 未设置为 "disabled"
检查日志中是否有群组消息的记录

插件未找到

症状：日志中出现飞书通道加载失败的错误。

飞书是 OpenClaw 的插件，需要单独安装：

bash

openclaw plugins install @openclaw/feishu

如果使用 Docker，确保镜像中已包含该插件。预构建镜像 ghcr.io/openclaw/openclaw:latest 已预装飞书插件。

控制面板无法访问（ERR_EMPTY_RESPONSE）

症状：浏览器打开 http://127.0.0.1:18789/ 时显示 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:18789/?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。

事件订阅配置失败

症状：在飞书开放平台保存长连接事件订阅时失败。

原因：网关未运行。飞书需要与网关建立 WebSocket 连接来验证事件订阅配置。

解决方案：

确保容器已启动：docker compose up -d
确认网关已就绪：docker compose logs -f（等待 [gateway] listening）
然后重新配置事件订阅

Docker Compose + 飞书部署指南 — 快速开始和部署概览
飞书应用配置详解 — 飞书开放平台配置步骤

配置参考与故障排除 ​

openclaw.json 完整示例 ​

配置参考 ​

Agents 配置 ​

模型提供商配置 ​

飞书通道配置 ​

网关配置 ​

Docker Compose 详解 ​

完整的 docker-compose.yml ​

卷挂载说明 ​

权限说明 ​

环境变量 ​

端口配置 ​

故障排除 ​

容器启动失败 ​

飞书机器人无响应 ​

权限错误（EACCES / EBUSY） ​

群聊中机器人无响应 ​

插件未找到 ​

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

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

模型 422 错误（model not found） ​

事件订阅配置失败 ​

返回 ​

相关文档 ​

配置参考与故障排除

openclaw.json 完整示例

配置参考

Agents 配置

模型提供商配置

飞书通道配置

网关配置

Docker Compose 详解

完整的 docker-compose.yml

卷挂载说明

权限说明

环境变量

端口配置

故障排除

容器启动失败

飞书机器人无响应

权限错误（EACCES / EBUSY）

群聊中机器人无响应

插件未找到

控制面板无法访问（ERR_EMPTY_RESPONSE）

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

模型 422 错误（model not found）

事件订阅配置失败

返回

相关文档