openclaw 2026.2.1 安装实录：npm、nodejs 与 gateway 配置到 TaoToken

1. openclaw 2026.2.1 安装实录从零跑通 npm、nodejs 与 gateway 配置openclaw 2026.2.1 是一个可以本地部署的 AI Agent 网关它能把你常用的模型服务统一收口到一个 gateway 里再通过浏览器界面或插件对外提供对话能力。简单说它解决的是「模型太多、Key 太散、调用方式不统一」的问题。适合谁适合手里有一台 4G 以上内存的服务器、想自己掌控模型调用链路、又不想被某个平台绑死的开发者。我这次是在一台干净的 Linux 机器上从零开始装全程踩了几个坑尤其是 nodejs 版本和 gateway 的 bind 参数下面把完整链路拆开讲。先说结论openclaw 2026.2.1 的安装本身不复杂真正容易卡住的是三件事——nodejs 版本太低导致 npm 装不上、gateway 的 mode 和 bind 配错导致浏览器打不开、以及配置文件里 apiKey 没换成自己的。这篇文章会按「环境准备 → 安装 → 配置 → 启动 → 验证 → 排错」的顺序走一遍每一步都给可复制的命令和配置片段。你跟着做基本能在半小时内看到聊天界面。需要提前说明的是openclaw 2026.3 及以上版本有安全限制要求必须通过 HTTPS 或本地安全上下文比如 localhost访问这是为了防止未加密连接被滥用。我们这篇聚焦的是 2026.2.1它对本地 http 访问更宽松适合先在自有环境跑通。如果你后面要升级记得提前用 nginx 做代理并配好证书。另外模型服务这块我用的是 TaoToken 作为统一入口。它的好处是一个 Key 就能调多家模型baseUrl 和 model id 的写法跟 openclaw 的 provider 配置能对上省得你到处找厂商文档。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 后面配置里会用到。2. 环境准备与 nodejs、npm 版本校验openclaw 安装前置依赖怎么配这一节解决的是「装之前机器上该有什么」。openclaw 2026.2.1 对 nodejs 版本有要求实测下来 v20 以上比较稳我这次用的是 v24.12.0。如果你机器上还是 v16 甚至更老npm 在装 openclaw 时会直接报 engine 不匹配或者装到一半卡住。先装基础编译工具很多 npm 包的 native 依赖需要它们yum install -y git wget gcc-c make cmake yum install -y wget tar xz xz-devel然后下载 nodejs 二进制包。用二进制包而不是包管理器是为了版本可控避免系统自带的 node 版本太旧cd /usr/local/src wget -c https://nodejs.org/dist/v24.12.0/node-v24.12.0-linux-x64.tar.xz tar xf node-v24.12.0-linux-x64.tar.xz mv node-v24.12.0-linux-x64 /usr/local/node echo export PATH/usr/local/node/bin:$PATH /etc/profile source /etc/profile校验版本这一步别跳过node -v npm -v正常应该输出 v24.12.0 和对应的 npm 版本。如果 node -v 报 command not found说明 PATH 没生效重新 source 一下 /etc/profile或者检查你写进去的路径对不对。接着设置 npm 镜像源。国内直连官方源经常超时换成 npmmirror 会快很多npm config set registry https://registry.npmmirror.com npm config set git $(which git)这里有个小坑npm config set git 是为了让某些依赖在安装时能找到 git 可执行文件如果你机器上没装 git这步会报错所以前面 yum 那行一定要先执行。环境准备好之后跑一下 openclaw 的 setup 命令指定本地模式openclaw setup如果这时提示 openclaw 命令不存在别慌那是因为还没全局安装setup 这步在部分版本里是安装后才会有的子命令。你可以先跳到下一节做全局安装再回来跑 setup。我实测的顺序是先 npm install -g再 openclaw setup最后 doctor --fix。内存方面官方建议至少 4G。我试过 2G 的机器gateway 启动后加载模型列表时会 OOM所以别省这点内存。磁盘留 10G 以上npm 全局包加上插件依赖占用不算小。3. openclaw 2026.2.1 全局安装与 gateway 配置片段含 TaoToken 接入这一节是核心包含安装命令、配置文件、以及 gateway 的启动参数。先做全局安装npm install -g openclaw2026.2.1 --verbose --force加 --verbose 是为了出错时能看到具体卡在哪--force 是防止某些缓存导致的冲突。如果装失败先卸载再重装npm uninstall -g openclaw npm install -g openclaw2026.2.1 --verbose --force装完之后配置文件在 ~/.openclaw/openclaw.json。这个文件决定了模型 provider、agent、gateway 三块。下面是我实测可用的配置片段注意把 apiKey 换成你自己的{ meta: { lastTouchedVersion: 2026.2.1, lastTouchedAt: 2026-04-03T08:38:22.202Z }, wizard: { lastRunAt: 2026-04-03T08:38:22.191Z, lastRunVersion: 2026.2.1, lastRunCommand: doctor, lastRunMode: local }, models: { mode: merge, providers: { taotoken: { baseUrl: https://taotoken.net/api/v1, apiKey: 你的TaoToken Key, api: openai-completions, models: [ { id: claude-sonnet-4-5, name: TaoToken Claude Sonnet, reasoning: false, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 200000, maxTokens: 8192 } ] } } }, agents: { defaults: { models: { taotoken/claude-sonnet-4-5: { alias: taotoken } }, maxConcurrent: 4, subagents: { maxConcurrent: 8 } }, list: [ { id: main, name: main, workspace: /root/.openclaw/workspace, agentDir: /root/.openclaw/agents/main/agent, model: taotoken/claude-sonnet-4-5 } ] }, messages: { ackReactionScope: group-mentions }, commands: { native: auto, nativeSkills: auto, restart: true }, gateway: { port: 18789, mode: local, bind: lan, controlUi: { allowInsecureAuth: true }, auth: { mode: token, token: 3f650da1b6ccce9297efeb1990d5a2520bb5951723b87016 } }, plugins: { entries: {} } }几个关键点解释一下。baseUrl 我写的是 https://taotoken.net/api/v1 这是 OpenAI 兼容格式的路径openclaw 的 api 字段设成 openai-completions 就能对接。model id 要跟你实际想用的模型对上TaoToken 支持多家模型具体 id 可以在模型对话页面查。gateway 的 bind 设成 lan表示监听局域网地址这样你用服务器 IP 就能访问如果设成 localhost那就只能本机 curl浏览器从外部打不开。mode 设成 local 是本地模式配合 allowInsecureAuth 允许 http 访问这在 2026.2.1 上是可行的。还要建一个 auth-profiles.json路径在 ~/.openclaw/agents/main/agent/auth-profiles.json{ taotoken:default: { provider: taotoken, mode: api-key } }这个文件告诉 openclaw 用 api-key 模式去调 taotoken 这个 provider。两个文件都改好之后跑一次修复命令openclaw doctor --fixdoctor 会检查配置结构、路径、权限有问题的字段它会提示。我遇到过一次 models.providers 里 provider 名字和 agents 里引用的名字不一致doctor 直接报出来了改完就好。4. 启动 gateway 并验证请求openclaw 服务可用性怎么确认配置改完启动 gatewayopenclaw gateway start如果之前已经启动过用 restart 更稳openclaw gateway restart启动后浏览器访问http://你的服务器IP:18789/chat?token3f650da1b6ccce9297efeb1990d5a2520bb5951723b87016token 就是配置文件里 gateway.auth.token 那个值。能打开聊天界面说明 gateway 起来了。如果页面转圈或者报 401先看下一节的排错。除了浏览器也可以用 curl 验证 API 是否通curl -X POST http://127.0.0.1:18789/v1/chat/completions \ -H Authorization: Bearer 3f650da1b6ccce9297efeb1990d5a2520bb5951723b87016 \ -H Content-Type: application/json \ -d { model: taotoken/claude-sonnet-4-5, messages: [{role: user, content: 你好测试一下}] }正常会返回一段 JSONchoices 里有模型回复。如果返回 401说明 token 不对如果返回 model not found说明 model id 跟配置里对不上如果连接被拒说明 gateway 没起来或者端口没监听。再确认一下端口监听状态ss -tlnp | grep 18789应该能看到 node 进程在监听。如果 bind 设的是 lan这里显示的应该是 0.0.0.0:18789 或 :::18789如果只显示 127.0.0.1:18789那外部访问不了需要把 bind 改成 lan 再重启。模型调用这块我建议先在 TaoToken 的模型对话页面确认 Key 和模型 id 可用再填进 openclaw。因为 openclaw 的报错有时候比较笼统先在模型对话里验证一遍能排除掉一半问题。模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 登录后能直接试。验证通过后你可以在聊天界面发一条消息看是否正常返回。如果返回内容为空但状态码 200多半是 maxTokens 或 contextWindow 设得太小或者模型 id 对应的模型不支持当前请求格式。把 maxTokens 调到 8192 再试。5. openclaw 安装常见报错排查401、local proxy failed、reading choices 怎么解这一节按真实报错来。我装的时候踩了三个逐个说。第一个401 Unauthorized。浏览器打开聊天页提示未授权或者 curl 返回 401。原因通常是 token 不匹配。检查三处配置文件 gateway.auth.token、URL 里的 token 参数、curl 的 Authorization 头。三处必须完全一致。另外如果你改过配置文件但没重启 gateway旧 token 还在内存里restart 一下。第二个local proxy failed。这个报错一般出现在 gateway 启动阶段日志里会写 local proxy failed to bind。原因是端口被占用或者 bind 地址不可用。先查端口ss -tlnp | grep 18789如果有别的进程占着换端口比如把 gateway.port 改成 18790。如果端口没被占但 bind 设的是某个不存在的网卡地址也会失败改成 lan 或 0.0.0.0。第三个reading choices 相关报错类似 cannot read property choices of undefined。这是模型返回结构跟 openclaw 预期不一致。常见于 baseUrl 写错比如漏了 /v1或者 api 字段没设成 openai-completions。检查 models.providers 里的 baseUrl 是不是 https://taotoken.net/api/v1 api 是不是 openai-completions。如果用的是别的厂商确认它的返回格式是不是 OpenAI 兼容。第四个OAuth 相关报错。如果你在配置里误开了 OAuth 模式但没配对应的 client id会报 OAuth flow failed。openclaw 2026.2.1 里用 api-key 模式就够了auth-profiles.json 里 mode 设成 api-key别设 oauth。第五个npm install 时报 engine 不匹配。这是 nodejs 版本太低。回到第二节确认 node -v 输出的是 v20 以上。如果系统里有多套 node用 which node 看当前用的是哪个。第六个doctor --fix 后配置被改乱。doctor 有时会把不认识的字段删掉。改之前先备份cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak出问题就还原。排错时多看日志gateway 的日志一般在 ~/.openclaw/logs/ 下或者启动时加 --verbose。日志里会写清楚是哪一步失败。如果你在接入过程中需要确认 Key 的权限和模型列表可以去控制台看https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Key 的管理在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各语言的调用示例对着改 baseUrl 就行。6. 长期编码与 Agent 场景用 Coding Plan 把 openclaw 跑成日常工具openclaw 跑通之后如果你打算长期用它做编码辅助或者 Agent 任务单次按量调用可能不够划算也不方便管理额度。TaoToken 的 Coding Plan 是面向长期编码场景的订阅方案适合把 openclaw 当成日常工具来用的开发者。入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。配置上Coding Plan 的 Key 和普通 API Key 用法一致填进 openclaw.json 的 apiKey 字段就行baseUrl 不变。model id 按你订阅里包含的模型填。如果你用的是 Claude Code 这类工具TaoToken 也提供了对应的接入方式文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里有说明。回到 openclaw 本身跑通之后你可以做几件事一是把多个模型配成不同 agent按任务切换二是装插件扩展能力比如企业微信插件让 openclaw 能在群里响应三是把 gateway 暴露给内网其他服务调用。企业微信插件的安装命令是openclaw plugins install wecom/wecom-openclaw-plugin装完用 openclaw plugins list 确认再用 openclaw plugins doctor 检查健康状态。配渠道用 openclaw channels add按引导选企业微信填 Bot ID 和 secret最后用 openclaw pairing approve wecom 配对码 完成配对。这块我还没实战完但命令链路是通的你可以先按这个顺序试。最后提醒一句openclaw 2026.2.1 的 gateway 默认允许 http 访问方便本地调试但如果你要放到公网务必上 nginx 做 HTTPS 代理或者升级到 2026.3 以上版本用它的安全限制。配置文件改完记得 doctor --fix 和 restart这两步能省掉很多莫名其妙的报错。