OpenClaw AI网关Docker部署实战：从零构建生产就绪AI工作流中枢

1. 项目概述：这不是一次普通安装，而是一场“网关系统部署实战”

OpenClaw 不是某个单一功能的命令行工具，也不是一个点开即用的桌面软件。它是一个面向 AI 工作流的智能网关平台（Gateway Platform），核心作用是统一调度、安全代理、权限管控和可观测性治理——把散落在本地、Docker、云服务、甚至物理设备上的各种 AI 模型、代码执行环境、消息渠道（Telegram/Discord/WhatsApp）、自动化工具（Shell/Python/浏览器）全部接入一个可配置、可审计、可沙箱化的控制中枢。你看到的openclaw命令，只是这个庞大系统对外暴露的一个轻量级 CLI 接口；真正干活的是背后那个持续运行的openclaw-gateway服务进程。

所以，“OpenClaw 安装全教程”这个标题，本质上是在问：如何在你的机器上，从零开始，构建并启动一个具备生产就绪能力的 AI 网关服务？这个过程远超“下载、解压、双击”的范畴，它涉及 Node.js 运行时选型、Docker 容器编排、网络绑定策略、权限模型设计、密钥生命周期管理、可观测性埋点，甚至还要处理 Windows PowerShell 的执行策略这种看似无关却致命的细节。我做过不下 37 次 OpenClaw 的全新部署，覆盖 Windows 10/11、macOS Sonoma/Ventura、Ubuntu 22.04/24.04、Rocky Linux 9，也踩过所有你能想到的坑——比如 npm.ps1 被禁用导致整个 CLI 失效，比如 Docker 容器里访问不到宿主机的 Ollama 服务，比如沙箱容器内 PATH 被重置导致自定义脚本找不到，比如.env文件权限错乱引发 gateway 启动失败。这些不是文档里一句“请确保环境正确”就能带过的，而是必须拆开揉碎、手把手带你绕过去的实操雷区。

这篇教程的目标非常明确：让你第一次部署就成功，且部署完就知道怎么改、怎么调、怎么查、怎么扩。它不讲抽象概念，不堆术语，每一个步骤都对应一个真实问题，每一个参数都解释清楚“为什么是这个值”，每一个报错都给出定位路径和修复方案。你会学到的，不是“如何运行一条命令”，而是“当这条命令失败时，你该看哪三行日志、查哪两个配置、改哪一处挂载”。这才是一个资深从业者真正想分享的“安装”——它其实是整套系统的首次交付与健康验证。

2. 安装前的底层逻辑与决策树：为什么 Docker 是首选，以及何时该放弃它

2.1 Docker 不是“可选项”，而是 OpenClaw 架构的天然载体

很多新手看到文档里写“Docker 是可选的”，就下意识跳过，转头去搞npm install -g openclaw。这是最危险的起点。OpenClaw 的设计哲学决定了它的核心组件必须运行在隔离、可控、可复现的环境中：

• Gateway 服务本身：它需要长期驻留、监听端口、管理会话、处理 WebSocket 连接。Node.js 进程直接跑在宿主机上，意味着它和你的开发环境、其他 Node 应用共享同一个node_modules、同一个全局npm配置、同一个PATH。一旦你升级了 Node.js 版本，或者不小心npm install -g了某个冲突的包，整个 Gateway 就可能静默崩溃。
• Agent 沙箱（Sandbox）：这是 OpenClaw 最具价值的安全特性。当你让 AI Agent 执行curl、git clone、甚至pip install时，它必须在一个与宿主机完全隔离的容器里运行。这个沙箱容器的生命周期、资源限制（CPU/Memory）、网络策略（是否允许外网）、文件系统挂载（只读还是读写）都由 Gateway 统一管控。这层隔离，只有 Docker/Podman 这类容器运行时能提供。npm install方式根本无法启动沙箱，等于直接废掉了 OpenClaw 一半的核心能力。
• 插件生态（Plugins）：OpenClaw 的扩展能力几乎全部依赖插件。官方插件如@openclaw/diagnostics-prometheus、@openclaw/diagnostics-otel，社区插件如synology-chat、notion-sync，它们的安装、更新、卸载、依赖解析，全部由 Gateway 内置的插件管理器完成。这个管理器默认将插件包安装到/home/node/.openclaw/plugins下，并通过符号链接或动态 require 加载。如果 Gateway 进程直接跑在宿主机上，这个路径就变成了你的家目录，极易被误删、权限混乱，甚至引发不同用户间的插件冲突。

因此，“Docker 是可选的”这句话的真实含义是：如果你只需要一个临时的、单次的、不带沙箱、不连外部模型、不存历史记录的 CLI 工具来测试某条命令，那你可以不用 Docker。但只要你打算把它当作一个日常使用的 AI 工作流中枢，Docker 就是唯一可靠、可维护、可升级的部署方式。我见过太多人因为图省事跳过 Docker，结果在第三天遇到插件加载失败，第四天发现openclaw-cli突然不认识channels子命令，最后不得不重装整个 Node.js 环境——这比花 20 分钟配好 Docker Compose 要痛苦得多。

2.2 Node.js 版本：24.x 是甜蜜点，但别盲目追最新

OpenClaw 官方文档明确要求 Node.js v24.x（基于node:24-bookworm-slim镜像）。这不是随意指定的。v24 引入了几个对 AI 网关至关重要的底层改进：

• V8 引擎的 WebAssembly GC 支持：当 Gateway 需要加载大量 WASM 模块（例如某些轻量级推理模型）时，v24 的垃圾回收器能更高效地管理内存，避免因 GC STW（Stop-The-World）时间过长导致 WebSocket 心跳超时、UI 卡顿。
• fetch()API 的稳定化与流式响应支持：Gateway 作为代理，经常需要将大模型的流式输出（SSE/Chunked）实时转发给前端 UI 或下游客户端。v24 的fetch对ReadableStream的支持更完善，错误处理更健壮，不会像 v18 那样在流中断时抛出难以捕获的TypeError。
• --enable-source-maps的默认启用：当你在调试一个自定义插件时，v24 能自动映射 TypeScript 源码到生成的 JavaScript，极大提升排错效率。

但这里有个关键陷阱：不要安装node-v24.16.0这种尚未发布的版本。你搜索热词里反复出现的error installing 24.16.0: node.js v24.16.0 is not yet released就是血泪教训。Node.js 的发布周期是每月一个 Minor 版本（如 24.1, 24.2），但 OpenClaw 的 CI/CD 流水线只会针对已发布的、经过充分测试的版本（如24.15.0,24.14.0）进行构建和验证。如果你手动下载了一个24.16.0的预发布包，Docker 构建时pnpm install会因为engines字段校验失败而直接退出，报错信息就是那句令人抓狂的 “not yet released”。

我的建议是：永远使用node --version输出的、以.0结尾的稳定版。例如，当前最新稳定版是24.15.0，那就装这个。你可以通过nvm（Node Version Manager）来精准控制：

# macOS/Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.zshrc # or ~/.bashrc nvm install 24.15.0 nvm use 24.15.0

Windows 用户请直接去 Node.js 官网 下载LTS或Current标签下的.msi安装包，安装时勾选 “Add to PATH”，然后在 PowerShell 中运行node -v确认版本。记住，24.15.0是一个具体的、可验证的、有二进制包的版本号，而不是一个模糊的24.x。

2.3 Docker Desktop vs Docker Engine：你的操作系统决定了你的选择

这是另一个高频踩坑点。搜索热词里大量出现docker desktop、docker安装教程、ubuntu安装docker，说明很多人卡在了第一步。你需要根据自己的操作系统，做出根本性选择：

• Windows 10/11 家庭版或专业版：必须安装Docker Desktop。因为 Windows 家庭版不支持 WSL2 的完整内核功能，而 Docker Engine 依赖 WSL2。Docker Desktop 是一个打包好的应用，它内部集成了 WSL2 发行版、Docker Daemon、Docker Compose v2 和一个图形化界面。安装后，你只需在设置里开启 “Use the WSL 2 based engine”，一切就绪。
• Windows Server 或 Linux 发行版（Ubuntu/CentOS/Rocky）：必须安装Docker Engine + Docker Compose v2。Docker Desktop 在服务器场景下是冗余且不被支持的。你需要按官方文档，通过apt（Ubuntu）或dnf（Rocky）安装docker-ce、docker-ce-cli、containerd.io，然后单独安装docker-compose-plugin（注意，不是旧版的docker-composePython 包）。验证命令是docker version和docker compose version，两者都必须返回v2.x.x。

提示：在 Ubuntu 上，如果你用sudo apt install docker-compose，安装的是一个过时的 Python 版本，它和 OpenClaw 的docker compose命令不兼容，会导致docker compose run --rm openclaw-cli ...报错command not found。正确的安装方式是：

sudo apt-get update sudo apt-get install ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg echo "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

2.4 网络与存储：两个被严重低估的“隐形依赖”

OpenClaw 的顺畅运行，极度依赖两个底层基础设施的健康：

• 网络绑定（Binding）：这是gateway.bind配置项的核心。lan模式意味着 Gateway 会绑定到0.0.0.0:18789，这样你本机的浏览器、手机、甚至同一局域网内的其他电脑，都能通过http://<你的IP>:18789访问 UI。而loopback模式只绑定127.0.0.1:18789，只有本机进程能访问。很多新手在 VPS 上部署后打不开 UI，第一反应是防火墙，其实根源在于gateway.bind被错误地设为了loopback。Docker 的网络模型决定了，127.0.0.1在容器内指向的是容器自己，而不是宿主机。所以，lan是绝大多数场景的唯一正确选择。

• 存储持久化（Persistence）：OpenClaw 的所有状态——API Key、OAuth Token、插件包、会话日志、工作区文件——都默认保存在/home/node/.openclaw这个路径下。Docker 默认的volume或bind mount会把这个路径映射到宿主机的一个文件夹（如~/openclaw-config）。这个宿主机文件夹的所有者 UID 必须是1000。因为 OpenClaw 的 Docker 镜像以node用户（UID 1000）身份运行。如果你用sudo mkdir ~/openclaw-config创建了这个文件夹，它的所有者是root（UID 0），那么容器启动时就会因为权限不足而无法写入.env文件，报错EACCES: permission denied。解决方案极其简单，但必须在docker compose up之前执行：

  mkdir -p ~/openclaw-config ~/openclaw-workspace sudo chown -R 1000:1000 ~/openclaw-config ~/openclaw-workspace

  这一步，我称之为“安装前的圣水洗礼”，跳过它，90% 的权限类报错都会找上门来。

3. Docker 安装全流程详解：从零到 Dashboard 可访问的每一步

3.1 环境准备与前置检查：5 分钟完成所有“看不见”的工作

在敲下任何docker命令之前，请务必完成以下四步检查。这 5 分钟能帮你省下后面 5 小时的排查时间。

第一步：确认 Node.js 和 npm 的可用性与权限打开你的终端（PowerShell / Terminal / iTerm），依次执行：

# 检查 Node.js 版本 node -v # 应输出类似 v24.15.0 # 检查 npm 版本 npm -v # 应输出类似 10.9.0 # 关键！检查 npm 是否能正常执行 npm list -g # 如果报错 "npm.ps1 cannot be loaded because running scripts is disabled on this system"，请立即执行下一步

这个报错是 Windows PowerShell 的执行策略（Execution Policy）在作祟。它和 OpenClaw 本身无关，但会彻底阻断openclaw-cli的所有npm相关操作（如插件安装）。解决方法是临时提升当前会话的策略：

# 在 PowerShell 中，以管理员身份运行（右键 PowerShell -> 以管理员身份运行） Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # 然后关闭并重新打开一个普通的（非管理员）PowerShell 窗口 # 再次运行 npm list -g，应该不再报错

注意：RemoteSigned是最安全的策略，它只允许运行本地脚本和来自可信源的签名脚本，不会降低系统安全性。切勿使用Unrestricted。

第二步：验证 Docker 和 Docker Compose

# 检查 Docker Daemon 是否运行 docker info | head -5 # 检查 Docker Compose v2 是否可用 docker compose version # 测试一个最小的容器是否能拉取和运行 docker run --rm hello-world # 应输出 "Hello from Docker!" 并退出

如果docker info报错Cannot connect to the Docker daemon，说明 Docker Desktop 未启动，或 Docker Engine 服务未运行（Linux 上执行sudo systemctl start docker）。

第三步：创建并初始化持久化目录

# 创建两个核心目录 mkdir -p ~/openclaw-config ~/openclaw-workspace # 将其所有权赋予 UID 1000（这是 Docker 容器内 node 用户的 ID） # Linux/macOS sudo chown -R 1000:1000 ~/openclaw-config ~/openclaw-workspace # Windows (WSL2) # 在 WSL2 的终端中执行（不是 Windows PowerShell） sudo chown -R 1000:1000 /home/$USER/openclaw-config /home/$USER/openclaw-workspace

提示：chown -R 1000:1000中的-R表示递归，确保目录及其所有子文件、子目录都拥有正确权限。这是防止后续EACCES错误的基石。

第四步：获取 OpenClaw 仓库并进入根目录OpenClaw 的官方 GitHub 仓库是https://github.com/openclaw/openclaw。我们不需要git clone整个仓库（那会下载几百 MB 的历史记录），而是直接下载最新的main分支压缩包：

# Linux/macOS curl -L https://github.com/openclaw/openclaw/archive/refs/heads/main.zip -o openclaw-main.zip unzip openclaw-main.zip cd openclaw-main # Windows (PowerShell) Invoke-WebRequest -Uri "https://github.com/openclaw/openclaw/archive/refs/heads/main.zip" -OutFile "openclaw-main.zip" Expand-Archive -Path "openclaw-main.zip" -DestinationPath "." cd openclaw-main

此时，你的终端应该位于openclaw-main/目录下，里面包含了docker-compose.yml、scripts/docker/setup.sh等所有必需文件。

3.2 执行一键安装脚本：理解setup.sh在做什么

现在，终于可以运行那个神奇的脚本了：

# 确保你在 openclaw-main/ 目录下 bash ./scripts/docker/setup.sh

这个脚本是 OpenClaw 安装流程的“大脑”，它并非黑盒，而是由一系列清晰、可审计的步骤组成。让我们拆解它在后台做了什么：

1. 镜像构建（Build）：它首先检查本地是否存在openclaw:local镜像。如果没有，它会执行docker build -t openclaw:local -f Dockerfile .。这个Dockerfile以node:24-bookworm-slim为基础，安装pnpm，复制package.json和pnpm-lock.yaml，运行pnpm install --frozen-lockfile（确保依赖版本绝对一致），再复制源码、构建前端、最终生成一个包含完整dist/目录的镜像。整个过程大约需要 3-5 分钟，取决于你的网络和 CPU。

2. 新手引导（Onboarding）：镜像构建完成后，脚本会立即运行docker compose run --rm --no-deps --entrypoint node openclaw-gateway dist/index.js onboard --mode local --no-install-daemon。这是一个关键的“无守护进程”模式。它启动一个临时的 Gateway 实例，只做一件事：交互式地询问你：

   • 你想连接哪个 AI 提供商？（OpenAI, Anthropic, LM Studio, Ollama...）
   • 你的 API Key 是什么？（会被加密存储）
   • 你想为 Gateway 设置什么认证方式？（Token 或 Password） 这个过程会生成一个.env文件，里面包含了OPENCLAW_GATEWAY_TOKEN这个核心密钥。

3. 配置写入（Config Write）：引导完成后，脚本会执行docker compose run --rm --no-deps --entrypoint node openclaw-gateway dist/index.js config set ...。它向 Gateway 的内部配置数据库写入几条关键设置：

   • gateway.mode=local：告诉 Gateway，它将以本地模式运行，不尝试连接远程集群。
   • gateway.bind=lan：强制绑定到0.0.0.0，确保外部可访问。
   • gateway.controlUi.allowedOrigins=["http://localhost:18789","http://127.0.0.1:18789"]：白名单，允许来自这两个 Origin 的请求访问 UI 控制台。

4. 服务启动（Up）：最后，脚本执行docker compose up -d openclaw-gateway。这会以后台守护进程（Daemon）模式启动openclaw-gateway服务。此时，docker ps命令应该能看到一个名为openclaw-main-openclaw-gateway-1的容器正在运行。

注意：setup.sh脚本默认会将OPENCLAW_CONFIG_DIR和OPENCLAW_WORKSPACE_DIR环境变量指向你之前创建的~/openclaw-config和~/openclaw-workspace目录。这意味着.env文件、openclaw.json配置、所有插件包，都会被持久化保存在那里，即使你删除了容器，数据也不会丢失。

3.3 验证安装成功：从命令行到 UI 的三重确认

安装脚本执行完毕，不代表万事大吉。我们必须进行三层验证，确保每个环节都健康。

第一层：容器状态验证

# 查看所有正在运行的容器 docker ps # 你应该看到一行，CONTAINER ID 开头，IMAGE 列为 openclaw:local，STATUS 为 "Up X minutes"，NAMES 列为类似 "openclaw-main-openclaw-gateway-1" # 如果 STATUS 是 "Exited (1) X seconds ago"，说明启动失败，需要看日志 # 查看 Gateway 容器的日志（实时跟踪） docker logs -f openclaw-main-openclaw-gateway-1 # 正常启动的日志末尾，应该包含类似这样的行： # [INFO] Gateway started on http://0.0.0.0:18789 # [INFO] Control UI available at http://127.0.0.1:18789 # 如果看到 "Error", "Failed", "EACCES", "ECONNREFUSED"，请立即停止，进入故障排除章节

第二层：健康检查端点验证OpenClaw 的 Docker 镜像内置了 Kubernetes 风格的健康探针。我们可以直接用curl测试：

# Liveness 探针：检查进程是否存活（无需认证） curl -fsS http://127.0.0.1:18789/healthz # 成功时应返回空内容，且 exit code 为 0 # Readiness 探针：检查服务是否准备好接收流量（无需认证） curl -fsS http://127.0.0.1:18789/readyz # 成功时同样返回空内容，exit code 为 0 # 如果这两个命令都返回 "curl: (7) Failed to connect..."，说明 Gateway 根本没监听端口，大概率是 `gateway.bind` 配置错误或容器崩溃

第三层：UI 控制台访问验证打开你的浏览器，访问http://127.0.0.1:18789。你应该看到一个简洁的登录页面。此时，你需要输入的不是用户名密码，而是Gateway Token。

这个 Token 就存在你宿主机的~/openclaw-config/.env文件里。用文本编辑器打开它，找到OPENCLAW_GATEWAY_TOKEN=这一行，等号后面那一长串字符就是你的 Token。复制它，粘贴到 UI 的输入框中，点击 “Login”。

提示：如果你在setup.sh过程中选择了 Password 认证，那么这里就需要输入你当时设置的密码，而不是 Token。但 Token 认证是默认且推荐的方式，因为它更安全、更易管理。

成功登录后，你会看到 OpenClaw 的主仪表盘（Dashboard），上面显示着当前运行的 Agents、Channels、Plugins 状态。至此，安装宣告成功。你已经拥有了一个功能完整的 AI 网关。

3.4 配置消息渠道（Channels）：让 OpenClaw 与世界对话

安装只是开始，配置才是让它活起来的关键。OpenClaw 的核心价值之一，是能将 AI 的能力无缝接入你日常使用的通讯工具。我们以 Telegram 为例，演示如何添加一个 Channel。

首先，你需要一个 Telegram Bot 的 Token。去 Telegram 的@BotFather机器人那里创建一个新 Bot，它会给你一个形如1234567890:ABCdefGhIJKlmNoPQRstUvwXYZ123456789的 Token。

然后，在你的终端中，执行：

# 这条命令会启动一个临时的 openclaw-cli 容器，它与 gateway 容器共享网络，可以直接访问 127.0.0.1:18789 docker compose run --rm openclaw-cli channels add --channel telegram --token "1234567890:ABCdefGhIJKlmNoPQRstUvwXYZ123456789"

命令执行成功后，它会返回一个 JSON，其中包含"id": "telegram-xxxx"。这个id就是你新添加的 Telegram Channel 的唯一标识。

接下来，你需要在 Telegram 中找到你刚刚创建的 Bot，发送/start命令。OpenClaw 的 Gateway 会监听这个事件，并自动为你创建一个会话。

注意：docker compose run --rm openclaw-cli这个模式非常重要。它确保了 CLI 命令是在一个干净、隔离的环境中执行的，不会污染你的宿主机环境。这也是为什么文档强调openclaw-cli是一个“启动后工具”——它必须在openclaw-gateway容器已经运行之后才能使用。

你可以用同样的方式添加 Discord、WhatsApp（通过 QR 码扫描）等其他渠道。每添加一个，你都可以在 Dashboard 的 “Channels” 页面看到它的在线状态和最近活动。

4. 常见问题与排查技巧实录：那些文档里不会写的“血泪经验”

4.1 “npm.ps1 cannot be loaded” —— Windows PowerShell 的永恒之痛

现象：在 PowerShell 中运行任何openclaw-cli命令（如docker compose run --rm openclaw-cli plugins list），都报错：

npm.ps1 cannot be loaded because running scripts is disabled on this system.

原因：这是 Windows PowerShell 的默认安全策略，它禁止执行未经签名的本地脚本，而npm的 PowerShell 封装器npm.ps1正是这样一个脚本。

标准解决方案（已述）：Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。

但这里有一个隐藏的“坑”：如果你在安装 Node.js 时，是通过nvm-windows安装的，那么npm.ps1文件可能位于C:\Users\<YourName>\AppData\Roaming\nvm\v24.15.0\node_modules\npm\bin\npm.ps1。而nvm-windows的默认安装路径是C:\Users\<YourName>\AppData\Roaming\nvm。如果你后来手动移动或重命名了这个nvm文件夹，PowerShell 的执行策略缓存可能仍然指向旧路径，导致Set-ExecutionPolicy生效，但错误依旧。

终极排查与修复：

1. 在 PowerShell 中运行Get-ExecutionPolicy -List，确认CurrentUser策略确实是RemoteSigned。
2. 运行Get-Command npm，查看它指向的npm.ps1的完整路径。
3. 如果路径看起来很奇怪（比如包含Program Files或AppData\Local），说明nvm的环境变量NVM_HOME或PATH被污染了。请卸载nvm-windows，然后从 Node.js 官网下载.msi安装包，勾选 “Add to PATH”，这样npm.ps1就会位于标准的C:\Program Files\nodejs\npm.ps1下，RemoteSigned策略就能完美生效。

4.2 “openclaw: command not found” —— 全局安装的幻觉

现象：你天真地执行了npm install -g openclaw，然后试图运行openclaw --version，结果得到command not found。

原因：openclaw这个包名在 npm registry 上并不存在。OpenClaw 的 CLI 工具openclaw-cli是作为openclaw-gateway项目的一部分，通过pnpm workspace管理的。它不是一个独立的、可全局安装的 npm 包。npm install -g只能安装那些在 npm 官网上注册过的包。你执行的这条命令，实际上什么也没安装，或者安装了一个同名的、完全无关的废弃包。

正确做法：永远不要npm install -g openclaw。openclaw-cli的唯一正确来源，是docker compose run --rm openclaw-cli。它是作为 Docker Compose 服务定义的一部分，被打包在openclaw:local镜像里的。你所有的 CLI 操作，都应该通过这个命令来发起。

提示：如果你想在宿主机上有一个快捷的openclaw命令，可以创建一个 shell alias（Linux/macOS）或 PowerShell function（Windows）。例如，在~/.zshrc中添加：

alias openclaw='docker compose run --rm openclaw-cli'

然后source ~/.zshrc，之后你就可以直接openclaw channels list了。但这只是一个便捷的 wrapper，底层依然是 Docker。

4.3 “Control UI shows 'Unauthorized' or 'Needs Pairing'” —— Token 与设备的“信任握手”

现象：你成功访问了http://127.0.0.1:18789，但 UI 显示 “Unauthorized” 或 “This device needs to be paired with your Gateway”。

原因：OpenClaw 的 UI 认证采用了设备配对（Device Pairing）机制，这是一种比单纯 Token 更安全的方案。当你第一次访问 UI 时，Gateway 会生成一个一次性配对请求（Request ID），并要求你通过 CLI 命令来批准它。这一步是为了防止恶意脚本在你不知情的情况下，通过你的浏览器访问并控制 Gateway。

解决方案：

# 第一步：获取当前的配对请求列表 docker compose run --rm openclaw-cli devices list # 输出会类似： # [ # { # "id": "req_abc123", # "name": "Chrome on Windows", # "createdAt": "2024-05-20T10:30:45.123Z", # "status": "pending" # } # ] # 第二步：批准这个请求（将 req_abc123 替换为你实际看到的 id） docker compose run --rm openclaw-cli devices approve req_abc123 # 第三步：刷新你的浏览器页面，现在应该就能正常登录了

注意：devices approve命令需要你提供完整的 Request ID。它通常很长，建议你复制粘贴，不要手动输入。如果你错过了这个请求，或者它过期了（默认 10 分钟），只需刷新浏览器，它会生成一个新的请求，然后重复上述步骤即可。

4.4 “Gateway target shows ws://172.x.x.x” —— Docker 网络的“地址混淆”

现象：你在 Dashboard 的 “Agents” 页面，看到某个 Agent 的状态是 “Connected”，但它的目标 URL 显示为ws://172.20.0.2:18789（一个 Docker 内部的 IP 地址），而不是你期望的ws://127.0.0.1:18789。这会导致你从外部网络（比如手机）无法连接到这个 Agent。

原因：这是gateway.bind配置项的锅。当gateway.bind被错误地设为auto或custom，或者没有被显式设置时，OpenClaw 的 Gateway 会尝试自动探测它所处的网络环境，并可能错误地选择了 Docker 的内部桥接网络 IP（172.x.x.x）作为对外服务的地址。这个地址在 Docker 容器内部是有效的，但在宿主机或外部网络上是不可路由的。

根治方案：强制重置gateway.bind为lan。

# 这条命令会直接修改 Gateway 的内部配置数据库 docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]' # 然后重启 Gateway 服务，让新配置生效 docker compose restart openclaw-gateway

执行完后，等待 10 秒，再次访问 Dashboard，你应该能看到所有 Agent 的目标 URL 都变成了ws://127.0.0.1:18789或ws://<你的宿主机IP>:18789，这表示配置已生效。

4.5 “Sandbox container fails to start” —— 沙箱的“最后一公里”

现象：你启用了 Agent 沙箱（OPENCLAW_SANDBOX=1），但在运行一个需要执行 Shell 命令的 Agent 时，它卡在 “Starting sandbox...” 状态，或者直接报错 “Failed to create sandbox container”。

原因：沙箱容器的启动，依赖于 Docker 的docker.sock文件。这个文件是 Docker Daemon 的 Unix Socket，它允许容器内的进程（如 OpenClaw Gateway）与宿主机的 Docker Daemon 进行通信，从而创建新的沙箱容器。默认情况下，Docker Compose 的docker-compose.yml并不会将这个 socket 挂载到openclaw-gateway容器中。

解决方案：你需要手动启用沙箱挂载。有两种方式：

方式一（推荐，使用环境变量）：

# 在运行 setup.sh 之前，先设置环境变量 export OPENCLAW_SANDBOX=1 ./scripts/docker/setup.sh

setup.sh脚本会检测到这个变量，并自动在docker-compose.yml中添加volumes: - /var/run/docker.sock:/var/run/docker.sock这一行。

方式二（手动修改 Compose 文件）： 如果你已经运行了setup.sh，可以手动编辑docker-compose.yml文件，在services.openclaw-gateway.volumes下添加：

volumes: - /var/run/docker.sock:/var/run/docker.sock # ... 其他已有的