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 一半的核心能力。插件生态PluginsOpenClaw 的扩展能力几乎全部依赖插件。官方插件如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 STWStop-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那就装这个。你可以通过nvmNode 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.0Windows 用户请直接去 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 在服务器场景下是冗余且不被支持的。你需要按官方文档通过aptUbuntu或dnfRocky安装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-plugin2.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是绝大多数场景的唯一正确选择。存储持久化PersistenceOpenClaw 的所有状态——API Key、OAuth Token、插件包、会话日志、工作区文件——都默认保存在/home/node/.openclaw这个路径下。Docker 默认的volume或bind mount会把这个路径映射到宿主机的一个文件夹如~/openclaw-config。这个宿主机文件夹的所有者 UID 必须是1000。因为 OpenClaw 的 Docker 镜像以node用户UID 1000身份运行。如果你用sudo mkdir ~/openclaw-config创建了这个文件夹它的所有者是rootUID 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 安装流程的“大脑”它并非黑盒而是由一系列清晰、可审计的步骤组成。让我们拆解它在后台做了什么镜像构建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。新手引导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这个核心密钥。配置写入Config Write引导完成后脚本会执行docker compose run --rm --no-deps --entrypoint node openclaw-gateway dist/index.js config set ...。它向 Gateway 的内部配置数据库写入几条关键设置gateway.modelocal告诉 Gateway它将以本地模式运行不尝试连接远程集群。gateway.bindlan强制绑定到0.0.0.0确保外部可访问。gateway.controlUi.allowedOrigins[http://localhost:18789,http://127.0.0.1:18789]白名单允许来自这两个 Origin 的请求访问 UI 控制台。服务启动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:localSTATUS 为 Up X minutesNAMES 列为类似 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生效但错误依旧。终极排查与修复在 PowerShell 中运行Get-ExecutionPolicy -List确认CurrentUser策略确实是RemoteSigned。运行Get-Command npm查看它指向的npm.ps1的完整路径。如果路径看起来很奇怪比如包含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 aliasLinux/macOS或 PowerShell functionWindows。例如在~/.zshrc中添加alias openclawdocker 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 的内部桥接网络 IP172.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_SANDBOX1但在运行一个需要执行 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_SANDBOX1 ./scripts/docker/setup.shsetup.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 # ... 其他已有的