OpenClaw 是一个可接入飞书、企业微信、钉钉、Telegram、Discord、WhatsApp 等通道的个人 AI 助理网关。官方提供两种容器化方式：仓库自带的 scripts/docker/setup.sh（官方推荐，自动完成镜像、onboarding、Compose 启动），以及直接使用预构建镜像的最小 Compose。本文两种都给，国内拉取镜像的坑也一并说明。

一、准备工作

• Docker Engine + Compose v2（见本系列《安装 Docker》）。
• 预构建镜像不需要本地编译；若从源码构建镜像，主机至少 6 GB 内存。
• 一个模型供应商 API Key（OpenAI、火山引擎、DeepSeek、Kimi、MiniMax 等均可，onboarding 之后在配置里加）。
• 默认控制台端口 18789。

二、方式 A：官方 setup.sh（推荐）

git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 使用预构建镜像，避免本地编译（二选一）：
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"     # GHCR，海外优先
# export OPENCLAW_IMAGE="openclaw/openclaw:latest"           # Docker Hub 镜像

# 国内主机如果 ghcr.io 拉不动，先从加速器拉到本地再打标：
# docker pull docker.m.daocloud.io/openclaw/openclaw:latest
# docker tag  docker.m.daocloud.io/openclaw/openclaw:latest openclaw/openclaw:latest
# export OPENCLAW_IMAGE="openclaw/openclaw:latest"

./scripts/docker/setup.sh

脚本会自动完成：拉取/构建镜像 → 生成 .env（含网关 token）→ onboarding（引导填模型 Key、网关鉴权）→ docker compose up -d 启动。

完成后：

# 打印 Control UI 地址（http://127.0.0.1:18789，首次打开用 .env 里的 token 配对）
docker compose run --rm openclaw-cli dashboard --no-open

无人值守的纯命令行 onboarding（Headless）可以参考官方文档的 non-interactive 流程，把 OPENAI_API_KEY、OPENCLAW_GATEWAY_TOKEN、各通道机器人凭据放进 .env 后用 onboard --non-interactive 完成。

三、方式 B：最小 docker-compose.yml

不想拉整个源码仓库，可以直接用预构建镜像写一份最小栈。配置、工作区、鉴权密钥目录全部持久化，镜像内服务以 uid 1000 运行。

目录与权限

sudo mkdir -p /opt/openclaw/{config,workspace,auth}
sudo chown -R 1000:1000 /opt/openclaw

.env（600）

umask 077
cat > /opt/openclaw/.env <<'EOF'
# 网关 Control UI 配对 token：openssl rand -hex 32 生成
OPENCLAW_GATEWAY_TOKEN=替换为64位随机十六进制
# 模型供应商 Key（示例；也可 onboarding 后在 openclaw.json 里配多家）
OPENAI_API_KEY=替换为你的APIKey
OPENCLAW_TZ=Asia/Shanghai
EOF
chmod 600 /opt/openclaw/.env

docker-compose.yml

name: openclaw

services:
  openclaw:
    # 国内拉不动时：从 docker.m.daocloud.io/openclaw/openclaw 拉取后 retag 成本名
    image: openclaw/openclaw:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    env_file:
      - .env
    ports:
      # 只绑回环：用 SSH 隧道或前置 HTTPS 反代访问，不要裸暴露公网
      - "127.0.0.1:18789:18789"
    volumes:
      - ./config:/home/node/.openclaw                 # openclaw.json、state、会话
      - ./workspace:/home/node/.openclaw/workspace   # 工作区文件
      - ./auth:/home/node/.config/openclaw          # 本地加密密钥目录
    extra_hosts:
      - "host.docker.internal:host-gateway"        # 容器内访问宿主上的 Ollama/LM Studio
    security_opt:
      - no-new-privileges:true
    mem_limit: 1g
    logging:
      driver: json-file
      options: { max-size: "20m", max-file: "3" }

持久化的三个目录各司其职：config 存 openclaw.json、共享 SQLite 状态和各 agent 数据；workspace 是助理读写文件的地方；auth 存放 OAuth token 的本地加密主密钥，要和 config 一起备份、分开授权。

初始化 onboarding

cd /opt/openclaw
docker compose up -d
# 交互式初始化（本地模式，不在容器内装系统级 daemon）：
docker compose run --rm --entrypoint node openclaw \
  dist/index.js onboard --mode local --no-install-daemon
docker compose restart openclaw

纯无头环境（无 TTY）用非交互模式：

docker compose run -T --rm --entrypoint node openclaw \
  dist/index.js onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice openai-api-key \
  --secret-input-mode ref \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
  --skip-channels \
  --no-install-daemon
docker compose up -d

之后接入飞书/钉钉/企微/Telegram 等通道，按对应通道的指引把机器人凭据加进配置或环境变量即可，配置文件支持热加载，改完无需重启。

四、验证

docker compose ps

# 三个健康探针（容器内/隧道内免鉴权）：
curl -fsS http://127.0.0.1:18789/healthz    # 存活
curl -fsS http://127.0.0.1:18789/startupz   # 启动完成、可接流量
curl -fsS http://127.0.0.1:18789/readyz     # 深度就绪（含通道状态）

浏览器访问 Control UI：先在本机建隧道 ssh -L 18789:127.0.0.1:18789 user@203.0.113.10，再开 http://127.0.0.1:18789/，粘贴 .env 中的 OPENCLAW_GATEWAY_TOKEN 完成设备配对。

公网使用时放在 Nginx/Caddy 后面上 HTTPS（参考本系列 Nginx 文章），不要把 18789 直接挂到公网 HTTP。

五、日常运维与升级

docker compose logs -f openclaw
docker compose restart openclaw
docker compose pull && docker compose up -d     # 升级；状态在 bind mount 中，不丢

新版镜像启动时会自动执行安全的迁移与插件收敛。如果容器因无法自愈而反复退出，可用同一镜像挂载相同状态执行一次修复，再恢复正常启动：

docker run --rm -v /opt/openclaw/config:/home/node/.openclaw \
  openclaw/openclaw:latest openclaw doctor --fix
docker compose up -d

六、常见问题