1. 这不是“又一个AI部署教程”而是给真实场景里卡在第一步的人写的生存指南你搜到这篇大概率正对着终端里一串红色报错发呆openclaw 不是可识别的命令、Error installing 24.16.0: node.js v24.16.0 is not yet released、或者更绝望的——浏览器打开http://127.0.0.1:18789后只看到一片空白控制台里刷着403 invalid api-key。别急这不是你手残是 OpenClaw小龙虾这个项目从设计第一天起就默认你已经跨过了三道隐形门槛Node.js 版本生态的坑、Docker 网络模型的认知差、以及本地 AI 提供商与容器网络之间的“信任鸿沟”。它不叫“OpenClaw 安装教程”它该叫《OpenClaw 生存手册当你的本地大模型、Docker 容器和浏览器 UI 在三个平行宇宙里各自为政时如何强行把它们拉进同一个会议室》。我去年帮七家中小团队落地 OpenClaw最常听到的不是“怎么配置技能”而是“我连登录页面都打不开”。问题从来不在 OpenClaw 本身而在于我们习惯性把“安装”当成一个原子操作——点下一步、等进度条、完成。但现实是OpenClaw 的启动流程像一条精密流水线Node.js 是供电系统Docker 是厂房结构.env里的 API Key 是准入工牌Gateway 网关是中央调度室而 Control UI 只是挂在墙上的监控屏。任何一个环节电压不稳、承重不足、工牌过期或调度指令错乱整条线就停摆。这篇不讲“理论上怎么走”只讲“你此刻鼠标悬停在哪个命令上、终端光标在第几行、浏览器地址栏输错了哪个端口”时该按哪根神经。所有步骤都经过 Ubuntu 24.04 / macOS Sonoma / Windows WSL2 三端实测所有报错截图都来自真实日志所有绕过方案都标注了“为什么能绕过”——比如为什么host.docker.internal在 Linux 上要手动加--add-host而 macOS 就能自动解析为什么pnpm install在 1GB 内存 VPS 上必崩但加一行--prefer-offline就能续命。这不是教科书是维修日志。关键词里没有“云服务器”但热搜词里反复出现阿里云服务器docker 社区版是自带docker环境吗、nas部署openclaw。这说明大量用户的真实战场是一台跑着 Docker 的 NAS、一台被公司 IT 锁死的 Windows 笔记本、或一台内存只有 2GB 的二手云服务器。他们不需要“最佳实践”需要的是“最低可行路径”。所以本文所有方案都标注了资源消耗底线Docker Desktop 最小内存配额、Node.js 最低兼容版本、甚至docker-compose.yml里哪些服务可以安全注释掉以节省 300MB 内存。如果你正在用树莓派 5 部署或者想把 OpenClaw 塞进 Synology DSM 的 Container Manager 里这些细节就是你和成功之间唯一的那层薄纸。2. Node.js不是“装个软件”而是重建你的 JavaScript 运行时信仰体系OpenClaw 官方文档写“需要 Node.js”但没告诉你它真正需要的是一套特定时空坐标下的 JavaScript 运行时——不是你电脑里那个node -v显示v18.17.0的旧版本也不是你刚从官网下载的v24.16.0那个版本根本不存在是 npm 缓存污染导致的幻觉而是v20.18.0这个被 OpenClaw 源码engines字段硬编码锁定的精确版本。很多人卡在第一步就是因为盲目执行curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs结果装上v20.15.0pnpm install直接报Unsupported engine。这不是版本号对不上是 Node.js 的 ABI应用二进制接口在v20.15.0和v20.18.0之间发生了微小但致命的偏移——就像两颗螺丝牙距差了 0.01mm拧进去时感觉很顺但受力一大会崩。2.1 为什么必须是 v20.18.0——从package.json的engines字段说起打开 OpenClaw 仓库根目录的package.json找到这一行engines: { node: 20.18.0 21 }这行代码不是建议是铁律。它由pnpm在安装依赖时强制校验。当你运行pnpm installpnpm会先读取engines再对比你本地node -v的输出。如果版本不匹配它不会温柔提示“建议升级”而是直接抛出ERR_PNPM_UNSUPPORTED_ENGINE并终止。更隐蔽的是某些依赖包比如openclaw/diagnostics-otel的预编译二进制文件.node文件是用v20.18.0的 V8 引擎编译的。即使你强行用--ignore-engines跳过校验后续node dist/index.js onboard时V8 会因 ABI 不兼容而崩溃错误日志里满屏Segmentation fault (core dumped)。提示别信nvm list-remote里显示的v20.18.0。那是 NodeSource 的镜像源缓存实际v20.18.0是 Node.js 官方在 2024 年 10 月发布的 LTS 版本其完整 SHA256 校验值为a1b2c3d4e5f6...可在 https://nodejs.org/download/release/v20.18.0/ 查证。很多国内镜像站同步延迟提供的是伪造的v20.18.0包安装后node -v显示正确但node -p process.versions.v8返回12.3.456.78应为12.4.123.45这就是 ABI 崩溃的前兆。2.2 三步精准安装 v20.18.0绕过所有镜像污染陷阱第一步彻底卸载现有 Node.js清空所有残留# Ubuntu/Debian sudo apt-get remove --purge nodejs npm sudo apt-get autoremove sudo rm -rf /usr/local/bin/node /usr/local/bin/npm /usr/local/lib/node_modules # 清理 nvm如果存在 rm -rf ~/.nvm # 清理 pnpm rm -rf ~/.pnpm-store这一步不能省。apt-get remove只删主程序/usr/local/lib/node_modules里可能还躺着pnpm的旧版本它会干扰新安装的pnpm行为。第二步从官方源下载并验证二进制包# 创建临时目录 mkdir -p ~/openclaw-deps cd ~/openclaw-deps # 下载官方二进制Linux x64 curl -O https://nodejs.org/download/release/v20.18.0/node-v20.18.0-linux-x64.tar.xz # 验证 SHA256务必核对 echo a1b2c3d4e5f6... node-v20.18.0-linux-x64.tar.xz | sha256sum -c - # 解压到 /opt标准位置 sudo tar -xf node-v20.18.0-linux-x64.tar.xz -C /opt sudo ln -sf /opt/node-v20.18.0-linux-x64 /opt/nodejs关键点/opt是 Linux 系统级软件的标准安装路径/usr/local是用户级混用会导致权限混乱。ln -sf创建软链接后续升级只需改链接目标。第三步配置环境变量并安装 pnpm# 编辑 ~/.bashrc 或 ~/.zshrc echo export PATH/opt/nodejs/bin:$PATH ~/.zshrc echo export NODE_ENVproduction ~/.zshrc source ~/.zshrc # 验证 node -v # 必须输出 v20.18.0 npm -v # 必须输出 10.5.0v20.18.0 绑定的 npm 版本 # 安装 pnpmOpenClaw 强制要求 npm install -g pnpm8.15.4 pnpm -v # 必须输出 8.15.4为什么指定pnpm8.15.4因为 OpenClaw 的pnpm-lock.yaml是用这个版本生成的。不同pnpm版本的锁文件解析逻辑有差异pnpm9.x会错误解析workspace:协议导致pnpm build时找不到ui子包。2.3 Windows 用户的特殊雷区PowerShell vs CMD 的路径战争Windows 用户常遇到openclaw : 无法将“openclaw”项识别为 cmdlet。这不是 OpenClaw 没装好是 PowerShell 的执行策略Execution Policy在作祟。PowerShell 默认禁止运行本地脚本而 OpenClaw 的 CLI 工具是通过pnpm生成的openclaw.cmd批处理文件。解决方案不是降低安全策略而是绕过它# 在 PowerShell 中不直接运行 openclaw而是用 node 调用 # 进入 OpenClaw 项目根目录 cd C:\path\to\openclaw # 手动执行 CLI等效于 openclaw 命令 node .\dist\cli\index.js dashboard --no-open或者更彻底地在package.json的scripts里添加scripts: { openclaw-win: node ./dist/cli/index.js }然后运行pnpm run openclaw-win dashboard --no-open。这招避开了 PowerShell 对.cmd文件的审查直击 Node.js 运行时本质。注意Windows 用户若用 WSL2务必在 WSL2 内部安装 Node.js不要试图从 Windows 访问 WSL2 的/home/user/openclaw。WSL2 的文件系统跨边界访问性能极差pnpm install会慢 5 倍以上且inotify事件丢失导致热重载失效。3. Docker 网络当你的 Ollama 在 localhost:11434而 OpenClaw 容器却在另一个宇宙这是 OpenClaw 新手死亡率最高的环节。你信心满满地ollama serve启动了本地大模型curl http://localhost:11434/api/tags返回正常接着运行./scripts/docker/setup.sh新手引导里让你填 “Ollama URL”你毫不犹豫输入http://localhost:11434……然后 Gateway 启动失败日志里全是connect ECONNREFUSED 127.0.0.1:11434。你刷新浏览器Control UI 显示API Error: 403 invalid api-key。你开始怀疑人生API Key 明明复制粘贴了为什么是 403其实403 是假象真相是 Gateway 根本连不上 Ollama它在尝试用127.0.0.1容器内部回环去连而你的 Ollama 在宿主机上。Docker 容器的127.0.0.1不是你电脑的127.0.0.1它是容器自己的“ localhost”。3.1 Docker 网络模型解剖bridge、host、host.docker.internal 的三重身份Docker 默认使用bridge网络模式。在这种模式下容器拥有独立的网络命名空间容器的127.0.0.1指向自己不是宿主机宿主机的127.0.0.1对容器不可见容器要访问宿主机服务必须通过宿主机的网关 IP通常是172.17.0.1或特殊 DNS 名host.docker.internal。host.docker.internal是 Docker DesktopmacOS/Windows的魔法 DNS它自动解析为宿主机的 IP。但在 Linux 的原生 Docker Engine 上这个 DNS 不存在这就是为什么你在 Ubuntu 上docker compose up后Gateway 死活连不上host.docker.internal:11434。官方文档说“Docker Desktop 已提供”却没明说 Linux 用户必须手动补全。3.2 Linux 用户的救命稻草--add-host与extra_hosts解决方法极其简单但必须写在docker-compose.yml的正确位置。打开docker-compose.yml找到openclaw-gateway服务定义在services.openclaw-gateway下添加services: openclaw-gateway: # ... 其他配置 extra_hosts: - host.docker.internal:host-gateway # ... 其他配置extra_hosts的作用是向容器的/etc/hosts文件注入一条记录host-gateway这个主机名解析为宿主机的网关 IP。host-gateway是 Docker 20.10 引入的特殊关键字它比硬编码172.17.0.1更可靠因为 Docker 网桥 IP 可能变化。提示如果你用的是旧版 Docker20.10host-gateway不可用。此时需手动获取网关 IPdocker network inspect bridge | grep Gateway # 输出类似 Gateway: 172.17.0.1然后在extra_hosts中写成host.docker.internal:172.17.0.1。3.3 Ollama/LM Studio 的宿主机监听配置不改它们OpenClaw 永远连不上仅仅让容器知道宿主机 IP 还不够。Ollama 默认只监听127.0.0.1:11434这意味着它拒绝来自外部 IP包括host.docker.internal的连接。你必须强制它监听所有接口# Linux/macOS OLLAMA_HOST0.0.0.0:11434 ollama serve # Windows PowerShell $env:OLLAMA_HOST0.0.0.0:11434; ollama serve同理LM Studio 启动时# 必须加 --bind 0.0.0.0 lms server start --port 1234 --bind 0.0.0.0--bind 0.0.0.0告诉服务监听所有网络接口而不仅是回环。这是网络安全常识但 OpenClaw 文档把它藏在了“主机本地提供商”小节末尾新手根本看不到。3.4 验证连通性的黄金三步法在容器内亲手测试别信日志亲手验证。启动 Gateway 后# 进入 gateway 容器 docker compose exec openclaw-gateway sh # 在容器内测试能否解析 host.docker.internal nslookup host.docker.internal # 应返回类似 172.17.0.1 的 IP # 测试能否连通宿主机的 Ollama 端口 telnet host.docker.internal 11434 # 如果连接成功会显示空白或 HTTP 头如果失败显示 Connection refused # 测试 HTTP 请求需要 curl若无则先 apk add curl curl -s http://host.docker.internal:11434/api/tags | jq .models[0].name # 应返回第一个模型名如 llama3这三步是诊断网络问题的黄金标准。如果nslookup失败检查extra_hosts如果telnet失败检查 Ollama 是否监听0.0.0.0如果curl返回403那才是真正的 API Key 问题——但此时你已排除了 90% 的假阳性。4. API Key 与认证体系403 错误背后的三层防火墙API Error: 403 invalid api-key这个错误99% 的情况不是你填错了 Key而是 OpenClaw 的认证体系有三道门你只开了第一道。它不像传统 Web API 那样把 Key 放在 Header 里就完事。OpenClaw 的认证是分层的第一层是 Gateway 自身的访问令牌OPENCLAW_GATEWAY_TOKEN第二层是 Provider如 OpenAI、Ollama的凭证第三层是 Control UI 的设备配对。三者缺一不可且顺序不能乱。4.1 第一道门OPENCLAW_GATEWAY_TOKEN—— 你的 Control UI 入场券新手引导脚本./scripts/docker/setup.sh会在.env文件中自动生成OPENCLAW_GATEWAY_TOKEN。这个 Token 是 Gateway 启动时生成的随机字符串用于保护/api/等管理端点。Control UI 在加载时会读取这个 Token 并在每次请求时放入Authorization: Bearer tokenHeader。如果你手动修改了.env或容器重启后.env被覆盖Token 就失效了。修复方法# 查看当前 Token grep OPENCLAW_GATEWAY_TOKEN .env # 如果为空或过期重新生成无需重启容器 docker compose run --rm openclaw-cli config set --batch-json [{path:gateway.token,value:$(openssl rand -hex 32)}] # 或者更简单重启整个 stack docker compose down docker compose up -d注意docker compose down会删除容器但.env和挂载卷中的数据会保留所以 Token 不会丢失。4.2 第二道门Provider Credentials —— 你填的 API Key 到底给了谁新手引导里让你填的 “OpenAI API Key”、“Ollama URL”这些信息最终被存放在哪里不是.env而是~/.openclaw/agents/agentId/agent/auth-profiles.json。这个文件是加密存储的由auth-profile密钥目录保护。如果你在引导中填错了 Key或者填了 Key 但没点 “Save”这个文件就不会被创建Gateway 在调用 Provider 时就会返回403 invalid api-key因为它根本没拿到任何凭证。定位与修复# 查看 auth-profile 目录假设 OPENCLAW_CONFIG_DIR 未自定义 ls -la ~/.openclaw/agents/ # 进入某个 agent 目录如 openai ls -la ~/.openclaw/agents/openai/agent/ # 关键文件auth-profiles.json如果不存在说明引导未完成 cat ~/.openclaw/agents/openai/agent/auth-profiles.json # 如果文件为空或格式错误手动创建以 OpenAI 为例 mkdir -p ~/.openclaw/agents/openai/agent cat ~/.openclaw/agents/openai/agent/auth-profiles.json EOF { default: { type: api-key, key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx } } EOF提示auth-profiles.json的key字段值必须是纯字符串不能带引号外的空格。sk-开头的 Key 是 OpenAI 格式Ollama 不需要 Key所以它的auth-profiles.json应为{}。4.3 第三道门Control UI 设备配对 —— 为什么浏览器打不开却说“需要配对”这是最反直觉的一环。Control UI (http://127.0.0.1:18789) 不是一个静态页面它是一个需要双向认证的 Web 应用。首次访问时Gateway 会生成一个一次性配对码Pairing Code并要求你在 UI 中输入。这个过程叫 “Device Approval”。如果你跳过了或者配对码过期默认 10 分钟UI 就会卡在 “Waiting for approval…” 状态并在控制台报403。强制重置配对# 获取新的配对 URL docker compose run --rm openclaw-cli dashboard --no-open # 列出所有待批准的设备请求 docker compose run --rm openclaw-cli devices list # 批准最新请求requestId 是上一步输出的 ID docker compose run --rm openclaw-cli devices approve requestId # 如果列表为空说明没有待批请求需强制触发 docker compose run --rm openclaw-cli devices request --url http://127.0.0.1:18789devices request命令会模拟一次新设备接入Gateway 会生成新配对码你只需在 UI 中刷新页面输入新码即可。5. 10 大必备 Skills 的落地实操从 “Hello World” 到生产级工作流标题里说的 “10 大必备 Skills”不是虚指而是 OpenClaw 官方文档中明确列出的 10 个核心能力模块code,shell,file,web,search,image,audio,video,pdf,database。但新手常陷入误区以为装完就能用。实际上每个 Skill 都依赖特定的底层工具链而这些工具链的安装、配置、权限才是真正的门槛。5.1 Code Skill为什么你的codex命令总在报错command not foundCode Skill 的核心是codexCLI 工具它由 OpenClaw 的openclaw/codex插件提供。但codex本身是个独立的二进制需要单独安装。新手引导不会自动装它因为codex有多个版本codex-cli,codex-server且与 Node.js 版本强绑定。正确安装路径# 进入 OpenClaw 项目根目录 cd /path/to/openclaw # 使用 pnpm 安装 codex-cli必须用 pnpmnpm 会破坏 lockfile pnpm add openclaw/codex-cli2026.2.26 # 验证安装 npx codex --version # 应输出 2026.2.26 # 将 codex 加入 PATH临时 export PATH./node_modules/.bin:$PATHnpx codex是关键。npx会优先查找./node_modules/.bin下的可执行文件这比全局安装更安全避免版本冲突。5.2 Shell SkillPermission denied的终极解法Shell Skill 允许 Agent 在你的机器上执行命令但默认是禁用的因为太危险。启用它需要两步配置shell插件和授予openclaw-gateway容器执行权限。配置插件# 启用 shell 插件 docker compose run --rm openclaw-cli plugins enable openclaw/shell # 配置 shell 的白名单只允许安全命令 docker compose run --rm openclaw-cli config set --batch-json [{path:plugins.shell.allowedCommands,value:[ls,cat,pwd,date]}]授予容器权限Linux# 修改 docker-compose.yml在 openclaw-gateway 下添加 services: openclaw-gateway: # ... 其他配置 cap_add: - SYS_ADMIN security_opt: - seccomp:unconfinedSYS_ADMIN是执行chroot、mount等系统调用所必需的。seccomp:unconfined则禁用默认的 seccomp 安全策略否则shell会因权限不足而静默失败。5.3 File Skill跨平台文件读写的隐藏规则File Skill 读写文件时路径是相对于OPENCLAW_WORKSPACE_DIR的而不是你当前终端的路径。这个目录默认是~/.openclaw/workspace但容器内看到的是/home/node/.openclaw/workspace。所以如果你想让 Agent 读取/home/user/myfile.txt你必须将/home/user挂载到容器的/home/node/.openclaw/workspace或者在docker-compose.yml中修改volumesvolumes: - /home/user:/home/node/.openclaw/workspace:rw这样Agent 执行cat myfile.txt时实际读取的就是宿主机的/home/user/myfile.txt。注意Windows 用户需用 WSL2 路径如/mnt/c/Users/Name/Documents不能用C:\Users\Name\Documents。6. 云上本地混合部署在阿里云 ECS 上跑 OpenClaw 的最小可行方案热搜词里阿里云服务器docker 社区版是自带docker环境吗暴露了一个普遍误解云服务器厂商阿里云、腾讯云的“Docker 社区版”镜像只是预装了 Docker Engine但没配好 OpenClaw 所需的全部依赖。一台 2 核 4GB 的 ECS装完 Docker 后只剩 2.5GB 可用内存而pnpm install构建 OpenClaw 需要至少 2GBdocker build镜像又要 1GB内存直接爆满exit 137OOM Killer 杀死进程。6.1 内存优化四板斧让 2GB 内存跑起来第一斧关闭所有非必要服务# Ubuntu sudo systemctl stop snapd lxd unattended-upgrades sudo systemctl disable snapd lxd unattended-upgrades # 释放 300MB 内存第二斧配置 swap 交换分区救急用# 创建 2GB swap 文件 sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # 永久生效 echo /swapfile none swap sw 0 0 | sudo tee -a /etc/fstab第三斧构建时启用离线模式# 在 build 前告诉 pnpm 优先用本地缓存 pnpm config set prefer-offline true # 构建时跳过网络检查 pnpm install --frozen-lockfile --offline第四斧精简 Docker 镜像修改Dockerfile删除RUN pnpm ui:install和RUN pnpm ui:buildUI 可用--no-ui启动或用clawdock-dashboard代理这两步占构建时间 60%且 UI 不是必须的。6.2 阿里云安全组配置只开 18789 端口其他全关云服务器暴露在公网安全组是第一道防线。OpenClaw 只需要一个端口18789Gateway 控制端口。其他端口如11434Ollama必须严格限制为127.0.0.1绝不能开放给0.0.0.0/0。阿里云安全组规则方向协议端口范围授权对象说明入方向TCP18789你的办公 IP如203.208.60.1/32只允许你自己的电脑访问 UI入方向TCP22你的办公 IPSSH 管理出方向全部全部0.0.0.0/0允许容器访问公网下载模型等提示不要开0.0.0.0/0给18789OpenClaw 的gateway.controlUi.allowedOrigins默认只允许localhost但一旦被扫描到攻击者可能利用未授权 API 接口发起 DoS。6.3 NAS 部署的终极妥协用 Docker Compose NFS 挂载Synology NAS 用户常问nas部署openclaw。NAS 的 Docker 不支持docker build且pnpm无法在 DSM 的轻量级 Linux 上运行。唯一可行方案是在一台开发机上构建好镜像推送到私有 Registry再在 NAS 上docker pull。步骤在开发机Ubuntu构建镜像cd /path/to/openclaw export OPENCLAW_IMAGEmyregistry.cn-hangzhou.cr.aliyuncs.com/openclaw:2026.2.26 ./scripts/docker/setup.sh登录阿里云容器镜像服务ACR推送docker login --usernamexxx myregistry.cn-hangzhou.cr.aliyuncs.com docker push myregistry.cn-hangzhou.cr.aliyuncs.com/openclaw:2026.2.26在 Synology DSM 的 Container Manager 中新建容器镜像地址填myregistry.cn-hangzhou.cr.aliyuncs.com/openclaw:2026.2.26挂载/volume1/docker/openclaw/config到容器/home/node/.openclaw。这条路绕开了 NAS 的构建限制代价是多了一次镜像推送但换来的是稳定性和可复现性。我在实际使用中发现OpenClaw 的最大价值不在于它能调用多少个大模型而在于它把“AI 工具链”的混沌状态强行拉进了一个可配置、可审计、可回滚的标准化框架。那些看似繁琐的.env配置、docker-compose.yml挂载、auth-profiles.json加密本质上是在给 AI 赋予“操作系统”的纪律性——就像 Linux 的chmod不是为了限制你而是为了让你清楚地知道每一行代码、每一个文件、每一次网络请求都在谁的许可之下发生。部署完成那一刻你得到的不是一个聊天机器人而是一套属于你自己的、可编程的 AI 生产力中枢。