1. 为什么我决定把 OpenClaw 跑在自己的 Linux 机器上OpenClaw 是一个开源的 AI 智能体框架核心用 TypeScript 编写、跑在 Node.js 运行时之上能让你用自然语言指挥一个“数字员工”去操作浏览器、执行命令、读写文件、调用 API。它适合谁适合已经会用命令行、想在自己项目里复现“AI 真正动手干活”这条链路的开发者而不是只想找个聊天窗口的人。我最初注意到它是因为社区里到处在传“三个月星标数冲到 25 万”这类消息。但真正让我动手的是它的技术选型Node.js TypeScript。这意味着两件事——第一npm 生态里几乎所有现成库都能被它当“技能”调用第二类型系统能在编译期就拦住大量低级错误对一个要长期在后台跑任务、还要频繁调用外部工具的框架来说这个约束非常关键。很多人把 OpenClaw 当成一个“更聪明的聊天机器人”这是误解。聊天机器人是“嘴”你问它答OpenClaw 是“手”你给它一个目标它自己拆步骤、自己调工具、自己看结果、自己纠错。这个循环在工程上叫 ReAct思考→行动→观察→反思而它落地的前提就是一个能稳定处理异步 I/O、长连接和高并发的运行时——这正是 Node.js 的强项。所以这篇不讲八卦只讲怎么在你自己的 Linux 环境里把 OpenClaw 的核心链路跑通从 Node.js 环境初始化到 TypeScript 项目配置再到接上模型、发一条真实任务、看到它真的执行。中间我会把踩过的坑和报错原文都放出来你可以直接对照排查。2. 前置准备Node.js 运行时与模型接入渠道怎么选在动手之前先把两件事定下来运行时版本和模型调用渠道。OpenClaw 对 Node.js 版本有硬性要求官方建议 22 及以上。原因不复杂它大量使用了较新的 ESM 模块规范、原生 fetch、以及部分异步迭代器特性低版本会在启动阶段直接抛语法或 API 缺失错误。你可以先用一条命令确认当前版本node -v # 期望输出v22.x.x 或更高如果低于 22别急着全局升级容易把系统里其他依赖旧版本的项目搞崩。更稳的做法是用 nvm 管理多版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 node -v第二件事是模型渠道。OpenClaw 本身只是“执行引擎”真正做推理的是背后的大模型。它支持多种接入方式但对个人开发者来说最省心的是用一个兼容 OpenAI 协议的统一入口把 Base URL、API Key、Model ID 三样东西配好就行。我这边用的是 TaoToken 的接口原因是它把多家模型的调用格式统一了切换模型时不用改代码只改配置。你需要提前拿到三样东西后面配置会反复用到配置项说明示例形态Base URL模型服务的接口根地址https://taotoken.net/apiAPI Key身份凭证形如 sk- 开头sk-xxxxxxxxModel ID具体调用的模型标识如claude-3-5-sonnet等注意API Key 等同于账号权限不要写进会提交到 Git 的明文文件里。后面我会讲怎么用环境变量隔离。把这两件事准备好环境初始化就不会卡在“装到一半发现版本不对”或者“跑起来发现没模型可用”这种低级问题上。3. 可复制配置从零初始化一个 OpenClaw 项目这一节是全文最核心的部分所有命令和配置都可以直接复制。我按“建目录 → 装依赖 → 写配置 → 起服务”的顺序来。先建项目目录并初始化mkdir -p ~/openclaw-demo cd ~/openclaw-demo npm init -y npm install openclaw装完之后项目根目录需要一份配置文件。OpenClaw 支持 JSON 和 TOML 两种格式我用 JSON因为和 Node.js 生态更贴合。新建openclaw.config.json{ runtime: { nodeVersion: 22, logLevel: info }, gateway: { port: 8787, host: 127.0.0.1 }, model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, modelId: claude-3-5-sonnet, maxTokens: 4096, temperature: 0.3 }, skills: { enabled: [shell, filesystem, http], sandbox: true }, memory: { soulFile: ./SOUL.md, memoryFile: ./MEMORY.md } }这里有几个点必须说清楚。第一apiKey我写的是${TAOTOKEN_API_KEY}这是环境变量占位符OpenClaw 启动时会去读系统环境变量避免密钥硬编码。第二baseUrl后面不要带多余的路径OpenClaw 会自己拼接/v1/chat/completions这类端点。第三sandbox: true一定要开它会让技能在受限环境里执行降低误操作风险。接着设置环境变量。临时生效可以直接 export长期生效写进 shell 配置export TAOTOKEN_API_KEYsk-你的真实key # 验证是否写入成功 echo $TAOTOKEN_API_KEY然后创建两个记忆文件OpenClaw 启动时会读取它们来定义智能体的人格和长期记忆cat SOUL.md EOF # 角色定义 你是一个严谨的工程助手执行任何文件或命令操作前先说明意图。 遇到不确定的路径或参数先询问而不是猜测。 EOF cat MEMORY.md EOF # 长期记忆 - 项目根目录~/openclaw-demo - 默认模型claude-3-5-sonnet EOF最后启动服务npx openclaw start --config ./openclaw.config.json如果一切正常终端会打印网关监听地址和已加载的技能列表。到这一步配置链路就通了。整个过程里最容易出错的是环境变量没生效——如果你在同一个终端里 export 之后又开了新窗口新窗口是读不到的记得重新 source 或写进~/.bashrc。4. 验证请求发一条真实任务看它是否真的执行配置写完不代表能用必须发一条真实任务验证。OpenClaw 的网关默认监听127.0.0.1:8787你可以用 curl 直接打它的任务接口。先确认服务活着curl -s http://127.0.0.1:8787/health # 期望返回{status:ok,skills:[shell,filesystem,http]}然后发一条会触发“动手”的任务。我选了一个能同时验证文件系统和 shell 技能的例子——让它创建一个文件并写入内容curl -s -X POST http://127.0.0.1:8787/task \ -H Content-Type: application/json \ -d { input: 在当前目录创建一个 hello.txt写入一行文字OpenClaw 链路验证成功, sessionId: test-001 }正常返回会是一个 JSON里面包含任务 ID 和状态。但真正要看的是执行结果去检查文件是否真的被创建cat ~/openclaw-demo/hello.txt # 期望输出OpenClaw 链路验证成功如果文件存在且内容正确说明整条链路——网关接收任务、模型推理、技能调用、文件写入——全部跑通了。这一步的意义在于它验证的不是“模型会不会聊天”而是“模型能不能通过框架真正操作你的环境”。再补一个稍微复杂点的验证测试它的多步推理能力curl -s -X POST http://127.0.0.1:8787/task \ -H Content-Type: application/json \ -d { input: 列出当前目录下所有 .json 文件统计它们的总行数把结果追加写入 hello.txt, sessionId: test-002 }这条任务需要它先执行ls、再对每个文件做行数统计、最后写文件属于典型的多步 ReAct 循环。如果它能正确完成说明执行引擎的“思考→行动→观察→反思”逻辑是工作的。实测下来第一次跑可能会因为模型对路径理解偏差而失败这时候看日志里它调用了什么命令就能定位是提示词问题还是技能配置问题。5. 本篇常见报错排查401、local proxy failed 与 reading choices这一节把我实际遇到过的报错按原文列出来方便你直接搜索对照。报错一401 UnauthorizedError: Request failed with status code 401 {error:{message:Invalid API key provided}}原因基本只有一个API Key 没读到或写错了。排查顺序是——先echo $TAOTOKEN_API_KEY确认环境变量有值再检查配置文件里是不是写成了${TAOTOKEN_API_KEY}而不是真实 key最后确认 key 没有多余空格或换行。如果都没问题可能是 key 本身失效去控制台重新生成一个。报错二local proxy failedError: local proxy failed to connect to upstream cause: ECONNREFUSED 127.0.0.1:7890这个报错说明你的系统里配置了本地代理但代理服务没启动。OpenClaw 的 HTTP 技能会继承系统代理设置。解决办法是检查http_proxy/https_proxy环境变量如果不需要代理就 unset 掉unset http_proxy https_proxy all_proxy然后重启 OpenClaw 服务。注意这里说的是清理本机环境变量不是让你去搭什么通道纯粹是避免残留配置干扰。报错三reading choicesTypeError: Cannot read properties of undefined (reading choices)这个报错通常出现在模型返回格式和框架预期不一致时。choices是 OpenAI 兼容接口的标准返回字段如果它是 undefined说明返回体根本不是预期结构。可能原因有两个一是baseUrl配错了请求打到了错误的端点返回了 HTML 或错误页二是modelId写了一个服务端不存在的模型服务端返回了错误对象。排查方法是把baseUrl和modelId单独拿出来用 curl 直接打一次接口看原始返回curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-3-5-sonnet,messages:[{role:user,content:hi}]}如果这条 curl 能返回正常的choices数组说明配置没问题问题在 OpenClaw 的读取逻辑如果这条也报错那就是 Base URL 或 Model ID 的问题。报错四OAuth 相关Error: OAuth token expired, please re-authenticate如果你用的是需要 OAuth 的模型渠道token 过期会报这个。解决方式是重新走一遍授权流程或者换成 API Key 方式的渠道省去刷新 token 的麻烦。对个人项目来说API Key 模式更简单可控。把这几类报错记住基本能覆盖 90% 的启动失败场景。剩下的多半是 Node.js 版本不对或依赖没装全回去看第二节的版本检查即可。6. 把 OpenClaw 接进你的项目从验证到长期使用跑通验证只是第一步真正有价值的是把它接进你日常的开发流。这里给几个我实践下来的方向。第一把常用任务固化成脚本。上面那些 curl 命令可以包成一个 shell 函数比如oc-task 你的指令省去每次拼 JSON 的麻烦。更进一步可以把 OpenClaw 的网关当成一个本地服务让你的其他程序通过 HTTP 调用它相当于给你的项目加了一个“能动手的执行层”。第二模型选择上做分层。日常对话和简单任务用便宜快速的模型复杂推理再切到能力更强的模型。因为 OpenClaw 的配置里modelId是独立字段你可以在不同任务里传不同的模型标识不用改代码。这也是用统一接口入口的好处——切换成本极低。第三长期跑的话一定要开日志和审计。OpenClaw 的logLevel设成info能看到每次工具调用的入参和返回设成debug能看到完整的推理链。定期翻日志既能发现异常行为也能反过来优化你的提示词。第四权限最小化。skills.enabled里只开你真正需要的技能比如你不需要它操作浏览器就别开 browser 相关技能。sandbox: true保持开启。这些配置在openclaw.config.json里改完重启服务即可生效。如果你打算把它用在更长期的编码或 Agent 场景里可以考虑用 Coding Plan 这类固定额度的方案来控制成本避免按量计费时因为一个死循环任务把额度跑爆。模型对话调试阶段则可以直接在对话界面里试提示词确认效果后再写进配置。最后说一个我踩过的坑改完配置文件后一定要重启服务OpenClaw 不会热加载配置。我一开始改了modelId却没重启排查了半天以为接口有问题结果只是进程还在用旧配置。重启命令就是前面那条npx openclaw start先 CtrlC 停掉再起。到这里从环境初始化到任务验证再到长期接入的完整链路就齐了。你可以先照着第三节的配置跑一遍遇到报错翻第五节跑通之后再按第六节的思路往自己项目里搬。