Docker（可选）

Docker 是 可选的。仅在您想要容器化网关或验证 Docker 流程时使用。

Docker 适合我吗？

  • 是：您想要隔离的、可丢弃的网关环境，或在没有本地安装的主机上运行 Clawdbot。
  • 否：您在自己的机器上运行，只想要最快的开发循环。请改用正常安装流程。
  • 沙箱说明：代理沙箱也使用 Docker，但它 不 要求完整网关在 Docker 中运行。详见 沙箱。

本指南涵盖：

  • 容器化网关（完整 Clawdbot 在 Docker 中）
  • 每会话代理沙箱（主机网关 + Docker 隔离的代理工具）

沙箱详情：沙箱

要求

  • Docker Desktop（或 Docker Engine）+ Docker Compose v2
  • 足够的磁盘空间用于镜像和日志

容器化网关（Docker Compose）

快速开始（推荐）— 使用预构建镜像

现在支持使用官方预构建的 Docker 镜像，无需从源码构建！

方式 1：使用预构建镜像（最简单）

如果您想使用预构建的镜像，设置环境变量：

bash
export OPENCLAW_IMAGE="jiulingyun803/openclaw:latest"
./docker-setup.sh

预构建镜像的优点：

  • ✅ 快速部署 — 无需本地构建，直接拉取镜像
  • ✅ 多架构支持 — 自动选择适配你的系统（amd64/arm64）
  • ✅ 更新及时 — 官方镜像定期更新最新版本
  • ✅ 减少资源占用 — 不需要在本地构建耗时又耗资源

方式 2：从源码构建（本地镜像）

从仓库根目录构建本地镜像：

bash
./docker-setup.sh

此脚本：

  • 构建网关镜像（可能耗时 10-30 分钟）
  • 运行引导向导
  • 打印可选的提供商设置提示
  • 通过 Docker Compose 启动网关
  • 生成网关令牌并写入 .env

可选环境变量：

  • OPENCLAW_DOCKER_APT_PACKAGES — 在构建期间安装额外的 apt 包
  • OPENCLAW_EXTRA_MOUNTS — 添加额外的主机绑定挂载
  • OPENCLAW_HOME_VOLUME — 在命名卷中持久化 /home/node

完成后：

  • 在浏览器中打开 http://127.0.0.1:18789/。
  • 将令牌粘贴到控制 UI（设置 → 令牌）。

它在主机上写入配置/工作空间：

  • ~/.openclaw/
  • ~/clawd

在 VPS 上运行？详见 Hetzner (Docker VPS)。

手动流程（compose）

bash
docker build -t clawdbot:local -f Dockerfile .
docker compose run --rm clawdbot-cli onboard
docker compose up -d clawdbot-gateway

环境变量配置（可选）

Docker 容器支持以下环境变量。您可以通过 .env 文件或命令行设置它们：

网关和 CLI 共享的环境变量

变量用途必需说明
CLAUDE_AI_SESSION_KEYClaude.ai 会话凭证❌用于使用 Claude AI 作为智能体后端
CLAUDE_WEB_SESSION_KEYClaude Web 会话凭证❌用于 Claude 网页版集成
CLAUDE_WEB_COOKIEClaude Web 访问令牌❌用于 Claude 网页版 Cookie 认证
OPENCLAW_GATEWAY_TOKEN网关认证令牌❌由 docker-setup.sh 自动生成
OPENCLAW_GATEWAY_BIND网关绑定地址❌默认：lan（局域网）；可设为 0.0.0.0（公开）或 localhost
OPENCLAW_GATEWAY_PORT网关监听端口❌默认：18789
OPENCLAW_BRIDGE_PORT桥接端口❌默认：18790

镜像和构建相关变量

变量用途说明
OPENCLAW_IMAGEDocker 镜像名称默认：openclaw:local；可设为预构建镜像如 jiulingyun803/openclaw:latest
OPENCLAW_DOCKER_APT_PACKAGES额外的 apt 包在镜像构建期间安装（如 ffmpeg build-essential）
OPENCLAW_EXTRA_MOUNTS额外挂载点逗号分隔的绑定挂载列表（如 $HOME/.codex:/home/node/.codex:ro)
OPENCLAW_HOME_VOLUME命名卷名称用于持久化容器 /home/node 目录

配置和工作目录

变量用途默认值
OPENCLAW_CONFIG_DIR配置目录~/.openclaw
OPENCLAW_WORKSPACE_DIR工作区目录~/clawd

设置环境变量的方法：

方法 1：使用 .env 文件（推荐）

在项目根目录创建 .env 文件：

bash
# Claude 集成（可选）
CLAUDE_AI_SESSION_KEY=your_session_key_here
CLAUDE_WEB_SESSION_KEY=your_web_session_key_here
CLAUDE_WEB_COOKIE=your_cookie_here

# 网关配置
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_GATEWAY_BIND=lan

# 镜像配置
OPENCLAW_IMAGE=jiulingyun803/openclaw:latest

然后运行 Docker Compose 命令时会自动读取这些变量。

方法 2：直接导出环境变量

bash
export CLAUDE_AI_SESSION_KEY="your_key"
export OPENCLAW_GATEWAY_PORT="18789"
docker compose run --rm openclaw-cli pairing list

方法 3：在命令行指定

bash
docker compose run -e OPENCLAW_GATEWAY_PORT=18789 --rm openclaw-cli status

关于 Claude 环境变量的说明

这三个 Claude 相关变量是可选的：

  • 何时需要：如果你要使用 Claude AI 作为网关的智能体后端
  • 何时不需要：仅使用 Feishu、Telegram 等渠道集成时，可以忽略

如果这些变量未设置，Docker 会输出以下警告（这是正常的）：

time="..." level=warning msg="The \"CLAUDE_AI_SESSION_KEY\" variable is not set. Defaulting to a blank string."
time="..." level=warning msg="The \"CLAUDE_WEB_SESSION_KEY\" variable is not set. Defaulting to a blank string."
time="..." level=warning msg="The \"CLAUDE_WEB_COOKIE\" variable is not set. Defaulting to a blank string."

这些警告不会影响渠道功能，如 Feishu、Telegram、Discord 等。

额外挂载（可选）

如果您想将额外的主机目录挂载到容器中，在运行 docker-setup.sh 之前设置 OPENCLAW_EXTRA_MOUNTS。这接受逗号分隔的 Docker 绑定挂载列表，并通过生成 docker-compose.extra.yml 将它们应用到 clawdbot-gateway 和 clawdbot-cli。

示例：

bash
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

注意：

  • 在 macOS/Windows 上，路径必须与 Docker Desktop 共享。
  • 如果您编辑 OPENCLAW_EXTRA_MOUNTS，重新运行 docker-setup.sh 以重新生成额外的 compose 文件。
  • docker-compose.extra.yml 是生成的。不要手动编辑它。

持久化整个容器 home（可选）

如果您希望 /home/node 在容器重建后持久化，通过 OPENCLAW_HOME_VOLUME 设置命名卷。 这会创建一个 Docker 卷并将其挂载到 /home/node，同时保留标准的配置/工作空间绑定挂载。 这里使用命名卷（不是绑定路径）；对于绑定挂载，使用 OPENCLAW_EXTRA_MOUNTS。

示例：

bash
export OPENCLAW_HOME_VOLUME="clawdbot_home"
./docker-setup.sh

您可以将其与额外挂载结合：

bash
export OPENCLAW_HOME_VOLUME="clawdbot_home"
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

注意：

  • 如果您更改 OPENCLAW_HOME_VOLUME，重新运行 docker-setup.sh 以重新生成额外的 compose 文件。
  • 命名卷会持久化，直到使用 docker volume rm \<name\> 删除。

安装额外的 apt 包（可选）

如果您需要镜像内的系统包（例如，构建工具或媒体库），在运行 docker-setup.sh 之前 设置 OPENCLAW_DOCKER_APT_PACKAGES。这会在镜像构建期间安装这些包，因此即使容器被删除 它们也会持久化。

示例：

bash
export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

注意：

  • 这接受空格分隔的 apt 包名列表。
  • 如果您更改 OPENCLAW_DOCKER_APT_PACKAGES，重新运行 docker-setup.sh 以重建镜像。

更快的重建（推荐）

要加速重建，调整 Dockerfile 顺序使依赖层被缓存。 这避免了除非锁文件更改否则重新运行 pnpm install：

dockerfile
FROM node:22-bookworm

# 安装 Bun（构建脚本需要）
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# 除非包元数据更改否则缓存依赖
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

CLI 服务

服务名称：openclaw-cli

通过 Docker Compose 运行 CLI 命令进行配置、调试和管理：

bash
# 查看所有可用命令
docker compose run --rm openclaw-cli --help

# 交互式配置向导
docker compose run --rm openclaw-cli onboard

# 查看当前配置
docker compose run --rm openclaw-cli config get

# 列出待审批的配对请求
docker compose run --rm openclaw-cli pairing list

# 批准飞书配对请求
docker compose run --rm openclaw-cli pairing approve feishu <pairing_code>

渠道设置（可选）

使用 CLI 容器配置渠道，然后根据需要重启网关。

WhatsApp（QR）：

bash
docker compose run --rm openclaw-cli channels login

Telegram（机器人令牌）：

bash
docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

Discord（机器人令牌）：

bash
docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Feishu（飞书）：

bash
# 使用引导向导设置
docker compose run --rm openclaw-cli onboard

# 或直接配置
docker compose run --rm openclaw-cli config set channels.feishu.accounts[].appId "<app_id>"
docker compose run --rm openclaw-cli config set channels.feishu.accounts[].appSecret "<app_secret>"

文档：WhatsApp、Telegram、Discord、Feishu

健康检查和调试

bash
# 检查网关健康状态
docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

# 查看实时日志
docker compose logs -f openclaw-gateway

# 查看 CLI 日志
docker compose logs -f openclaw-cli

# 检查渠道状态
docker compose run --rm openclaw-cli channels status

# 运行医生诊断
docker compose run --rm openclaw-cli doctor

常用 CLI 命令参考

命令说明
pairing list列出待审批的配对请求
pairing approve \<channel\> <code>批准配对请求
config get查看当前配置
config set \<key\> \<value\>设置配置值
config set gateway.controlUi.allowInsecureAuth true允许 Web UI 不安全认证（见下文常见问题）
channels status查看所有渠道状态
channels loginWhatsApp QR 登录
channels add --channel \<name\> --token \<token\>添加新渠道
doctor运行诊断检查
logs查看网关日志
dashboard打开控制面板 URL

E2E 冒烟测试（Docker）

bash
scripts/e2e/onboard-docker.sh

QR 导入冒烟测试（Docker）

bash
pnpm test:docker:qr

容器服务说明

本项目提供两个主要的 Docker Compose 服务：

服务用途命令
openclaw-gateway后台网关服务（持续运行）docker compose up -d openclaw-gateway
openclaw-cli交互式 CLI 工具（一次性命令）docker compose run --rm openclaw-cli \<command\>

注意

  • 网关绑定默认为 lan 用于容器使用。
  • 网关容器是会话的权威来源（~/.openclaw/agents/\<agentId\>/sessions/）。
  • CLI 容器与网关共享配置目录（~/.openclaw），任何通过 CLI 进行的配置更改都会立即在网关中生效。

代理沙箱（主机网关 + Docker 工具）

深入了解：沙箱

功能说明

当 agents.defaults.sandbox 启用时，非主会话 在 Docker 容器内运行工具。 网关保持在您的主机上，但工具执行是隔离的：

  • scope：默认为 "agent"（每个代理一个容器 + 工作空间）
  • scope："session" 用于每会话隔离
  • 每范围的工作空间文件夹挂载在 /workspace
  • 可选的代理工作空间访问（agents.defaults.sandbox.workspaceAccess）
  • 允许/拒绝工具策略（拒绝优先）
  • 入站媒体被复制到活动沙箱工作空间（media/inbound/*）以便工具可以读取（使用 workspaceAccess: "rw" 时，这会落在代理工作空间中）

警告：scope: "shared" 禁用跨会话隔离。所有会话共享一个容器和一个工作空间。

每代理沙箱配置文件（多代理）

如果您使用多代理路由，每个代理可以覆盖沙箱 + 工具设置： agents.list[].sandbox 和 agents.list[].tools（加上 agents.list[].tools.sandbox.tools）。 这让您可以在一个网关中运行混合访问级别：

  • 完全访问（个人代理）
  • 只读工具 + 只读工作空间（家庭/工作代理）
  • 无文件系统/shell 工具（公共代理）

详见 多代理沙箱与工具 了解示例、优先级和故障排除。

默认行为

  • 镜像：clawdbot-sandbox:bookworm-slim
  • 每个代理一个容器
  • 代理工作空间访问：workspaceAccess: "none"（默认）使用 ~/.openclaw/sandboxes
    • "ro" 保持沙箱工作空间在 /workspace 并以只读方式挂载代理工作空间在 /agent（禁用 write/edit/apply_patch）
    • "rw" 以读写方式挂载代理工作空间在 /workspace
  • 自动清理：空闲 > 24 小时 或 存在时间 > 7 天
  • 网络：默认为 none（如需出站访问请明确启用）
  • 默认允许：exec、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
  • 默认拒绝：browser、canvas、nodes、cron、discord、gateway

启用沙箱

如果您计划在 setupCommand 中安装包，请注意：

  • 默认 docker.network 是 "none"（无出站）。
  • readOnlyRoot: true 阻止包安装。
  • user 必须是 root 才能运行 apt-get（省略 user 或设置 user: "0:0"）。 Clawdbot 在 setupCommand（或 docker 配置）更改时自动重建容器，除非容器 最近使用过 （约 5 分钟内）。热容器会记录警告，带有确切的 clawdbot sandbox recreate ... 命令。
json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared（默认为 agent）
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "clawdbot-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "clawdbot-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"]
        },
        prune: {
          idleHours: 24, // 0 禁用空闲清理
          maxAgeDays: 7  // 0 禁用最大存在时间清理
        }
      }
    }
  },
  tools: {
    sandbox: {
      tools: {
        allow: ["exec", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
      }
    }
  }
}

加固选项位于 agents.defaults.sandbox.docker 下： network、user、pidsLimit、memory、memorySwap、cpus、ulimits、 seccompProfile、apparmorProfile、dns、extraHosts。

多代理：通过 agents.list[].sandbox.{docker,browser,prune}.* 覆盖每个代理的 agents.defaults.sandbox.{docker,browser,prune}.* （当 agents.defaults.sandbox.scope / agents.list[].sandbox.scope 为 "shared" 时忽略）。

构建默认沙箱镜像

bash
scripts/sandbox-setup.sh

这使用 Dockerfile.sandbox 构建 clawdbot-sandbox:bookworm-slim。

沙箱通用镜像（可选）

如果您想要带有通用构建工具（Node、Go、Rust 等）的沙箱镜像，构建通用镜像：

bash
scripts/sandbox-common-setup.sh

这构建 clawdbot-sandbox-common:bookworm-slim。要使用它：

json5
{
  agents: { defaults: { sandbox: { docker: { image: "clawdbot-sandbox-common:bookworm-slim" } } } }
}

沙箱浏览器镜像

要在沙箱内运行浏览器工具，构建浏览器镜像：

bash
scripts/sandbox-browser-setup.sh

这使用 Dockerfile.sandbox-browser 构建 clawdbot-sandbox-browser:bookworm-slim。 容器运行启用 CDP 的 Chromium 和可选的 noVNC 观察器（通过 Xvfb 实现有头模式）。

注意：

  • 有头模式（Xvfb）比无头模式减少机器人封锁。
  • 仍可通过设置 agents.defaults.sandbox.browser.headless=true 使用无头模式。
  • 不需要完整桌面环境（GNOME）；Xvfb 提供显示。

使用配置：

json5
{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true }
      }
    }
  }
}

自定义浏览器镜像：

json5
{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-clawdbot-browser" } }
    }
  }
}

启用后，代理会收到：

  • 沙箱浏览器控制 URL（用于 browser 工具）
  • noVNC URL（如果启用且 headless=false）

记住：如果您使用工具允许列表，添加 browser（并从拒绝中删除）否则工具仍被阻止。 清理规则（agents.defaults.sandbox.prune）也适用于浏览器容器。

自定义沙箱镜像

构建您自己的镜像并将配置指向它：

bash
docker build -t my-clawdbot-sbx -f Dockerfile.sandbox .
json5
{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-clawdbot-sbx" } }
    }
  }
}

工具策略（允许/拒绝）

  • deny 优先于 allow。
  • 如果 allow 为空：所有工具（除了 deny）都可用。
  • 如果 allow 非空：只有 allow 中的工具可用（减去 deny）。

清理策略

两个选项：

  • prune.idleHours：移除 X 小时未使用的容器（0 = 禁用）

预构建 Docker 镜像

本项目现在提供官方的预构建 Docker 镜像，支持多架构部署。

支持的架构

预构建镜像支持以下架构：

  • linux/amd64 — Intel/AMD 64位处理器（大多数服务器和现代电脑）
  • linux/arm64 — ARM 64位处理器（Apple Silicon Mac、树莓派 4/5、华为云鲲鹏等）

Docker 会自动选择匹配你系统的镜像版本。

镜像标签

标签说明更新频率
latest最新稳定版本每次推送到 main 分支
vX.Y.Z特定版本每次发布新版本标签
main-XXXXX开发版本每次提交到 main 分支

快速开始（使用预构建镜像）

最简单的方法是使用预构建镜像：

bash
# 1. 使用官方预构建镜像
export OPENCLAW_IMAGE="jiulingyun803/openclaw:latest"

# 2. 运行一键部署脚本
./docker-setup.sh

# 3. 在浏览器中打开 http://127.0.0.1:18789/
# 4. 复制并粘贴网关令牌到控制界面

手动运行预构建镜像

如果你希望更细致的控制，可以手动运行：

bash
# 拉取镜像
docker pull jiulingyun803/openclaw:latest

# 运行网关
docker run -d \
  --name openclaw-gateway \
  -p 18789:18789 \
  -e HOME=/home/node \
  -v ~/.openclaw:/home/node/.openclaw \
  -v ~/clawd:/home/node/clawd \
  jiulingyun803/openclaw:latest \
  node dist/index.js gateway --bind 0.0.0.0 --port 18789

使用 Docker Compose

编辑 .env 文件：

bash
OPENCLAW_IMAGE=jiulingyun803/openclaw:latest

然后运行：

bash
docker compose up -d openclaw-gateway

构建和发布你自己的镜像

如果你想对预构建镜像进行自定义或发布到你自己的 Docker Hub 账户：

  1. 确保你有 Docker Hub 账户
  2. 按照 Docker Hub 预构建镜像配置指南 设置 GitHub Actions
  3. GitHub Actions 会自动为你的每个推送和版本发布构建和推送多架构镜像

镜像大小和性能

  • 镜像大小 — 约 500-600 MB（包含完整运行环境）
  • 首次启动 — 第一次拉取镜像约需 2-5 分钟（取决于网络速度）
  • 后续启动 — 使用本地缓存，启动时间 < 10 秒
  • 内存占用 — 运行时约 100-200 MB

生产环境部署

对于生产环境，建议：

  1. 使用特定版本标签 — 不要使用 latest，而是指定如 v2026.1.31
  2. 启用容器重启策略 — restart: unless-stopped
  3. 设置资源限制 — 限制 CPU 和内存
  4. 启用日志轮转 — 防止日志文件过大
  5. 监控容器健康 — 使用 healthcheck 指令

示例 docker-compose 生产配置：

yaml
services:
  openclaw-gateway:
    image: jiulingyun803/openclaw:v2026.1.31
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ~/.openclaw:/home/node/.openclaw
      - ~/clawd:/home/node/clawd
    environment:
      NODE_ENV: production
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 512M
        reservations:
          cpus: '1'
          memory: 256M
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

故障排查

镜像拉取失败

bash
# 检查镜像是否存在
docker pull jiulingyun803/openclaw:latest

# 如果失败，检查仓库是否公开，或尝试本地构建
./docker-setup.sh

ARM64 兼容性问题

如果在 ARM64 系统（如树莓派）上遇到问题：

  1. 确保 Docker 已更新到最新版本
  2. 验证镜像拉取时自动选择了 ARM64 版本：
    bash
    docker inspect jiulingyun803/openclaw:latest | grep -i architecture
  3. 如果上述步骤不成功，使用本地构建：
    bash
    ./docker-setup.sh

权限错误

类型 1：无法连接 Docker daemon（套接字权限不足）

症状：

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

解决（Linux）：

bash
# 将当前用户添加到 docker 组
sudo usermod -aG docker $USER

# 刷新组成员关系（无需重启）
newgrp docker

# 验证
docker ps

newgrp docker 仅对当前终端生效；永久生效需退出重新登录。macOS/Windows 上请确认 Docker Desktop 正在运行。

类型 2：容器内文件权限不足（EACCES）

症状：

Error: EACCES: permission denied, mkdir '/home/node/.openclaw/...'

原因：宿主机挂载目录由 root 创建，但容器以 node:node（UID 1000）运行，无写权限。

解决：

bash
# 创建目录并设置正确所有者
mkdir -p ./data/.openclaw ./data/clawd
chown -R 1000:1000 ./data

更多信息

详见：

示例：

  • 保留忙碌会话但限制生命周期： idleHours: 24，maxAgeDays: 7
  • 永不清理： idleHours: 0，maxAgeDays: 0

安全说明

  • 硬墙仅适用于 工具（exec/read/write/edit/apply_patch）。
  • 仅主机工具如 browser/camera/canvas 默认被阻止。
  • 在沙箱中允许 browser 会破坏隔离（浏览器在主机上运行）。

常见问题（FAQ）

Web UI 显示 "disconnected (1008): pairing required" 错误

问题表现

在浏览器中访问 Web UI（http://127.0.0.1:18789/?token=...）时，收到错误：

disconnected (1008): pairing required

同时 Feishu、Telegram 等渠道能正常工作，表明网关运行正常。

原因

Docker 中的 Web UI 连接采用不同的认证路径：

  • 本地 npm 模式：浏览器连接被识别为真正的本地连接 → 自动允许，跳过配对检查
  • Docker 模式：即使是 127.0.0.1 的浏览器连接也被视为网络连接 → 需要显式配置允许 Web UI 不安全认证

这是因为 WebSocket 连接经过容器网络栈的处理，因此需要 gateway.controlUi.allowInsecureAuth 配置项来告诉网关允许基于令牌的 Web UI 认证。

解决方案

启用 Web UI 不安全认证配置：

bash
# 执行一次性配置命令
docker compose run --rm openclaw-cli config set gateway.controlUi.allowInsecureAuth true

# 重启网关使配置生效
docker compose restart openclaw-gateway

# 等待几秒钟，然后在浏览器中重新打开 Web UI

验证配置已保存：

bash
cat ~/.openclaw/openclaw.json | grep -A 2 controlUi

应该看到：

json
"controlUi": {
  "allowInsecureAuth": true
},

为什么这很安全？

  • gateway.bind=loopback 限制了网关只在本地访问
  • 即使启用 allowInsecureAuth，仍然需要有效的网关令牌（OPENCLAW_GATEWAY_TOKEN）
  • 令牌由 docker-setup.sh 自动生成并安全存储

如果仍然不工作？

详见网关专题文档：配对要求故障排除

故障排除步骤：

  1. 检查令牌

    bash
    # 获取令牌
cat ~/.openclaw/openclaw.json | grep -A 1 '"auth"'

# 验证 Web UI URL 中包含正确的令牌
# 格式: http://127.0.0.1:18789/?token=<token>

  2. 查看网关日志

    bash
    docker compose logs -f openclaw-gateway | grep -i "control ui\|pairing"

  3. 重新启动网关

    bash
    docker compose restart openclaw-gateway
sleep 3
docker compose logs openclaw-gateway | tail -20

故障排除

  • 镜像缺失：使用 scripts/sandbox-setup.sh 构建或设置 agents.defaults.sandbox.docker.image。
  • 容器未运行：它会按需自动创建每个会话。
  • 沙箱中的权限错误：将 docker.user 设置为与挂载的工作空间所有权匹配的 UID:GID（或 chown 工作空间文件夹）。
  • 网关/CLI 容器权限错误（EACCES: permission denied, mkdir '/home/node/.openclaw/...'）：容器以 node:node（UID 1000）运行，宿主机挂载目录必须对 UID 1000 可写。运行 mkdir -p ./data/.openclaw ./data/clawd && chown -R 1000:1000 ./data 修复。
  • 找不到自定义工具：Clawdbot 使用 sh -lc（登录 shell）运行命令，这会 source /etc/profile 并可能重置 PATH。设置 docker.env.PATH 以在前面添加您的自定义工具路径（例如，/custom/bin:/usr/local/share/npm-global/bin），或在 Dockerfile 中的 /etc/profile.d/ 下添加脚本。
上一节：Docker 快速部署
下一节：Nix