★ FEATURED ARTICLE 1. OpenClaw 安装前必须搞清楚的 Node 与 pnpm 环境准备OpenClaw 是一个本地运行的 AI Agent 工具能帮你把模型对话、技能调用、聊天渠道和 Gateway 服务串成一条可编排的流水线。它适合谁适合第一次部署 AI Agent、想在自己电脑上跑通完整链路、又不想被复杂配置劝退的开发者。我这次从零装了一遍把 Node 版本校验、pnpm 全局安装、openclaw onboard交互式初始化这三个关键节点完整走通顺便把 TaoToken 统一 Key 接了进去。先说结论OpenClaw 官方推荐 Node 24兼容 Node 22 LTS22.16。如果你机器上 Node 版本太低安装脚本会尝试帮你装 Node 24但与其让它自动折腾不如自己先把版本对齐省得中途报错。pnpm 只在从源码构建时才需要但既然标题里点名了 pnpm我就把全局安装和版本检查一起讲清楚后面用pnpm管理全局包也顺手。整个安装链路可以拆成四步检查 Node 版本 → 安装 pnpm → 执行 OpenClaw 安装脚本 → 运行openclaw onboard完成初始化。每一步都有可复制的命令你跟着敲就行。下面先讲环境准备再讲 onboard 里怎么填 TaoToken 的 Base URL、Key 和 Model ID。1.1 检查 Node 版本别让低版本卡住安装打开终端先看当前 Node 版本node -v如果输出是v24.x.x直接跳过升级。如果是v22.16.0及以上也能用。如果低于 22.16或者干脆提示command not found那就需要装 Node 24。macOS 上我习惯用 nvm 管理版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash source ~/.zshrc nvm install 24 nvm use 24 node -vLinux 用户同样可以用 nvm把source ~/.zshrc换成source ~/.bashrc即可。Windows 用户建议直接去 Node 官网下载 Node 24 的 LTS 安装包或者用winget install OpenJS.NodeJS.LTS。这里有个坑有些系统自带 Node 是 18 甚至 16openclaw安装脚本检测到低版本会尝试自动装 Node 24但自动安装依赖系统包管理器权限容易在sudo环节卡住。所以我的建议是手动把 Node 升到 24再往下走。1.2 安装 pnpm 并验证全局可用pnpm 是一个高效的包管理器OpenClaw 从源码构建时会用到它。即使你走的是预编译安装装一个 pnpm 也不亏后面管理全局 CLI 工具很方便。用 npm 全局安装 pnpmnpm install -g pnpm装完检查版本pnpm -v正常会输出类似9.x.x的版本号。如果提示pnpm: command not found说明 npm 全局 bin 目录不在 PATH 里。用下面命令看 npm 全局路径npm config get prefix把这个路径下的bin目录加到 PATH。macOS/Linux 编辑~/.zshrc或~/.bashrc加一行export PATH$PATH:$(npm config get prefix)/bin然后source一下配置文件再执行pnpm -v应该就能看到了。Windows 用户如果遇到同样问题检查%APPDATA%\npm是否在系统环境变量 Path 中。1.3 执行 OpenClaw 安装脚本环境就绪后安装 OpenClaw 本身。官方提供了一键脚本macOS/Linux 下curl -fsSL https://openclaw.ai/install.sh | bashWindows PowerShellirm https://openclaw.ai/install.ps1 | iex如果你更习惯用 npm 全局装npm install -g openclaw安装完成后验证是否成功openclaw --version看到版本号输出比如openclaw/0.x.x就说明二进制已经可用。如果提示找不到命令回到 1.2 检查 PATH或者重新开一个终端窗口让环境变量生效。这一步是整个安装链路的分水岭版本号能打出来后面 onboard 才有意义打不出来先别急着往下走把 PATH 和 Node 版本再确认一遍。2. TaoToken 前置准备统一 Key 与 Base URL 怎么拿OpenClaw 的 onboard 向导会问你用哪个 AI 模型提供商然后要你填 API Key。如果你手上有多个厂商的 Key每个都要单独配管理起来很碎。TaoToken 的思路是提供一个统一的接入层你拿一个 Key就能在 OpenClaw 里调用多家模型Base URL 和 Model ID 也统一管理。这一步的目标很明确拿到三样东西——Base URL、API Key、Model ID。这三件套后面在 onboard 里会依次用到缺一不可。2.1 注册并创建 API Key打开 TaoToken 官网注册账号后进入控制台。地址是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content登录后找到 API Keys 页面路径是https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content点创建新 Key复制出来保存好。这个 Key 只显示一次丢了就得重新建。建议先存到密码管理器或者临时文本里后面 onboard 要粘贴。2.2 确认 Base URL 和 Model IDTaoToken 的 API 入口是https://taotoken.net/api注意这个地址不带 UTM 参数是纯 API 端点。在 OpenClaw 的配置里Base URL 就填这个。Model ID 取决于你想用哪个模型。TaoToken 支持多家模型具体可用的 Model ID 在文档里能查到https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content常见的比如claude-sonnet-4-20250514、gpt-4o这类。你选一个自己常用的记下来onboard 里要填。2.3 三件套对照表配置项值用途Base URLhttps://taotoken.net/apiAPI 请求入口API Key控制台创建的 Key身份认证Model ID文档里查到的模型标识指定调用哪个模型这三样准备好onboard 里遇到模型配置环节就不会卡壳。如果你还没注册先去把 Key 建了再回来继续。3. openclaw onboard 交互式初始化完整配置openclaw onboard是 OpenClaw 的初始化向导它会一步步引导你完成模型、聊天渠道、技能、Hooks、Gateway 服务的配置。整个过程是交互式的你按提示选就行。下面我把每个步骤的配置项和填写内容拆开讲尤其是模型配置那一段直接对应 TaoToken 的三件套。3.1 启动向导与安全提示在终端执行openclaw onboard首先会显示一段安全警告大意是提醒你 Agent 会执行本地操作注意权限。阅读后选择Yes继续。接着选择 Onboarding 模式◇ Onboarding mode │ QuickStart选QuickStart推荐。它会自动配置网关端口18789、绑定地址127.0.0.1这些默认值对本地开发足够用。如果你有特殊网络需求可以选自定义模式但第一次装建议 QuickStart先把链路跑通。3.2 配置 AI 模型填入 TaoToken 三件套向导会问你选择 AI 模型提供商。这里不要选 Anthropic 或 OpenAI 的直连选项而是找自定义/兼容 OpenAI 协议的入口。不同版本的 OpenClaw 菜单文案可能略有差异核心是让你填 Base URL、API Key、Model ID 这三项。按下面填{ provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: 你的 TaoToken API Key, model: claude-sonnet-4-20250514 }如果你在 onboard 里看到的是分步提问就按顺序填Base URLhttps://taotoken.net/apiAPI Key粘贴你在 2.1 创建的 KeyModel ID填你在 2.2 查到的模型标识这里有个细节有些版本会问API Key的环境变量名比如OPENAI_API_KEY。你可以直接填 Key 本身也可以先导出环境变量再引用。我习惯直接填省事。3.3 聊天渠道、技能与 Hooks模型配完后向导会继续问聊天渠道。如果你只是本地测试可以先跳过或者选一个你常用的渠道。技能Skills和 Hooks 也是可选项第一次装建议保持默认等主链路跑通再回来加。Gateway 服务安装这一步QuickStart 模式下会自动帮你配好端口和绑定地址。你确认一下18789和127.0.0.1没问题就行。整个 onboard 走完后配置会写入本地配置文件。不同系统路径不同macOS/Linux 一般在~/.openclaw/下Windows 在%APPDATA%\openclaw\。你可以打开看看确认 Base URL 和 Model ID 写对了。3.4 配置文件片段参考如果你更想直接改配置文件而不是走交互向导可以参考这个 TOML 片段[model] provider openai-compatible base_url https://taotoken.net/api api_key 你的 TaoToken API Key model_id claude-sonnet-4-20250514 [gateway] port 18789 bind 127.0.0.1把这段写进 OpenClaw 的配置文件效果和 onboard 里填是一样的。改完记得重启 Gateway 服务让配置生效。4. 验证请求openclaw --version 与 API 连通性测试配置写完不代表链路通了得实际验证。这一步分两个动作先确认 OpenClaw 本身可用再确认它能通过 TaoToken 调到模型。4.1 版本检查openclaw --version输出类似openclaw/0.8.3 darwin-arm64 node-v24.4.0看到版本号、平台和 Node 版本说明二进制和运行时都正常。4.2 发起一次真实请求用 OpenClaw 的对话命令发一条测试消息openclaw chat 你好请回复一句话确认连通如果配置正确你会看到模型返回的内容。第一次调用可能稍慢因为要建立连接和加载配置。如果你想更直接地测 API 连通性可以用 curl 打 TaoToken 的端点curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的 TaoToken API Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}] }返回 JSON 里如果有choices字段和内容说明 Key、Base URL、Model ID 三件套都对。如果返回错误看下一节的排查。4.3 成功结果长什么样一次成功的openclaw chat会输出模型回复同时终端可能打印请求日志包含使用的模型和耗时。你重点确认两点模型 ID 是不是你配的那个返回内容是不是正常文本而不是报错。到这一步OpenClaw 安装、pnpm 环境、onboard 初始化、TaoToken 接入就全部跑通了。后面你可以继续在 onboard 里加聊天渠道、技能和 Hooks把 Agent 的能力扩展开。5. 本篇常见报错排查401、local proxy failed、reading choices安装和接入过程中最容易撞上的就是下面这几类报错。我把真实遇到的错误和对应处理列出来你对照着看。5.1 401 UnauthorizedError: 401 Unauthorized这个基本是 Key 的问题。检查三处Key 有没有复制完整前后有没有多余空格、Key 有没有被撤销、请求头里的Authorization格式对不对。TaoToken 的格式是Bearer 你的Key注意Bearer和 Key 之间有一个空格。如果你是在 onboard 里填的 Key打开配置文件确认一下有没有写错行。有时候粘贴时会把换行符带进去导致 Key 被截断。5.2 local proxy failedError: local proxy failed to connect这个报错通常和 Gateway 服务有关。QuickStart 模式默认绑定127.0.0.1:18789如果这个端口被占用或者 Gateway 没启动就会报 proxy failed。检查端口占用lsof -i :18789如果有其他进程占着要么杀掉它要么在配置里换一个端口。换端口后记得同步更新 OpenClaw 的 Gateway 配置。另外确认 Gateway 服务确实在跑。有些系统下 onboard 装完服务不会自动启动需要手动拉起openclaw gateway start5.3 reading choices 相关报错Error: failed to read choices from response这个说明请求发出去了但返回的 JSON 结构里没有choices字段。常见原因有两个一是 Model ID 填错了TaoToken 不认识这个模型返回了错误结构二是 Base URL 写成了不带/api的地址请求打到了错误端点。回到配置文件确认base_url https://taotoken.net/api model_id claude-sonnet-4-20250514Model ID 一定要和文档里列出的完全一致大小写和连字符都不能错。改完重启 Gateway再发一次测试请求。5.4 OAuth 相关报错Error: OAuth token expired or invalid如果你在 onboard 里选了需要 OAuth 的提供商而不是用 API Key可能会遇到这个。解决办法很简单回到模型配置改用 API Key 方式填 TaoToken 的三件套。OAuth 适合官方直连场景走统一 Key 接入时用不上。5.5 排查顺序建议遇到报错别慌按这个顺序查先openclaw --version确认工具本身没问题再 curl 测 TaoToken 端点确认 Key 和 Base URL 对最后看 OpenClaw 配置文件里的 Model ID 和 Gateway 端口。三步下来大部分问题都能定位。6. 接入文档与后续动作链路跑通后你可能会想继续扩展加更多模型、接聊天渠道、写自定义技能。这些都可以在 TaoToken 的文档里找到对应说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你还没创建 Key去控制台补上https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content想先试试模型对话效果可以直接用模型对话页面https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你打算长期跑编码类 Agent 任务可以看看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content我自己的习惯是装完 OpenClaw 后先跑一周本地对话确认 Gateway 稳定再把常用技能和 Hooks 加上。配置文件改之前先备份一份出问题能快速回滚。Node 版本尽量锁在 24pnpm 保持最新这两个基础环境稳了后面升级 OpenClaw 会省很多事。
阅读完成 · 觉得有帮助？
