1. 刚装完 OpenClaw 的那半小时我踩了哪些坑OpenClaw 是一个可以在本地跑起来的开源 AI 助手平台核心卖点是「助手逻辑跑在你自己机器上模型调用走你指定的 API 通道」。它适合两类人一类是想把 AI 助手接进自己工作流、又不想把会话数据全交给第三方的开发者另一类是手里已经有统一 Key 通道想把 OpenClaw 当成一个可编排的本地 Agent 壳来用的人。你如果是刚npm install完、对着黑窗口不知道敲什么这篇就是给你写的。我第一次装完 OpenClaw 的时候犯了个很典型的错误直接openclaw回车然后盯着它默认去连某个公共端点等了半天报了个超时。后来才反应过来OpenClaw 本身不带模型它只是个「调度层」你得先告诉它模型从哪来。这个「从哪来」的配置就落在settings文件里。所以正确的顺序应该是先确认命令能跑openclaw version再确认网关状态openclaw gateway status然后把settings里的 Base URL、Key、Model ID 三件套指向你的统一通道最后用一条openclaw sessions send验证整条链路通不通。这四步走完十分钟足够。很多人卡在第三步因为 OpenClaw 的配置项命名和别的工具不太一样provider、baseUrl、apiKey、model这几个字段散在 JSON 里少一个就报401或者local proxy failed。下面我按「命令速查 → 配置落地 → 验证 → 排障」的顺序拆开讲每一段都能直接复制去用。先给一个全局认知OpenClaw 的命令大致分五组——基础status/help/version、会话sessions、技能skills、网关gateway、配置config。你日常 80% 的时间只会用到sessions send、gateway restart、config get/set这三类。剩下的等你要装技能、查历史时再翻。2. 把 settings 指向 TaoToken 统一通道的前置准备在动settings之前你得先有一个能用的 API 通道。这里我用 TaoToken 做演示因为它把多家模型的调用统一成一个 Base URL 一个 Key省得你在 OpenClaw 里为每个模型配一套 provider。对刚入门的人来说少配一个字段就少一个报错来源。第一步是拿 Key。打开https://taotoken.net/api-keys登录后创建一个新 Key复制出来先存到记事本。注意这个 Key 只在创建时完整显示一次关掉页面就看不全了所以别手滑。第二步是确认你要用的 Model ID。OpenClaw 的settings里model字段填的不是「gpt-4」这种口语名而是通道支持的规范 ID。你可以在https://taotoken.net/models页面查到当前可用的模型列表挑一个你熟悉的比如做代码补全就选偏 coding 的做通用对话就选通用款。把 ID 原样记下来大小写敏感。第三步是确认 Base URL。TaoToken 的 API 入口是https://taotoken.net/api注意这里不要加任何查询参数OpenClaw 会自己在后面拼/v1/chat/completions这类路径。如果你手贱加了?utm_source...请求路径就会变成.../api?v1/chat/completions直接 404。第四步找到 OpenClaw 的配置文件位置。不同安装方式路径不一样最稳的办法是用命令问它openclaw config path如果这条命令你的版本不支持就退而求其次openclaw config get provider它会回显当前 provider 配置顺带把配置文件所在目录暴露出来。常见位置是~/.openclaw/settings.json或者项目根目录下的openclaw.config.json。我实测下来全局安装的默认在用户目录项目内安装的优先读项目根目录。这里有个坑要提前说OpenClaw 会同时读全局配置和项目配置项目配置优先级更高。如果你改了全局的没生效八成是项目根目录下有个旧的openclaw.config.json在覆盖。用openclaw config get baseUrl看它实际读到的值比猜靠谱。准备好 Key、Model ID、Base URL 这三样再确认配置文件路径前置就算完成了。接下来直接改settings。3. 可复制的 settings 配置片段与逐条命令OpenClaw 的settings是 JSON 格式核心就一个provider块。下面这段可以直接复制把三个占位符换成你自己的{ provider: { type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, model: 你的Model ID, timeout: 60000 }, gateway: { port: 8787, host: 127.0.0.1 }, session: { store: ~/.openclaw/sessions } }几个字段逐个说清楚。type填openai-compatible因为 TaoToken 的接口兼容 OpenAI 的请求格式OpenClaw 用这个类型就能正确拼请求体。baseUrl就是上面说的https://taotoken.net/api结尾不要带斜杠带了会拼出双斜杠部分网关会拒。apiKey填你复制的 Key注意别把引号漏了。model填规范 ID。timeout我设了 60 秒因为有些推理型模型首 token 来得慢默认 30 秒容易误判超时。改完保存然后逐条验证。先让 OpenClaw 重新加载配置openclaw config reload如果你的版本没有reload子命令就重启网关代替openclaw gateway restart接着确认它读到的值和你写的一致openclaw config get provider.baseUrl openclaw config get provider.model第一条应该回显https://taotoken.net/api第二条回显你的 Model ID。如果回显的是旧值说明你改的文件不是它实际读的那个回到上一节用config path再确认一次。然后启动网关openclaw gateway start openclaw gateway statusstatus正常会显示running加监听端口。如果显示stopped或者端口被占先openclaw gateway stop再start端口冲突就改settings里的gateway.port。到这里配置就落地了。下一步是发一条真实请求验证整条链路。4. 验证请求跑通第一条 OpenClaw 命令配置对不对发一条消息就知道。OpenClaw 的会话命令是sessions先建一个会话或者直接用默认的openclaw sessions list如果列表是空的直接发消息它会自动建openclaw sessions send default 用一句话解释什么是递归这条命令会走完整链路OpenClaw 读settings→ 拼请求 → 打到https://taotoken.net/api→ 拿回结果 → 打印到终端。正常输出类似[default] assistant: 递归就是函数在定义中调用自身把大问题拆成同类的小问题直到触达一个不再拆分的基准情况。看到这段文字说明 Base URL、Key、Model ID 三件套全对链路通了。如果返回的是空或者报错往下看第五节。想验证多轮上下文可以接着发openclaw sessions send default 那它和迭代有什么区别它会带上上一轮的上下文再请求。如果第二轮能正确引用「递归」这个词说明会话存储也正常。再验证一下技能系统确认 OpenClaw 的扩展能力可用openclaw skills list正常会列出内置技能。想装一个试试openclaw skills install web-search openclaw skills list装完再sessions send一条需要联网的问题看它会不会调用技能。这一步不是必须的但能帮你确认 OpenClaw 不只是个「套壳聊天」而是真的能编排工具。最后把常用命令串一遍形成肌肉记忆openclaw version # 确认版本 openclaw status # 整体状态 openclaw gateway status # 网关状态 openclaw config get provider.model # 确认模型 openclaw sessions send default 测试 # 发消息这五条覆盖了日常 90% 的场景。剩下的sessions history、skills update、config edit等等用到再查openclaw help。5. 常见报错排查401、local proxy failed、reading choices这一节按真实报错来对。你大概率会撞上下面几个之一。报错一401 Unauthorized或invalid api key原因基本是 Key 不对。三种可能Key 复制时漏了尾部字符settings里apiKey的引号没配对导致解析成空或者你用的是别的通道的 Key。排查动作openclaw config get provider.apiKey看回显的 Key 和你复制的是否一致。如果回显是undefined说明 JSON 格式错了用openclaw config edit打开检查括号和逗号。确认无误后openclaw gateway restart再试。报错二local proxy failed或ECONNREFUSED这个通常不是 Key 的问题而是 OpenClaw 的本地网关没起来或者baseUrl指向了一个本地不存在的代理。先查网关openclaw gateway status如果是stoppedopenclaw gateway start。如果网关是 running 但还报这个检查settings里baseUrl是不是被误改成了http://127.0.0.1:xxxx这类本地地址。正确值应该是https://taotoken.net/api。改完重启网关。报错三reading choices或Cannot read properties of undefined (reading choices)这是 OpenClaw 拿到了一个不符合 OpenAI 格式的响应去取choices[0]时炸了。常见原因是baseUrl拼错了路径比如结尾多了斜杠变成//v1/chat/completions或者model填了一个通道不支持的 ID通道返回了错误结构。排查openclaw config get provider.baseUrl openclaw config get provider.modelBase URL 必须是https://taotoken.net/api结尾无斜杠。Model ID 去https://taotoken.net/models核对确保一字不差。两个都对还报就在settings里把timeout调到 120000排除是超时导致的半截响应。报错四OAuth相关或token expiredOpenClaw 某些版本会尝试走 OAuth 流程拿 token如果你用的是纯 API Key 模式这个流程是多余的。检查settings里provider.type是不是openai-compatible如果是oauth就改掉。改完openclaw gateway restart。报错五命令找不到command not found: openclaw安装没进 PATH。全局安装的话确认 npm 全局 bin 目录在 PATH 里项目内安装就用npx openclaw代替openclaw。这个和配置无关但新手经常卡在这。排查的核心思路就一条先确认配置读对了再确认网关起来了最后确认请求打对了地址。这三步覆盖 95% 的报错。6. 把 OpenClaw 接进日常从速查到顺手命令速查只是起点真正让 OpenClaw 好用的是把它接进你的日常流程。我自己的做法是把openclaw sessions send包一层 shell 函数比如ask() { openclaw sessions send default $1; }这样终端里ask 帮我写个正则就直接出结果不用每次敲全。配置层面如果你同时用多个工具比如 Cline、Codex 之类可以把它们都指向同一个 TaoToken 通道Key 和 Model ID 复用省得每个工具配一遍。OpenClaw 的settings结构简单改起来快适合当「第一个接通的工具」验证通道没问题后再去配别的。技能系统值得花点时间。openclaw skills list看内置的skills install装社区的装完在settings里可以给技能配独立的超时和权限。这块文档在https://taotoken.net/doc有对应的接入说明配合着看更快。最后提醒一句settings改完一定要gateway restartOpenClaw 不会热加载 provider 配置。我踩过这个坑改完以为生效了结果发的消息还是走旧配置白白排查了二十分钟。养成「改配置 → 重启网关 →config get确认 → 发消息验证」的习惯能省掉大部分玄学报错。到这一步你应该已经能用 OpenClaw 跑通第一条命令并且知道出问题去哪查了。剩下的就是多用把命令敲成肌肉记忆。