OpenClaw 部署指南：Docker部署详细实战经验分享

部署 OpenClaw 时，我查阅了大量 Docker 部署相关的文章，虽然官方文档很详细，但实际操作中仍会遇到不少坑。本文将这些经验整理出来，供大家参考。

特别说明：本文的部署环境是云服务器（Debian 13），并使用 1Panel 面板。1Panel 面板可以直接安装 OpenClaw，但无法自定义模型。如果你需要更灵活的部署方式，请继续往下看。

1. 部署

在开始部署之前，建议先阅读项目的 README.md，了解整体架构：

https://github.com/openclaw/openclaw/blob/main/README.md

OpenClaw 支持多种部署载体（本地宿主机、虚拟机、云服务器）和多种对话渠道（Telegram、Slack 等）。综合考虑便利性和模型能力，推荐使用海外云 VPS + Telegram + 顶级模型的组合。

详细的部署文档请参考：

https://github.com/openclaw/openclaw/blob/main/docs/install/docker.md

1.1 下载项目

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./docker-setup.sh

运行脚本后，会在宿主机上创建两个关键目录，它们会被挂载到 Docker 容器中：

① ~/.openclaw — 配置目录

存储 OpenClaw 的记忆数据
配置文件
第三方 API 密钥

② ~/openclaw/workspace — 工作空间目录

Agent 可直接访问的文件目录
Agent 创建的文件也会保存在这里

1.2 配置引导

首先点击 Skip for now 跳过初始配置。

如果你想使用 Telegram 作为消息渠道，需要提前完成以下准备工作：

在 Telegram 中搜索 @userinfobot，获取你的用户 ID
搜索 @BotFather，创建一个机器人（先设置昵称，再设置用户名）
创建完成后，BotFather 会给你一个 Bot API Token，请务必记录下来
在配置向导中填写 Telegram (Bot API) 时，需要用到这个 Token

后续配置可以一路跳过，Hooks 部分选择 session-memory 即可。

配置完成后，系统会显示一个 Token：

Token: 24b38f4bb1401bd949f5a2cc156e99bad6591847919f3ce0ab4cab02d69e037e

现在可以通过浏览器访问 http://公网IP:18789 了。不过更推荐使用域名访问，具体方法见 5.2 节。

2. 消息渠道配对

在服务器上执行配对命令，使 Telegram 机器人与 OpenClaw 建立连接：

# 宿主机直接执行
openclaw pairing approve telegram YKEY9974

# Docker 版执行方式
docker compose run --rm openclaw-cli pairing approve telegram YKEY9974

注意事项：

配对码有效期为 1 小时

每个渠道的待处理请求上限为 3 个

如果配对码已过期，会看到如下错误：

[openclaw] Failed to start CLI: Error: No pending pairing request found for code: 8AGF3F58

此时需要在 Telegram 中向机器人发送 /start 获取新的配对码。

配对成功后，效果如下：

3. 模型选择

选择模型时，主要从两个维度考虑：

按任务复杂度

任务类型	推荐模型
编程、金融、数据分析等复杂任务	Claude Opus 4.6、GPT 5.2 Pro
整理文件资料、图片处理、写作等日常任务	Kimi 2.5、GLM 5.0、MiniMax-M2.5

按使用频次

使用频次	建议
高频使用	开通包月/包年套餐，推荐 GLM5，能力与 Opus 4.5 相当
低频使用	使用企业级 API 按量付费，推荐 Atlas Cloud、接口 AI，稳定且性价比高

4. Skills 与 MCP

Skills

推荐前往 ClawHub 社区下载 Skills。注册账号后，可以获取 API 密钥让 OpenClaw 自动安装。

推荐安装的 Skills：

find-skills
Agent Browser
DevTools MCP
auto-updater
Openclaw Command Center
self-improving-agent

MCP

如果你使用智谱的模型，推荐安装官方 MCP，效果通常优于第三方 MCP。先装上试试，不满意可以随时更换。

5. 常见问题

5.1 权限问题：EACCES permission denied

问题描述： 运行 ./docker-setup.sh 后，出现以下错误：

Error: EACCES: permission denied, open '/home/node/.openclaw/openclaw.json.7.xxx.tmp'

原因： Docker 容器内的用户（uid=1000）没有权限写入宿主机上的目录。

解决方法：

chown -R 1000:1000 "$HOME/.openclaw"

修改权限后，可以重新运行初始化向导：

docker compose run --rm openclaw-cli onboard

5.2 浏览器访问安全问题

问题描述： 访问 http://公网IP:18789 时，页面报错：

disconnected (1008): control ui requires HTTPS or localhost (secure context)

This page is HTTP, so the browser blocks device identity. Use HTTPS (Tailscale Serve) or open http://127.0.0.1:18789 on the gateway host.

If you must stay on HTTP, set gateway.controlUi.allowInsecureAuth: true (token-only).

Docs: Tailscale Serve

Docs: Insecure HTTP

解决方法： 需要配置 HTTPS 反向代理。推荐使用 Caddy 管理多个子域名。配置完成后，即可通过 https://你的域名.com/ 访问 OpenClaw。

5.3 Docker 部署常见问题

5.3.1 disconnected (1008): pairing required

原因： 控制 UI 首次从新浏览器或新设备连接 Gateway 时，需要进行一次设备配对批准（即使在同一台机器上也可能需要）。

openclaw devices list
openclaw devices approve <requestId>

如果上述方法无法解决，请按以下步骤排查：

Step 1 — 修复容器网络

CLI 容器无法访问 127.0.0.1 的网关，因为容器内的 localhost 指向容器自身。需要在 docker-compose.yml 中添加：

openclaw-cli:
  depends_on:
    - openclaw-gateway
  environment:
    OPENCLAW_GATEWAY_URL: ws://openclaw-gateway:18789

Step 2 — 设置 Gateway 绑定到局域网

内置向导默认使用回环地址，但浏览器请求是通过 Docker 的桥接网络（172.18.0.x）到达的。在 ~/.openclaw/openclaw.json 中修改：

"gateway": {
  "bind": "lan"
}

Step 3 — 同步 Gateway Token

docker-setup.sh 会在 .env 文件中生成一个令牌，但配置向导会将不同的令牌写入 openclaw.json。请确保 ~/.openclaw/openclaw.json 中的 gateway.auth.token 与 .env 文件中的 OPENCLAW_GATEWAY_TOKEN 一致。

Step 4 — 批准待配对设备

设备卡在待处理状态时，可以尝试以下方法：

# 方法 A — 在网关容器内直接运行
docker compose exec openclaw-gateway node dist/index.js devices list
docker compose exec openclaw-gateway node dist/index.js devices approve <request-id>

# 方法 B — 手动移动配对记录
# ~/.openclaw/devices/pending.json → ~/.openclaw/devices/paired.json
# 将 pending.json 清空为 {}，然后重启网关

# 方法 C — 快速解决，在 openclaw.json 中添加：
# "controlUi": { "allowInsecureAuth": true }

完成上述任何一项操作后，请重启网关：
docker compose restart openclaw-gateway
然后访问 http://localhost:18789/#token=<your-token-from-.env>

5.3.2 常用命令

openclaw-cli 命令行

# 仅重启网关（不会应用新的 compose 配置）
docker compose restart openclaw-gateway

# 修改 docker-compose.yml 后需要重建容器
docker compose up -d --force-recreate openclaw-gateway

# 进入配置界面，可以更新配置
docker compose run --rm openclaw-cli onboard

# 启用 Slack 流式传输（实时反馈）(2026.2.18 更新)
docker compose run --rm openclaw-cli config set \
  "channels.slack.autoSlackBot.streamMode" "enabled"

# 进入 Telegram 配置
docker compose run --rm openclaw-cli configure --section web

# 配置 Cron 错峰调度（避免资源竞争）
docker compose run --rm openclaw-cli cron edit <job-id> --stagger "s"

# 启用 Telegram 按钮样式
docker compose run --rm openclaw-cli message send \
  --channel telegram \
  --target "@your-bot" \
  --message "请选择：" \
  --buttons '[[{"text":"确认","callback_data":"cmd:confirm","style":"success"},
              {"text":"取消","callback_data":"cmd:cancel","style":"danger"},
              {"text":"继续","callback_data":"cmd:continue","style":"primary"}]]'

OpenClaw 命令行速查

Docker 版 将 systemctl 替换为 docker compose run --rm openclaw-cli，后面命令不变。

# 启动网关
systemctl start openclaw-gateway

# 重启网关
systemctl restart openclaw-gateway

# 停止网关
systemctl stop openclaw-gateway

# 查看网关状态
systemctl status openclaw-gateway

# 查询设备列表
openclaw devices list

# 批准待配对的设备
openclaw devices approve <requestId>

核心文件说明

OpenClaw 有几个核心文件，用于定义 Agent 的角色、身份和能力。重装系统后可以直接替换这些文件，让它保留「前世的记忆」。

它们位于工作区 ~/.openclaw/workspace：

文件	作用
`AGENTS.md`	行为准则，定义什么能做什么不能做
`SOUL.md`	定义性格、技能和处理逻辑
`TOOLS.md`	定义可用工具
`IDENTITY.md`	基本信息，如名字和图标
`USER.md`	用户偏好设置
`HEARTBEAT.md`	默认为空或仅包含注释，用于定期检查任务
`MEMORY.md`	长期记忆文件

Spawn 分身能力： 调用 spawn 可以开启 OpenClaw 的分身能力，用于多任务处理。

示例：spawn 两个 subagent，分别从正方、反方角度阐述结婚的好处，不少于 3 轮，把详细过程展示出来。

给 OpenClaw 换一个「无班味」的性格设定

Read your SOUL.md. Now rewrite it with these changes:

1. You have opinions now. Strong ones. Stop hedging everything with 'it depends' — commit to a take.
2. Delete every rule that sounds corporate. If it could appear in an employee handbook, it doesn't belong here