1. 为什么新手第一次跑 OpenClaw 最容易卡在模型接入OpenClaw原名 Clawdbot、Moltbot是一个开源的个人 AI 助手平台能跑在你自己的电脑或一台低功耗小主机上再通过聊天渠道跟你对话。它和普通聊天机器人的区别在于它不只是回答问题还能调用工具、操作浏览器、跑定时任务、维护长期记忆。对个人开发者来说它更像一个可以自己掌控数据、自己决定接哪个模型的“私人助理底座”。但很多人第一次装完 OpenClaw卡住的地方不是安装脚本而是“模型接不进去”。表现通常是网关起来了、控制面板能打开、聊天渠道也配好了可一发消息就报错或者干脆没有任何回复。翻日志能看到401、model not found、reading choices之类的字样。原因往往不是 OpenClaw 本身有问题而是模型提供方的 Base URL、API Key、Model ID 这三件套没对齐。这篇面向刚接触 OpenClaw 的个人开发者目标很明确从零搭出一个能完成一次完整问答闭环的本地 AI 助手。我会把安装、模型接入、基础对话链路拆成可复制的步骤配置文件片段直接给出来每一步都配一条验证动作。你跟着做最后能在本地发一句话、收到模型回复这条链路就算通了。适合谁看手上有 Node.js 环境、想在自己机器上跑一个 AI 助手、对命令行不排斥的个人开发者。如果你之前只用过网页版聊天工具没配过 API也没关系我会把每个参数讲清楚它对应什么。先说清楚一个前提OpenClaw 本身是本地运行的框架它不绑定任何一家模型。你要给它一个能调用的模型接口它才能干活。所以“把本地 AI 助手跑起来”这件事本质是两段第一段把 OpenClaw 装好并启动第二段把模型接口接进去并验证。很多人只做了第一段就以为完成了结果对话链路是断的。我实测下来最省事的路径是先用官方脚本或 npm 把 OpenClaw 装上跑一次onboard向导生成默认配置然后手动改模型那一段配置把 Base URL、Key、Model ID 填对最后用一条命令行请求验证。下面按这个顺序展开。2. TaoToken 前置准备拿到 Base URL、API Key 和 Model ID在改 OpenClaw 配置之前先把模型侧的三件套准备好。OpenClaw 支持多种模型提供商配置方式是在~/.openclaw/openclaw.json里指定 provider 和对应参数。对个人开发者来说最直接的方式是准备一个兼容 OpenAI 接口协议的服务这样 OpenClaw 里选openai类型的 provider 就能对接。这里我用 TaoToken 作为模型接入方来演示因为它提供的就是标准的 OpenAI 兼容接口Base URL 和 Key 的填法和接 OpenAI 完全一致OpenClaw 不需要额外适配。你需要在 TaoToken 控制台创建一个 API Key并确认要用的 Model ID。第一步打开控制台创建 Key。地址是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content登录后在 API Keys 页面新建一个 Key。创建完立刻复制保存页面刷新后通常不再完整显示。这个 Key 就是后面配置里的apiKey字段。第二步确认 Base URL。TaoToken 的接口地址是https://taotoken.net/api注意这个地址后面不加任何 UTM 参数配置里原样填。OpenClaw 里如果 provider 类型是 OpenAI 兼容Base URL 一般填到/api这一层具体拼接由客户端处理。第三步确认 Model ID。在模型列表或文档里找到你要用的模型标识比如某个具体的模型名。这个字符串要一字不差地填进配置的model字段大小写和连字符都不能错否则会报model not found。如果你不确定该选哪个模型可以先在模型对话页面手动试一条确认这个 Model ID 能正常返回内容再去配 OpenClaw。地址是https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。在网页里发一句话能收到回复说明 Key 和 Model ID 都是有效的这一步能帮你排除掉一半的配置错误。注意API Key 属于敏感凭据不要写进会提交到 Git 的配置文件里。OpenClaw 的凭据目录是~/.openclaw/credentials/建议把 Key 放在这里或环境变量里配置文件里用引用方式读取。三件套准备好之后先别急着改 OpenClaw。我建议用一个最简的 curl 请求先验证一次确认 Key、Base URL、Model ID 三者能配合工作。命令如下curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的API_KEY \ -d { model: 你的Model_ID, messages: [{role: user, content: 你好回复一个字}] }如果返回的 JSON 里有choices字段并且message.content里有内容说明模型侧完全没问题。如果这里就报401那是 Key 的问题报model not found那是 Model ID 的问题。先把这一步跑通再去动 OpenClaw排障范围会小很多。3. 可复制配置openclaw.json 里的模型接入片段OpenClaw 装好之后主配置文件在~/.openclaw/openclaw.json工作区默认在~/.openclaw/workspace。如果你跑过openclaw onboard这个文件已经生成了里面有一些默认字段。我们要做的是把模型这一段改对。先确认安装。Node.js 需要 22 或更高版本可以用node -v检查。安装方式选一种即可# 官方脚本macOS / Linux curl -fsSL https://openclaw.ai/install.sh | bash # npm 方式 npm install -g openclaw-cnlatest # 安装后跑一次向导 openclaw-cn onboard --install-daemon向导会问你一些基础问题模型那一步可以先跳过或随便选因为我们要手动改配置。向导跑完后用编辑器打开配置文件openclaw configure # 或者直接编辑 vim ~/.openclaw/openclaw.json下面是一段可以直接参考的模型配置片段。核心是把 provider 指向 OpenAI 兼容接口Base URL 填 TaoToken 的地址apiKey 填你的 Keymodel 填你的 Model ID{ models: { default: taotoken-main, providers: { taotoken-main: { type: openai, baseUrl: https://taotoken.net/api, apiKey: 你的API_KEY, model: 你的Model_ID, maxTokens: 2048, temperature: 0.7 } } }, agents: { main: { workspace: ~/.openclaw/workspace, model: taotoken-main, maxConcurrency: 5, timeout: 30000 } } }几个字段说明一下。type填openai表示走 OpenAI 兼容协议TaoToken 的接口就是这个协议所以不用改。baseUrl是接口根地址填https://taotoken.net/api不要在后面加/chat/completions客户端会自己拼。apiKey就是你在控制台创建的那串 Key。model是 Model ID必须和模型列表里完全一致。maxTokens控制单次回复长度新手先给 2048 够用。temperature是随机性0.7 比较均衡。agents.main.model这一项要指向上面定义的 provider 名字taotoken-main这样主代理才知道用哪个模型。如果你后面配了多个 provider可以在这里切换。提示如果你不想把 Key 明文写在 JSON 里可以改成读环境变量。OpenClaw 支持在配置里用${ENV_NAME}的形式引用先在 shell 里export TAOTOKEN_KEY你的Key然后配置里写apiKey: ${TAOTOKEN_KEY}。改完配置后重启网关让配置生效openclaw gateway restart如果你是用 Docker 跑的配置文件的挂载路径要对应上重启容器即可docker restart openclaw这一步做完配置层面就齐了。但配置写对不等于链路通下一节我们用实际请求验证。4. 验证请求从网关启动到收到第一条回复配置改完接下来是逐条验证。我习惯把验证拆成三层网关是否活着、模型接口是否可达、完整对话是否闭环。任何一层出问题都能快速定位。第一层确认网关在跑。启动网关并查看状态openclaw gateway start openclaw gateway status状态里应该显示 running端口默认是 18789。你也可以打开控制面板确认openclaw dashboard然后浏览器访问http://localhost:18789/能看到面板就说明网关正常。如果端口被占用日志里会有提示换个端口或关掉占用程序。第二层确认模型接口可达。OpenClaw 提供了一个测试模型连通性的方式可以直接发一条测试消息openclaw models test taotoken-main这个命令会用你配置里的 provider 发一条最小请求。如果返回成功并带内容说明 Base URL、Key、Model ID 三者都对。如果报错看错误类型401是 Key 无效或没带上404通常是 Base URL 拼错model not found是 Model ID 不对。第三层完整对话闭环。启动一个交互式会话直接和助手对话openclaw chat进入交互界面后输入一句话比如“帮我列三个今天要做的事”。如果几秒内收到模型回复并且内容合理那么从本地 OpenClaw 到模型接口的完整链路就通了。这是最关键的一步它验证的不只是接口还有代理路由、会话管理、消息拼装这些环节。如果你配了聊天渠道比如 Telegram 或飞书也可以从那边发消息验证。渠道消息会经过网关路由到主代理再走模型。渠道侧能收到回复说明整条链路包括渠道适配都正常。实测下来第一次跑通后建议把这条成功记录保存下来用的哪个 Model ID、Base URL 是什么、配置里哪些字段。后面换模型或排障时这份记录能帮你快速对比。注意如果openclaw chat卡住不返回先看日志openclaw logs follow实时输出里通常能看到请求发出去了但没回来或者回来了但解析失败。解析失败常见于返回格式和预期不符这时候要确认 provider 类型是不是openai。到这里一个能完成问答闭环的本地 AI 助手就跑起来了。接下来是排障把新手最常撞到的几个错误集中讲清楚。5. 常见报错排查401、local proxy failed、reading choices、OAuth新手配 OpenClaw 模型时报错集中在几个类型。我把真实遇到过的错误和对应处理列出来你对照日志里的关键字定位。401 Unauthorized。这是最常见的一个。含义是请求带上的凭据没通过校验。可能原因有三个Key 复制时漏了字符或带了空格配置里apiKey字段没被正确读取比如引用了不存在的环境变量Key 本身被禁用或过期。处理方式先用第 2 节的 curl 命令单独测 Key确认 Key 有效再检查配置文件里apiKey的值如果是环境变量引用确认 shell 里已经 export 且重启过网关。local proxy failed或类似连接失败。这个通常出现在 Base URL 填错、网络不通、或者本地有拦截的情况下。先确认baseUrl是https://taotoken.net/api没有多余路径。再用curl -v https://taotoken.net/api看能不能建立连接。如果连接超时检查本机网络和 DNS。注意不要在任何配置里引入来路不明的转发设置保持直连即可。reading choices或cannot read property choices。这个错误说明请求发出去了、也回来了但返回的 JSON 结构里没有choices字段客户端解析失败。常见原因是 provider 类型配错比如把 OpenAI 兼容接口配成了别的类型导致解析逻辑不匹配。处理方式确认type是openai用 curl 看原始返回确认返回体里确实有choices数组。如果返回的是错误信息比如额度不足、模型不存在也会没有choices这时候要看返回体里的error字段。OAuth相关报错。如果你在配置里选了需要 OAuth 授权的 provider但没完成授权流程就会报这个。对新手来说最省事的是用 API Key 方式的 provider避开 OAuth。如果你确实要用 OAuth 类型的服务按对应文档完成授权把 token 存到凭据目录。OpenClaw 的凭据目录是~/.openclaw/credentials/权限建议设为仅当前用户可读。还有一个容易忽略的model not found。这个不是网络问题是 Model ID 字符串不匹配。模型标识通常区分大小写也可能带版本号或连字符。处理方式回到模型列表复制准确的 Model ID粘贴进配置不要手打。排查时善用日志。openclaw logs follow会实时输出请求和响应都能看到。看到请求发出但响应异常重点看响应体看到请求根本没发出重点看配置加载和 provider 初始化。提示改完配置一定要重启网关openclaw gateway restart。很多人改完配置直接测结果用的还是旧配置白折腾半天。把这几类错误过一遍基本能覆盖新手 90% 的卡点。剩下的多半是环境问题比如 Node 版本太低、端口冲突、权限不足日志里都会有明确提示。6. 把链路固定下来长期编码与 Agent 场景的下一步一次问答闭环跑通后你可以把这个环境固定下来作为日常用的本地助手。如果你打算长期用它做编码辅助或跑 Agent 任务有几个方向可以继续。一是把模型配置稳定住。确认好用的 Model ID 和参数后不要再频繁改。如果要用多个模型可以在providers里配多个然后在agents里按用途切换。比如一个模型负责日常对话一个负责代码生成。二是把工作区管好。~/.openclaw/workspace是助手的工作目录长期记忆、任务文件都放这里。定期备份这个目录和~/.openclaw/openclaw.json换机器时直接迁移。三是按需接入聊天渠道。OpenClaw 支持多种渠道配好之后出门也能通过手机发指令。渠道配置和配对审批在openclaw channels和openclaw pairing下完成配对码要妥善保管。如果你要把这套环境用于长期编码或 Agent 类任务可以了解下 Coding Plan 这类方案地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content它面向的就是持续调用模型的开发场景。日常验证模型是否可用用模型对话页面就够了https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。需要管理 Key 和查看用量去控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。接入过程中遇到配置细节可以对照接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。最后给一个实用建议把第 2 节那条 curl 验证命令存成一个脚本每次换 Key 或换模型先跑一遍。模型侧通了再去动 OpenClaw 配置排障会轻松很多。本地 AI 助手这件事跑通第一条消息之后剩下的都是在这个闭环上做加法。