1. 为什么第一次跑 OpenClaw 总卡在环境上OpenClaw 是一个可以本地部署、通过聊天渠道驱动的 AI Agent 运行框架简单说就是给你的大模型装上一双手能读文件、跑命令、调工具、记上下文。它适合想在自己电脑或服务器上跑一个「常驻助手」的开发者尤其是已经用过 Cline、Claude Code 这类工具、想再往前一步做自动化的人。但很多人第一次装 OpenClaw卡住的地方往往不是 OpenClaw 本身而是三件事Node 版本不对、安装脚本拉不下来、模型通道没配通。我见过太多人npm install -g openclaw之后openclaw --version报 command not found或者 onboard 向导走到「配置 AI 模型」那一步填了 Key 却一直转圈。这篇就按「本地安装 → 依赖检查 → 首个任务运行」的顺序走一遍目标很明确30 分钟内让你看到第一个任务真的跑出结果。中间会重点讲怎么用 TaoToken 统一 Key 和 API 通道把模型调用这一环一次性配好避免你在多个厂商的 Key 之间来回折腾。先说清楚运行环境怎么选。云服务器 24 小时在线、不怕断电适合想让助手全天候待命的人但新手一开始成本偏高自己的电脑或 Mac Mini 零门槛、立刻能开始缺点是关机就没了适合先试玩。我建议第一次就跑在本地跑通了再考虑搬到服务器。依赖这块OpenClaw 需要 Node.js 22 及以上。先检查node -v npm -v如果node -v输出低于 v22别急着装 OpenClaw先把 Node 升上去。用 nvm 最省事curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22Windows 用户建议先装 WSL2在 WSL 里操作会顺很多。以管理员身份打开 PowerShell 运行wsl --install重启后进 Ubuntu再按上面的 Linux 步骤走。这一步别跳过原生 Windows 下 OpenClaw 的守护进程和 Gateway 行为跟 Linux 差异较大新手容易踩坑。环境确认完再往下走安装。下面第二节先把 TaoToken 这条模型通道准备好因为 onboard 向导中途会要你填 API Key提前备好能少一次中断。2. TaoToken 前置准备统一 Key 与 API 通道OpenClaw 的 onboard 向导会问你选哪个模型提供商、填哪个 API Key。如果你手上有好几家的 Key每换一个模型就要改一次配置很烦。TaoToken 的作用就是把这些模型调用收敛到一个入口一个 Key、一个 Base URL后面换模型只改 Model ID 就行。先注册并拿到 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 完成账号注册后进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在里面找到 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 新建一个 Key 并复制保存。这个 Key 只显示一次丢了只能重建。拿到 Key 之后记住两个东西Base URLhttps://taotoken.net/apiAPI Key你刚复制的那串OpenClaw 的模型配置本质上是 OpenAI 兼容格式所以 Base URL 填 TaoToken 的 API 地址Key 填你新建的Model ID 填你想用的模型名。具体模型名可以在模型对话页面确认https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 或者在文档里查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。这里有个关键点OpenClaw 的 onboard 向导里模型提供商列表不一定直接有「TaoToken」这个选项。遇到这种情况选「OpenAI Compatible」或「Custom OpenAI」这类通用项然后手动填 Base URL 和 Key。如果向导只让你填 Key 不让你填 Base URL那就先随便选一个等向导跑完再用openclaw configure改配置文件。为了让你心里有底先验证一下这个 Key 能不能通。用 curl 直接打一次curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的Key \ -H Content-Type: application/json \ -d { model: 你的ModelID, messages: [{role: user, content: ping}] }返回里有choices字段就说明通道没问题。这一步很重要因为后面 OpenClaw 报错时你要能区分是 OpenClaw 配置问题还是 Key 本身问题。如果这里就 401先回控制台检查 Key 是否复制完整、是否被禁用。如果你打算长期跑编码类或 Agent 类任务可以顺手看一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合高频调用的场景。第一次跑通任务用普通 Key 就够了不用一上来就上套餐。Key 备好、通道验证通过接下来进安装和配置。3. 可复制配置安装 OpenClaw 并接入 TaoToken安装有三种方式我按成功率从高到低排。方式一npm 全局安装最稳npm install -g openclaw openclaw --version看到版本号就成功了。如果报 command not found多半是 npm 全局 bin 目录不在 PATH 里运行npm config get prefix看路径把它加到 PATH。方式二官方一键脚本# macOS / Linux curl -fsSL https://openclaw.ai/install.sh | bash# Windows PowerShell iwr -useb https://openclaw.ai/install.ps1 | iex这个脚本我试过有时候会因为网络原因中途失败失败就退回方式一别死磕。方式三源码安装适合要改代码的开发者git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm build装完跑初始化向导openclaw onboard向导会依次问安全提示选 Yes、Onboarding 模式选 QuickStart自动配网关端口 18789、绑定 127.0.0.1、AI 模型提供商、是否装后台守护进程选 Yes、健康检查、技能安装、Hooks、Gateway 服务。走到「配置 AI 模型」这一步就是接 TaoToken 的地方。如果向导支持自定义 Base URL直接填Base URL: https://taotoken.net/api API Key: 你的Key Model ID: 你的ModelID如果向导里没有自定义入口先跳过或随便选向导跑完后手动改配置文件。OpenClaw 的配置一般在~/.openclaw/目录下模型相关配置类似这样JSON 格式{ models: { default: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: 你的Key, model: 你的ModelID } }, gateway: { port: 18789, host: 127.0.0.1 } }注意路径和字段名以你本机openclaw configure生成的实际文件为准别直接覆盖。改完保存重启守护进程openclaw daemon restart技能那一步会问一堆 API Key比如 GOOGLE_PLACES_API_KEY、GEMINI_API_KEY、NOTION_API_KEY、OPENAI_API_KEY 等没有就全选 No后续用openclaw configure随时补。Hooks 建议全开boot-md、command-logger、session-memory 这三个分别负责启动加载、命令日志、会话记忆对调试很有用。Gateway 服务安装完向导会显示 Control UI 地址类似http://127.0.0.1:18789/记住它。到这里配置就齐了下一节验证。4. 验证请求跑通第一个 OpenClaw 任务先确认 Gateway 活着openclaw gateway status openclaw healthgateway status显示 running、health全绿说明服务层没问题。然后打开浏览器访问http://127.0.0.1:18789/能看到 Web 控制面板就对了。也可以用openclaw dashboard直接打开。第一个任务别搞复杂就让助手读一个本地文件并总结。在 Web UI 的对话框里输入读取当前目录下的 README.md用三句话总结它的内容如果模型通道配对了你会看到它先调用工具读文件再返回总结。这一步能跑通说明「模型调用 工具执行 上下文」整条链路是通的。如果 Web UI 不方便用命令行也能验证。OpenClaw 支持直接发指令openclaw run 列出当前目录的文件并告诉我哪个是最大的观察输出正常的话它会执行ls之类的命令再给结论。这里如果卡住不动八成是模型通道的问题回上一节用 curl 再测一次 Key。再验证一下会话记忆 Hook 有没有生效。发一条/new开新会话然后问它「我们刚才聊了什么」如果 session-memory 正常它能回忆起上一轮内容。这一步不是必须但能帮你确认 Hooks 配置对了。跑通之后日常管理命令记几个就够openclaw status # 整体状态 openclaw gateway status # 网关状态 openclaw health # 健康检查 openclaw configure # 改模型、频道 openclaw daemon restart # 重启后台 openclaw daemon logs # 看日志openclaw daemon logs是你后面排障最常用的命令任何异常先看日志。5. 本篇常见错排查401、local proxy failed 与 OAuth第一个高频错误是 401。表现是任务发出去后返回401 Unauthorized或invalid api key。原因通常是 Key 复制时带了空格、Key 被禁用、或者 Base URL 写成了https://taotoken.net少了/api。排查顺序先用第 2 节的 curl 命令单独测 Key通了再查 OpenClaw 配置文件里的 baseUrl 和 apiKey 字段。注意 JSON 里 Key 要用引号包住别漏。第二个是local proxy failed或connection refused。这通常是 Gateway 没起来或者端口被占。先openclaw gateway status如果是 stoppedopenclaw daemon restart。如果重启后还是失败看openclaw daemon logs常见原因是 18789 端口被别的进程占了改配置里的 port 换一个再重启。第三个是reading choices相关报错比如cannot read property choices of undefined。这说明请求发出去了但返回体不是预期的 OpenAI 格式多半是 Model ID 填错了或者 Base URL 指向了不支持该模型的服务。回模型对话页面确认 Model ID 拼写再确认 Base URL 是https://taotoken.net/api。第四个是 OAuth 相关报错出现在你选了需要 OAuth 的模型提供商时。如果你用的是 TaoToken 的 Key就不该走 OAuth 流程回openclaw configure把提供商改成 OpenAI Compatible填 Base URL Key Model ID 三件套。这三件套缺一不可尤其是 Model ID很多人只填了前两个结果请求发出去模型名为空直接报错。还有一个隐蔽的坑Node 版本。OpenClaw 要 Node 22如果你用 nvm 装了 22 但当前 shell 还是旧版本openclaw可能跑在旧 Node 上。node -v确认一下不对就nvm use 22再重启 daemon。排障时记住一个原则先分层再定位。Key 层用 curl 测服务层用 gateway status 测配置层看配置文件。三层分开测比盯着一个报错瞎改快得多。6. 把通道固定下来后面换模型只改一个字段跑通第一个任务之后建议你做一件事把 TaoToken 的 Base URL 和 Key 固定写进 OpenClaw 的模型配置Model ID 单独拎出来。这样以后想换模型只改 Model ID 一个字段不用动 Key 和地址。长期跑编码或 Agent 任务的话Coding Plan 那条通道更适合高频场景可以按需切过去。接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到配置字段不确定就翻它。模型列表在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 换模型前来这里确认 Model ID 拼写。最后留一个实用习惯每次改完配置先openclaw daemon restart再openclaw health两步都过了再发任务。这个顺序能帮你把「配置没生效」和「配置本身错了」区分开省掉大量来回试的时间。
