★ FEATURED ARTICLE 1. OpenClaw 从零搭建到底难在哪Node.js 版本、端口占用与依赖编译的真实坑位OpenClaw 是一个可以在本地跑起来的 AI 助手网关它能对接多种模型通道把对话、工具调用、文件处理这些能力统一收口到一个 Web UI 和命令行入口里。适合谁用想在自己电脑或服务器上跑一个可控 AI 助手的开发者、需要把模型能力接进内部工具链的团队以及单纯想折腾本地 AI 环境的技术爱好者。它本身不绑定某一家模型服务你可以把它理解成一个“插座”模型通道是“插头”插上就能用。但真正动手装的时候问题往往不在 OpenClaw 本身而在环境。我见过太多人卡在第一步openclaw: command not found。这个报错九成不是安装失败而是 npm 全局路径没进 PATH。Node.js 版本低于 22 也会直接报错退出因为 OpenClaw 用到了较新的运行时特性。还有端口 18789 被占用、node-llama-cpp编译失败、Windows 执行策略禁止脚本、路径里带中文或空格导致 gateway 起不来……这些坑单独看都不复杂但凑在一起就足够让人放弃。这篇内容的目标很明确给你一条从零到服务可用的完整链路覆盖 Node.js、npm、pnpm、Docker 四种环境准备方式每种方式都给出可复制的命令和版本锁定建议。然后重点放在“避错”上——按真实报错逐条给排查动作而不是泛泛说“检查环境”。最后用 TaoToken 的统一 Key 接入 API 通道给出一份可以直接改的 settings 配置并逐步验证服务真的可用。先说环境底线这是硬门槛不满足后面全白搭。Node.js 必须 ≥ 22.0.0低于这个版本openclaw onboard会直接抛错。内存建议 4GB 以上2GB 是能跑但编译依赖时容易 OOM。系统方面 Windows 10、macOS 12、Ubuntu 20.04 都可以WSL2 也支持但音频相关依赖要额外装。工具链需要 Git、pnpm推荐和 curl。安装目录和工作路径千万别用中文、空格或特殊字符D:\AI\openclaw这种是安全的D:\我的文件\open claw这种迟早出问题。下面按四种安装方式展开你可以根据自己的环境选一种。新手优先看方式一和方式二服务器或隔离环境看方式四。每种方式我都会给出验证命令装完立刻确认别等到配置阶段才发现没装上。2. TaoToken 统一 Key 前置准备Base URL、API Key 与模型 ID 三件套怎么拿在开始装 OpenClaw 之前先把模型通道准备好这样装完就能直接接上验证不用来回切换。TaoToken 在这里扮演的角色是统一入口你不需要为每个模型单独配一套鉴权和地址拿一个 Key 就能在 OpenClaw 里调用多个模型。对 OpenClaw 这种需要频繁切换模型的场景来说统一 Key 能省掉大量配置维护成本。你需要准备三样东西我习惯叫它们“三件套”Base URL、API Key、Model ID。这三样在 OpenClaw 的 settings 配置里会同时出现缺一个都跑不通。Base URL 是 API 请求的根地址TaoToken 的 API 地址是https://taotoken.net/api。注意这里不要加任何查询参数就是干净的根路径。API Key 需要你登录后在控制台创建创建入口在 API Keys 页面。Model ID 是你想调用的具体模型标识比如claude-sonnet-4-20250514这类具体可用列表在模型对话页面能看到也可以直接问模型对话里的助手。拿 Key 的步骤不复杂打开官网登录后进控制台找到 API Keys点创建复制生成的 Key。这个 Key 只显示一次复制后先存到安全的地方。如果你还没决定用哪个模型可以先在模型对话里试几个确认响应正常再写进配置。这里有个容易忽略的点OpenClaw 的配置里 Base URL 和 Key 是分开填的不是拼在一起。有些工具要求你把 Key 放在 URL 里OpenClaw 不是。所以配置时看清楚字段别把 Key 塞进 Base URL。另外如果你打算长期跑编码类任务或 Agent 工作流可以考虑 Coding Plan它在调用额度和并发上更适合持续使用。如果只是验证模型能不能通用模型对话就够了。接入文档里有完整的字段说明和示例配置前扫一眼能少走弯路。三件套准备好之后先别急着装 OpenClaw可以用 curl 快速验证 Key 是否有效。这一步能提前排除鉴权问题避免装完才发现 Key 是错的。验证命令在下一节给。3. 四种环境准备与可复制配置Node.js、npm、pnpm、Docker 全流程这一节是核心操作区四种方式按需选一种。每种都给出完整命令和版本锁定建议你直接复制改路径就行。3.1 方式一一键脚本新手首选Windows 用管理员 PowerShell先解锁执行策略再跑安装脚本Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force iwr -useb https://open-claw.org.cn/install-cn.ps1 | iexmacOS、Linux、WSL 用curl -fsSL https://open-claw.org.cn/install-cn.sh | bash装完立刻验证openclaw --version能打印版本号就说明二进制已就位。如果报command not found跳到第 5 节看 PATH 排查。3.2 方式二npm/pnpm 手动安装已有 Node 环境首选先配国内镜像加速再全局安装并锁定版本npm config set registry https://registry.npmmirror.com npm install -g openclawlatest openclaw onboard如果你用 pnpm命令换成npm install -g pnpm pnpm add -g openclawlatest openclaw onboard版本锁定建议生产环境别用latest改成具体版本号比如openclaw1.4.2避免自动升级引入不兼容。onboard是初始化向导会引导你设置 API Key、端口和权限先跑一遍后面配置可以再改。3.3 方式三源码编译开发者/二次开发git clone https://gitee.com/OpenClaw-CN/openclaw-cn.git cd openclaw-cn npm install -g pnpm pnpm install pnpm ui:build pnpm build pnpm link --global openclaw onboard --install-daemon源码方式适合要改代码或做二次开发的场景。pnpm install会拉依赖ui:build构建前端build编译后端link --global把本地包链到全局。如果node-llama-cpp编译失败看第 5 节的编译环境排查。3.4 方式四Docker 部署服务器/隔离环境先拉镜像再起容器docker pull openclaw/openclaw:latest docker run -d --name openclaw -p 18789:18789 openclaw/openclaw:latest生产环境建议用 Compose 管理下面这份模板可以直接用注意把 Key 换成你自己的version: 3.8 services: openclaw: image: openclaw/openclaw:1.4.2 container_name: openclaw ports: - 18789:18789 environment: - OPENCLAW_API_BASEhttps://taotoken.net/api - OPENCLAW_API_KEYsk-你的Key - OPENCLAW_MODEL_IDclaude-sonnet-4-20250514 volumes: - ./data:/root/.openclaw restart: unless-stopped镜像 tag 别用latest锁到具体版本升级时改 tag 再docker compose up -d。volumes把配置和数据挂出来容器重建不丢配置。3.5 初始化与启动不管哪种方式装完都要初始化并启动网关openclaw onboard openclaw gateway start openclaw gateway status状态显示 running 就说明服务起来了Web UI 在http://localhost:18789。如果端口被占用改端口openclaw config set gateway.port 18790 openclaw gateway restart3.6 TaoToken 接入的 settings 配置示例OpenClaw 的配置文件在~/.openclaw/settings.jsonWindows 在C:\Users\用户名\.openclaw\settings.json。下面这份是接入 TaoToken 的最小可用配置路径和字段名按实际文件来{ gateway: { port: 18789, host: 127.0.0.1 }, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, modelId: claude-sonnet-4-20250514 } }, defaultProvider: taotoken }三件套在这里全部出现baseUrl对应 Base URLapiKey对应 KeymodelId对应 Model ID。改完保存重启网关生效openclaw gateway restart如果你用 Docker把这份配置放到挂载目录./data/settings.json容器重启后自动读取。4. 验证请求与成功结果从 curl 到 Web UI 的逐步确认配置写完不算完必须验证服务真的能通。我习惯分三步走每步都有明确的成功标志哪步断了就停在哪排查。第一步先用 curl 直接打 TaoToken 的 API确认 Key 和地址没问题。这一步绕开 OpenClaw单独验证通道curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: ping}] }返回里带content字段和文本内容就说明 Key 有效、地址正确、模型可调。如果返回 401看第 5 节鉴权排查如果返回模型不存在检查 Model ID 拼写。第二步验证 OpenClaw 网关本身。启动后访问状态接口curl http://localhost:18789/health返回{status:ok}或类似结构说明网关进程正常。如果连不上先确认openclaw gateway status是 running再看端口是否被防火墙拦。第三步走 Web UI 发一条真实消息。浏览器打开http://localhost:18789在对话框里输入任意内容比如“你好报一下当前模型”。能收到回复且回复来自你配置的模型整条链路就通了。这一步同时验证了前端、网关、provider 配置三部分。三步都过说明 OpenClaw 已经可用。如果第三步失败但前两步成功问题多半在 settings 的 provider 字段检查defaultProvider是否指向taotoken以及providers下的字段名有没有拼错。验证通过后你可以把常用命令记一下openclaw gateway status看状态openclaw doctor自动检测环境问题openclaw gateway restart改配置后重启。这几个命令能覆盖日常大部分操作。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth 逐条对照这一节按真实报错给排查动作你遇到哪个查哪个。报错 1openclaw: command not found原因基本是 npm 全局路径没进 PATH。先看路径npm config get prefixWindows 把这个路径加进系统环境变量 Path。macOS/Linux 执行echo export PATH$(npm config get prefix)/bin:$PATH ~/.bashrc source ~/.bashrc报错 2Windows 执行策略禁止脚本报错信息是cannot be loaded because running scripts is disabled。管理员 PowerShell 执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force报错 3端口 18789 被占用报错address already in use。Windows 查进程netstat -ano | findstr :18789 taskkill /F /PID 进程号macOS/Linuxlsof -i :18789 kill -9 进程号或者直接改端口openclaw config set gateway.port 18790 openclaw gateway restart报错 4node-llama-cpp编译失败缺 C 编译环境。Windows 装 VS Build Tools勾选 C 生成工具。macOS 执行xcode-select --install。Linux 执行sudo apt install build-essential cmake -y。报错 5npm 安装权限错误 EACCES别用 sudo 硬装改全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc报错 6sharp 安装失败macOSSHARP_IGNORE_GLOBAL_LIBVIPS1 npm install -g openclawlatest报错 7Gateway 启动失败 / 服务异常openclaw gateway stop pkill -9 -f openclaw-gateway openclaw gateway run --force日志位置Windows 在C:\Users\用户名\.openclaw\logsmacOS/Linux 在~/.openclaw/logs。日志是排查神器报错原文都在里面。报错 8401 鉴权失败检查三件套baseUrl是不是https://taotoken.net/apiapiKey有没有多余空格modelId是否在可用列表里。Key 复制时容易带上换行重新复制一次。如果 Key 过期去控制台重新创建。报错 9local proxy failed这个报错通常出现在网关转发请求时。先确认本机网络能直连taotoken.net用 curl 测一下。然后检查 settings 里baseUrl有没有写成带路径的形式必须是根地址。如果用了 Docker确认容器内 DNS 能解析外部域名。报错 10reading choices报错这个报错说明返回结构不符合预期多半是 Model ID 和接口协议不匹配。确认你用的模型走的是 messages 协议还是 chat completions 协议OpenClaw 的 provider 配置里协议类型要对上。换一个确认可用的 Model ID 再试。报错 11OAuth 相关报错如果你在配置里启用了 OAuth 流程但没配回调地址会报这个。OpenClaw 接 TaoToken 用 API Key 模式即可不需要 OAuth。检查 settings 里有没有多余的 OAuth 字段删掉再重启。报错 12路径含中文/空格导致异常规则很简单安装目录、工作路径禁止中文、空格、特殊字符。D:\AI\openclaw可以D:\我的文件\open claw不行。已经装错路径的卸载重装到干净路径。报错 13WSL2 运行异常sudo apt install pulseaudio -y export SDL_AUDIODRIVERpulseaudioWSL2 的音频和图形依赖需要额外补纯命令行使用可以忽略音频相关报错。排查顺序建议先看日志原文再对照上面的报错条目最后用openclaw doctor做一次全面检测。大部分问题都能在前三条里找到答案。6. 装完之后怎么用模型对话验证、Coding Plan 与接入文档的下一步服务跑起来只是起点接下来看你怎么用。如果只是想确认模型能通直接在 Web UI 里对话就行或者用模型对话页面测试不同模型的响应质量。这一步能帮你确定哪个 Model ID 最适合你的场景再写回 settings 固化下来。如果你打算把 OpenClaw 用在长期编码任务或 Agent 工作流上Coding Plan 在调用额度和并发上更适合持续使用配置方式一样只是 Key 的权限范围不同。接入文档里有完整的字段说明、协议对照和示例配置遇到字段不确定的时候翻一下比猜快。日常维护记住几个动作改完 settings 一定openclaw gateway restart升级前先备份~/.openclaw目录Docker 部署改 tag 再docker compose up -d。日志目录定期看一眼很多问题在爆发前就有征兆。最后说一个实用技巧把验证用的 curl 命令存成一个脚本每次改完配置跑一遍三步验证全过再继续。这样能把配置问题和环境问题分开排查效率高很多。OpenClaw 本身不复杂复杂的是环境差异把环境锁死、配置固化后面就顺了。
阅读完成 · 觉得有帮助？
