Docker 安装

Docker 是可选的。只有当你需要容器化的 Gateway 环境，或在没有本地安装的主机上运行 OpenClaw 时才使用它。

注意：Agent 沙箱隔离也使用 Docker，但它不要求 Gateway 本身运行在 Docker 中。

---

Docker 适合我吗？

场景	推荐方案
想要隔离、可丢弃的 Gateway 环境	✅ 用 Docker
在 VPS / 服务器上运行	✅ 用 Docker
在自己机器上本地开发	❌ 用普通安装流程更快

---

系统要求

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

---

快速开始（推荐）

从仓库根目录运行：

./docker-setup.sh

此脚本会自动：

1. 构建 Gateway 镜像
2. 运行新手引导向导
3. 通过 Docker Compose 启动 Gateway
4. 生成 Gateway Token 并写入 .env

完成后：

• 浏览器打开 http://127.0.0.1:18789/
• 将 Token 粘贴到控制 UI（Settings → token）
• 需要重新获取带 Token 的 URL？运行：docker compose run --rm openclaw-cli dashboard --no-open

配置和工作区写入主机：

• ~/.openclaw/
• ~/.openclaw/workspace

在 VPS 上运行？ 参考 Hetzner 部署文档。

---

手动流程（Docker Compose）

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

---

控制 UI 认证 + 配对（Docker）

如果看到 "unauthorized" 或 "disconnected (1008): pairing required"：

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

---

可选配置

挂载额外的主机目录

在运行 docker-setup.sh 之前设置环境变量：

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。

持久化整个容器 home

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

组合使用：

export OPENCLAW_HOME_VOLUME="openclaw_home"
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro"
./docker-setup.sh

在镜像中预装 apt 包

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

修改后需重新运行 docker-setup.sh 以重建镜像。

---

渠道配置（可选）

# WhatsApp（QR 扫码）
docker compose run --rm openclaw-cli channels login

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

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

---

权限问题（EACCES）

镜像以 node（uid 1000）运行。如果在 /home/node/.openclaw 上看到权限错误：

# Linux 主机
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

---

健康检查

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

---

Agent 沙箱隔离（主机 Gateway + Docker 工具）

当启用 agents.defaults.sandbox 时，非主会话的工具执行在 Docker 容器内进行，Gateway 本身仍在主机上运行。

构建默认沙箱镜像

scripts/sandbox-setup.sh

启用沙箱配置示例

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",   // off | non-main | all
        scope: "agent",     // session | agent | shared
        workspaceAccess: "none",  // none | ro | rw
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          network: "none",
          memory: "1g",
        }
      }
    }
  }
}

安全注意：默认沙箱镜像以非 root 的 node 用户（uid 1000）运行，browser、canvas、nodes 等主机工具默认被禁用。

---

故障排除

问题	原因	解决方法
镜像缺失	未构建	运行 scripts/sandbox-setup.sh
容器权限错误	UID 不匹配	chown -R 1000:1000 工作区目录
自定义工具找不到	PATH 未配置	设置 docker.env.PATH，或在 /etc/profile.d/ 下添加脚本