OpenClaw Docker Compose 部署完整指南

目录前置要求快速部署推荐手动部署步骤配置通讯渠道健康检查高级配置常用管理命令故障排查安全加固持久化说明一、前置要求必需软件Docker DesktopWindows/macOS或Docker EngineDocker Compose v2Linux系统资源至少 2GB RAM防止构建时 OOM10GB 可用磁盘空间网络需要访问 GitHub Container Registry 和 npm 仓库可选但推荐Node.js 24用于本地开发和 CLI 操作pnpm 10.23.0包管理器二、快速部署推荐这是最简单的方式脚本会自动完成所有配置# 1. 克隆项目gitclone https://github.com/openclaw/openclaw.gitcdopenclaw# 2. 运行设置脚本./scripts/docker/setup.sh脚本会自动✅ 构建 Docker 镜像✅ 生成 Gateway Token✅ 运行 Onboarding 向导✅ 启动 Gateway 服务✅ 配置必要的环境变量访问控制 UI打开浏览器访问http://127.0.0.1:18789/将终端显示的 token 粘贴到 Settings 中即可。三、手动部署步骤如果您想完全控制部署过程步骤 1构建 Docker 镜像方式 A本地构建cdopenclawdockerbuild-topenclaw:local-fDockerfile.方式 B使用预构建镜像exportOPENCLAW_IMAGEghcr.io/openclaw/openclaw:latestdockerpull$OPENCLAW_IMAGE 预构建镜像地址https://github.com/openclaw/openclaw/pkgs/container/openclaw[main](file://d:\project\openclaw\scripts\ui.js#L161-L193) - 主分支最新[latest](file://d:\project\openclaw\src\cli\gateway-cli\register.ts#L76-L76) - 最新稳定版version- 特定版本如2026.2.26步骤 2准备环境变量创建 [.env](file://d:\project\openclaw\openclaw.podman.env) 文件# 基础配置OPENCLAW_CONFIG_DIR$HOME/.openclawOPENCLAW_WORKSPACE_DIR$HOME/.openclaw/workspaceOPENCLAW_GATEWAY_PORT18789OPENCLAW_BRIDGE_PORT18790OPENCLAW_GATEWAY_BINDlanOPENCLAW_TZAsia/Shanghai# 认证 Token可选不设置则自动生成OPENCLAW_GATEWAY_TOKENyour-secret-token-here# 镜像配置OPENCLAW_IMAGEopenclaw:local# 沙箱配置可选OPENCLAW_SANDBOXOPENCLAW_DOCKER_SOCKET/var/run/docker.sock# 额外配置可选OPENCLAW_EXTRA_MOUNTSOPENCLAW_HOME_VOLUMEOPENCLAW_DOCKER_APT_PACKAGESOPENCLAW_EXTENSIONS步骤 3初始化配置目录# 创建目录结构mkdir-p$OPENCLAW_CONFIG_DIRmkdir-p$OPENCLAW_WORKSPACE_DIRmkdir-p$OPENCLAW_CONFIG_DIR/identitymkdir-p$OPENCLAW_CONFIG_DIR/agents/main/agentmkdir-p$OPENCLAW_CONFIG_DIR/agents/main/sessions步骤 4运行 Onboardingdockercompose run--rm--no-deps--entrypointnodeopenclaw-gateway\dist/index.js onboard--modelocal--no-install-daemon按照提示完成选择 AI 提供商OpenAI、Anthropic 等输入 API Key配置模型偏好步骤 5配置 Gateway# 设置 Gateway 模式为 localdockercompose run--rm--no-deps--entrypointnodeopenclaw-gateway\dist/index.js configsetgateway.modelocal# 设置绑定地址为 lan允许主机访问dockercompose run--rm--no-deps--entrypointnodeopenclaw-gateway\dist/index.js configsetgateway.bind lan# 配置 Control UI 允许的源重要dockercompose run--rm--no-deps--entrypointnodeopenclaw-gateway\dist/index.js configsetgateway.controlUi.allowedOrigins\[http://localhost:18789,http://127.0.0.1:18789]--strict-json步骤 6启动 Gatewaydockercompose up-dopenclaw-gateway步骤 7验证安装# 查看日志dockercompose logs-fopenclaw-gateway# 健康检查curl-fsShttp://127.0.0.1:18789/healthz# 就绪检查curl-fsShttp://127.0.0.1:18789/readyz看到 [ok](file://d:\project\openclaw\ui\src\ui\app-chat.ts#L107-L107) 表示成功四、配置通讯渠道WhatsApp二维码登录dockercompose run--rmopenclaw-cli channels login扫描二维码后WhatsApp 设备即连接成功。TelegramBot Token在 BotFather 创建 Bot获取 Tokendockercompose run--rmopenclaw-cli channelsadd\--channeltelegram\--token123456:ABCDEF-GHIJKLMNOPQRSTUVWXYZDiscordBot Token在 Discord Developer Portal 创建应用创建 Bot 并获取 Token邀请 Bot 到您的服务器dockercompose run--rmopenclaw-cli channelsadd\--channeldiscord\--tokenMTIzNDU2Nzg5MDEyMzQ1Njc4OQ.GJKLmN.OpQrStUvWxYzAbCdEfGhIjKlMnOpQrStUvWxSlack# 需要设置两个环境变量exportSLACK_BOT_TOKENxoxb-your-bot-tokenexportSLACK_APP_TOKENxapp-your-app-tokendockercompose run--rmopenclaw-cli channelsadd\--channelslackSignal需要先安装signal-cli然后配置dockercompose run--rmopenclaw-cli channelsadd\--channelsignal\--phone[phone]五、健康检查基础检查无需认证# Liveness probe存活检查curl-fsShttp://127.0.0.1:18789/healthz# Readiness probe就绪检查curl-fsShttp://127.0.0.1:18789/readyz深度检查需要认证dockercomposeexecopenclaw-gatewaynodedist/index.js health\--token$OPENCLAW_GATEWAY_TOKEN获取 Dashboard URLdockercompose run--rmopenclaw-cli dashboard --no-open六、高级配置选项1. 启用 Agent 沙箱推荐生产环境沙箱可以让非主会话在隔离的 Docker 容器中运行提高安全性exportOPENCLAW_SANDBOX1exportOPENCLAW_DOCKER_SOCKET/var/run/docker.sock ./scripts/docker/setup.sh对于 rootless DockerexportOPENCLAW_SANDBOX1exportOPENCLAW_DOCKER_SOCKET/run/user/1000/docker.sock ./scripts/docker/setup.sh2. 自定义 apt 包构建时安装exportOPENCLAW_DOCKER_APT_PACKAGESgit curl jq wgetdockerbuild\--build-argOPENCLAW_DOCKER_APT_PACKAGES$OPENCLAW_DOCKER_APT_PACKAGES\-topenclaw:local\-fDockerfile\.3. 预安装扩展exportOPENCLAW_EXTENSIONSdiagnostics-otel matrix tavilydockerbuild\--build-argOPENCLAW_EXTENSIONS$OPENCLAW_EXTENSIONS\-topenclaw:local\-fDockerfile\.支持的扩展在extensions/目录下。4. 安装 Playwright 浏览器用于浏览器自动化exportOPENCLAW_INSTALL_BROWSER1dockerbuild\--build-argOPENCLAW_INSTALL_BROWSER1\-topenclaw:local\-fDockerfile\.或在运行时安装dockercompose run--rmopenclaw-cli\node/app/node_modules/playwright-core/cli.jsinstallchromium5. 额外挂载访问宿主机文件exportOPENCLAW_EXTRA_MOUNTS/host/data:/container/data:ro,/host/logs:/container/logs格式source:target[:options]多个用逗号分隔。6. 使用命名卷持久化而非 bind mountexportOPENCLAW_HOME_VOLUMEopenclaw_home这会将/home/node整个目录持久化到 Docker 卷中。7. 配置示例openclaw.json编辑$OPENCLAW_CONFIG_DIR/openclaw.json{ agent: { model: anthropic/claude-opus-4-6, defaults: { sandbox: { mode: non-main, // off | non-main | all scope: agent, // session | agent | shared workspaceAccess: none } } }, gateway: { auth: { mode: token, token: your-token-here }, bind: lan, controlUi: { allowedOrigins: [ http://localhost:18789, http://127.0.0.1:18789 ] } }, channels: { whatsapp: { allowFrom: [*], dmPolicy: pairing }, telegram: { botToken: 123456:ABCDEF, allowFrom: [*] } } }七、常用管理命令日志查看# 实时查看日志dockercompose logs-fopenclaw-gateway# 查看最近 100 行dockercompose logs--tail100openclaw-gateway服务管理# 停止服务dockercompose down# 重启服务dockercompose restart openclaw-gateway# 完全清理包括数据卷dockercompose down-v# 重新构建并启动dockercompose up-d--buildopenclaw-gateway设备配对# 列出待批准的设备dockercompose run--rmopenclaw-cli devices list# 批准设备dockercompose run--rmopenclaw-cli devices approverequestId# 拒绝设备dockercompose run--rmopenclaw-cli devices rejectrequestId发送消息测试# 发送测试消息dockercompose run--rmopenclaw-cli message send\--to1234567890\--messageHello from OpenClaw!# 与 Agent 对话dockercompose run--rmopenclaw-cli agent\--messageShip checklist\--thinkinghigh配置管理# 查看当前配置dockercompose run--rmopenclaw-cli config get# 修改配置dockercompose run--rmopenclaw-cli configsetgateway.bind loopback# 重置配置dockercompose run--rmopenclaw-cli config reset技能管理# 列出已安装技能dockercompose run--rmopenclaw-cli skills list# 安装新技能dockercompose run--rmopenclaw-cli skillsinstallskill-name# 更新技能dockercompose run--rmopenclaw-cli skills updateskill-name八、故障排查问题 1权限错误EACCES症状容器内无法写入配置文件解决sudochown-R1000:1000$OPENCLAW_CONFIG_DIR$OPENCLAW_WORKSPACE_DIR问题 2Gateway 无法从主机访问症状浏览器无法打开 http://127.0.0.1:18789/解决# 检查绑定地址配置dockercompose run--rmopenclaw-cli config get gateway.bind# 如果不是 lan修改dockercompose run--rmopenclaw-cli configsetgateway.bind lan# 重启服务dockercompose restart openclaw-gateway问题 3沙箱容器未启动症状Agent 工具执行失败提示找不到 sandbox解决# 构建沙箱镜像./scripts/sandbox-setup.sh# 或指定自定义镜像# 编辑 openclaw.json设置 agents.defaults.sandbox.docker.image问题 4构建时 OOMexit 137症状pnpm install过程中容器被杀死解决增加 Docker 内存限制到至少 2GB或使用更大的虚拟机或分步构建减少并发依赖安装问题 5Dashboard 显示配对请求症状Control UI 显示需要配对设备解决# 获取 Dashboard 链接dockercompose run--rmopenclaw-cli dashboard --no-open# 在浏览器打开链接并批准设备# 或直接通过 CLI 批准dockercompose run--rmopenclaw-cli devices listdockercompose run--rmopenclaw-cli devices approverequestId问题 6WebSocket 连接失败症状macOS/iOS App 无法连接解决# 重置 Gateway 模式dockercompose run--rmopenclaw-cli configsetgateway.modelocaldockercompose run--rmopenclaw-cli configsetgateway.bind lan# 确保防火墙允许 18789 端口# macOS: 系统设置 网络 防火墙# Linux: sudo ufw allow 18789/tcp问题 7渠道消息不响应症状WhatsApp/Telegram 消息发送后无回复排查步骤# 1. 检查渠道状态dockercompose run--rmopenclaw-cli channels list# 2. 查看渠道日志dockercompose logs openclaw-gateway|grep-ichannel\|whatsapp\|telegram# 3. 检查 DM 策略是否启用了 pairingdockercompose run--rmopenclaw-cli config get channels.whatsapp.dmPolicy# 4. 如果是 pairing 模式需要批准发送者dockercompose run--rmopenclaw-cli pairing listdockercompose run--rmopenclaw-cli pairing approve whatsappcode九、安全加固1. DM私信安全策略默认行为DM 配对模式dmPolicypairing未知发送者会收到配对码Bot 不会处理未配对的私信防止垃圾消息和提示注入攻击批准流程# 查看待批准的配对dockercompose run--rmopenclaw-cli pairing list# 批准dockercompose run--rmopenclaw-cli pairing approvechannelcode开放模式仅限可信环境{ channels: { whatsapp: { dmPolicy: open, allowFrom: [*] // 允许所有人 } } }2. 网络暴露安全如果在 VPS 上部署Docker 防火墙规则# 添加 DOCKER-USER 链规则iptables-ADOCKER-USER-ieth0-ptcp--dport18789-jACCEPT iptables-ADOCKER-USER-ieth0-ptcp--dport18790-jACCEPT iptables-ADOCKER-USER-ieth0-jDROP使用 Tailscale推荐{ gateway: { tailscale: { mode: serve, // serve尾网| funnel公开| off resetOnExit: true }, bind: loopback, // 必须保持 loopback auth: { mode: token } } }3. Token 认证强化生成强 Token# 使用 openssl 生成openssl rand-hex32# 或使用 Pythonpython3-cimport secrets; print(secrets.token_hex(32))设置密码认证替代 Token{ gateway: { auth: { mode: password, password: your-strong-password-here } } }4. 容器安全Docker Compose 已经配置了以下安全措施services:openclaw-cli:cap_drop:-NET_RAW-NET_ADMINsecurity_opt:-no-new-privileges:true进一步加固services:openclaw-gateway:read_only:truetmpfs:-/tmpcap_drop:-ALLcap_add:-NET_BIND_SERVICE5. 沙箱隔离启用沙箱后非主会话的工具执行会在隔离容器中进行{ agents: { defaults: { sandbox: { mode: non-main, // 非主会话启用沙箱 scope: agent, workspaceAccess: none, // 禁止访问工作区 allowTools: [ bash, process, read, write, edit, sessions_list, sessions_history, sessions_send ], denyTools: [ browser, canvas, nodes, cron, discord, gateway ] } } } }十、持久化说明数据持久化策略Docker Compose 使用bind mount持久化关键数据宿主机路径容器路径内容$OPENCLAW_CONFIG_DIR/home/node/.openclaw配置、凭证、身份$OPENCLAW_WORKSPACE_DIR/home/node/.openclaw/workspace技能、会话、媒体目录结构~/.openclaw/ ├── openclaw.json # 主配置文件 ├── identity/ # 身份和密钥存储 │ └── default/ ├── credentials/ # 渠道凭证加密存储 ├── agents/ # Agent 配置 │ └── main/ │ ├── agent/ # Agent 专属文件 │ └── sessions/ # 会话历史 └── workspace/ ├── skills/ # 已安装技能 ├── media/ # 媒体文件缓存 └── cron/ └── runs/ # 定时任务记录磁盘增长监控以下目录可能快速增长需定期清理# 查看各目录大小dockercomposeexecopenclaw-gatewaydu-sh\/home/node/.openclaw/workspace/media\/home/node/.openclaw/agents/main/sessions\/home/node/.openclaw/workspace/cron/runs\/tmp/openclaw# 清理旧会话保留最近 7 天dockercompose run--rmopenclaw-cli sessions prune --older-than 7d# 清理媒体缓存dockercomposeexecopenclaw-gatewayrm-rf/home/node/.openclaw/workspace/media/*备份策略完整备份# 停止服务dockercompose down# 备份配置和工作区tar-czvfopenclaw-backup-$(date%Y%m%d).tar.gz\~/.openclaw# 重新启动dockercompose up-d增量备份仅配置文件cp~/.openclaw/openclaw.json ~/backups/openclaw-$(date%Y%m%d).json恢复备份# 停止服务dockercompose down# 解压备份tar-xzvfopenclaw-backup-20260401.tar.gz-C~/# 重新启动dockercompose up-d 下一步部署完成后建议访问 Control UIhttp://127.0.0.1:18789/配置 AI 模型在 Settings 中选择您的首选模型连接通讯渠道至少配置一个渠道WhatsApp/Telegram 等安装技能根据需求安装扩展技能测试对话发送一条测试消息验证功能详细使用文档请参考Channels 配置Skills 系统Gateway 配置安全指南祝您部署顺利