OpenClaw Docker 安装配置

⚠️ 安全注意事项

本功能涉及高权限操作与凭证管理。运行前请务必审阅以下内容：

• sudo 操作 — 所有 Docker 安装命令均需提升权限。执行前请先审阅 references/docker-setup.sh。
• Tailscale 远程访问 — 启用后将允许网络访问您的 OpenClaw 实例。请确认您的 Tailscale 网络策略已授权该访问，并检查防火墙规则。
• 凭证挂载 — 将 ~/.config/gh 或其他含凭证的目录挂载进容器，会使这些敏感信息暴露给容器镜像。仅在您完全信任该镜像来源时才执行此操作。
• 宿主机文件暴露 — 卷挂载（volume mounts）会赋予容器对宿主机文件的访问权限。请谨慎选择挂载的目录及运行的容器。
• 18789 端口暴露 — 切勿将 18789 端口暴露至公网。除非已配置明确的防火墙规则加以保护，否则应仅绑定到本地回环地址（127.0.0.1）。如需远程访问，请使用 Tailscale（参见 references/docker-config.md）。
• 令牌安全 — 管理脚本不再于终端输出中打印完整的网关令牌。所有令牌均被掩码处理，仅显示前 4 位字符。
• 镜像版本固定（Image pinning） — 为保障构建可复现性，请使用具体版本标签（例如 ghcr.io/openclaw/openclaw:v1.2.3），避免使用 :latest。后者可能在容器重启期间发生变更。

在 Linux（Ubuntu 24.04+）上通过 Docker 运行 OpenClaw，并借助 Tailscale 实现远程访问。

快速开始

1. 通过 APT 安装 Docker（非 Snap）：

   sudo apt install docker.io docker-compose && 
   sudo usermod -aG docker $USER
   

   随后请退出当前会话并重新登录 — sudo usermod 的组变更不会通过 newgrp 立即生效。

2. 运行 onboard 命令，完成网关配置并获取您的令牌：

   docker-compose run --rm openclaw-cli onboard
   

3. 使用 onboard 获取的令牌创建 docker-compose.yml 文件。
   完整模板及 .env 配置说明请参见 references/docker-config.md。

4. 启动容器：

   docker-compose up -d
   

   访问地址：http://localhost:18789?token=YOUR_TOKEN

核心概念

• bind：lan 与 loopback 的区别 — lan 表示可通过端口映射从宿主机访问；loopback 表示仅限容器内部访问（无法从宿主机直接连接）。
• Tailscale 运行于宿主机而非容器内 — 为实现远程访问，请在 Ubuntu 宿主机上运行 Tailscale。
• 仅使用一种安装方式 — Docker 安装与全局安装不可共存（会导致端口冲突与配置冲突）。
• 配置路径映射 — 宿主机路径 ~/.openclaw/ 映射至容器内路径 /home/node/.openclaw/（文件内容一致，路径不同）。
• Docker 用户组登录要求 — sudo usermod -aG docker 修改用户组后，必须完全退出并重新登录，newgrp 无法生效。

常用操作

生成安全令牌：

openssl rand -hex 32

查看容器日志：

docker-compose logs -f openclaw

在容器内运行 CLI 命令：

docker-compose run --rm openclaw-cli COMMAND_HERE

修复卷权限（Linux）：

sudo chown -R 1000:1000 ~/.openclaw ~/openclaw

批准 Telegram 配对：

docker-compose run --rm openclaw-cli pairing approve telegram YOUR_CODE

通过 Tailscale 访问（推荐 — HTTPS）：

sudo apt install tailscale
sudo tailscale up
./docker-setup.sh tailscale  # 在 18789 端口启动 tailscale serve

然后在任意接入您 tailnet 的设备上访问：https://YOUR_MACHINE_NAME.YOUR_TAILNET.ts.net?token=YOUR_TOKEN。建议使用 MagicDNS 主机名而非原始 IP 地址 — 默认启用 HTTPS，且连接更稳定。

参考资料

• references/docker-config.md — 包含 docker-compose.yml 与 .env 模板、权限配置、Tailscale 集成、管理脚本说明
• references/quickstart.md — 简明 5 分钟上手指南
• references/docker-setup.sh — 管理脚本（支持 start / stop / logs / doctor / tailscale / approve_telegram 等子命令）
• references/gotchas.md — 关键易错点及其规避方法
• references/troubleshooting.md — 常见错误与解决方案