OpenClaw 装完之后卡在模型接入这一步是很多人第一次跑这个项目时最容易停住的地方。它本身是个本地网关型 Agent 框架装好只是把壳子搭起来真正让它能对话、能调工具、能跑任务还得把模型通道接上。默认向导里推荐的模型对国内网络环境不算友好配置项又散落在 settings 文件里改错一个字段就是 401 或者一直转圈。这篇就聚焦「安装完成之后」这一段settings 里 Base URL 和 API Key 到底怎么改改完怎么用一次真实请求验证连通性以及报错时先看哪里。目标很明确让你从装完到能对话一次闭环不用来回翻文档。1. OpenClaw 装完却连不上模型的真实场景与排查思路先说清楚 OpenClaw 是什么、能做什么、适合谁。它是一个跑在本地的 Agent 网关对外暴露一个 18789 端口的仪表盘对内通过 OpenAI 兼容协议去调用各家大模型。你可以把它理解成一个「本地中转站」你的对话请求先到 OpenClaw它再按 settings 里配的地址转发给模型服务把结果拿回来。适合想在自己机器上跑 Agent、又不想把密钥和上下文散落在各个客户端里的人。问题就出在这个「转发」上。OpenClaw 默认走的是官方推荐的模型通道向导里让你填 API Key但很多人填完发现openclaw health里 AI Model 那一栏一直是 Disconnected。原因通常有三类一是 Base URL 没改还指向默认地址二是 Key 填了但格式不对比如多了空格或者少了前缀三是 settings 文件的位置找错了改了一个不生效的副本。我试过在一台 Ubuntu 上装完向导走完显示成功结果发消息一直转圈。后来openclaw gateway status看到网关是 Running但openclaw health里模型连接是红的。翻日志才发现请求打到了默认地址超时了。把 Base URL 换成国内可直连的兼容地址之后立刻就通了。所以排查顺序建议是这样先确认网关本身活着openclaw gateway status再看模型连接状态openclaw health最后去 settings 里核对 Base URL、API Key、Model ID 这三个字段。这三个字段是绑在一起的缺一个或者错一个都连不上。下面第二节先把 TaoToken 这边的准备工作做完再进配置文件。2. TaoToken 前置准备拿到 Base URL 与 API Key 的完整步骤在改 OpenClaw 的 settings 之前你得先有一个可用的模型通道。这里用 TaoToken 来做它提供 OpenAI 兼容接口正好对上 OpenClaw 的调用方式。整个准备过程就两件事注册拿 Key记下 Base URL。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 完成账号注册。这一步不复杂按页面提示走就行。第二步进控制台创建 API Key。地址是 https://taotoken.net/console 登录后在 API Keys 页面点新建复制出来的那串就是你的密钥。注意这个 Key 只在创建时完整显示一次关掉页面就看不全了所以复制完先存到安全的地方。第三步记下 Base URL。TaoToken 的接口地址是 https://taotoken.net/api 这个要填到 OpenClaw 的 settings 里。注意结尾不要多加斜杠也不要自己拼/v1OpenClaw 会按 OpenAI 兼容规范去拼路径多写反而会 404。第四步确认你要用的 Model ID。TaoToken 支持多种模型具体可用的模型名在文档里能查到地址是 https://taotoken.net/doc 。选一个你常用的比如做代码任务就挑代码能力强的做长文本就挑上下文大的。这个 Model ID 后面要原样填进 settings大小写和连字符都不能错。到这里你手上有三样东西Base URLhttps://taotoken.net/api、API Key控制台复制的那串、Model ID文档里选的。这三样就是下一节配置文件的全部输入。如果你还没拿到 Key先去 https://taotoken.net/api-keys 创建再回来继续。提示API Key 属于敏感信息不要提交到 Git 仓库也不要在截图里露出完整串。本地配置文件建议加上文件权限限制。3. 可复制配置把 settings 改到 TaoToken 的完整片段OpenClaw 的配置入口在 settings 文件里。不同安装方式路径略有差异常见的是用户目录下的~/.openclaw/settings.json如果你是用openclaw onboard走完向导的它一般会生成在这个位置。先确认文件存在ls -la ~/.openclaw/settings.json如果不存在可以手动创建目录和文件mkdir -p ~/.openclaw touch ~/.openclaw/settings.json然后编辑这个文件。下面是一份可直接复制的 JSON 片段把三个占位值换成你自己的{ gateway: { port: 18789, host: 127.0.0.1 }, model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, modelId: 你的ModelID, timeout: 60000 }, logging: { level: info } }几个字段说明一下。provider填openai-compatible因为 TaoToken 走的是 OpenAI 兼容协议。baseUrl就是上一步记下的 https://taotoken.net/api 注意这里不要带尾斜杠。apiKey填控制台复制的那串原样粘贴前后不要有空格。modelId填文档里选的模型名。timeout给 60 秒Agent 任务有时候响应慢太短会误判超时。如果你更习惯用 TOML 格式OpenClaw 也支持~/.openclaw/settings.toml等价写法是这样[gateway] port 18789 host 127.0.0.1 [model] provider openai-compatible baseUrl https://taotoken.net/api apiKey sk-你的TaoToken密钥 modelId 你的ModelID timeout 60000 [logging] level info两种格式选一种就行不要同时存在否则 OpenClaw 读取优先级可能让你改的那份不生效。改完保存然后重启网关让配置加载openclaw gateway restart openclaw gateway status看到状态是 Running 就说明配置被读进去了。如果重启报错先检查 JSON 有没有语法问题比如多了一个逗号或者少了引号可以用python3 -m json.tool ~/.openclaw/settings.json验证一下格式。注意如果你之前用向导配过别的模型settings 里可能已经有model段直接覆盖对应字段即可不要重复写两个model键JSON 里重复键会以后一个为准容易让人误判。4. 验证请求发一次真实对话确认连通性配置改完不能只看状态灯得发一次真实请求才算数。OpenClaw 提供了命令行方式直接测模型通道最直接的是用openclaw chat发一句话openclaw chat 用一句话说明什么是本地 Agent 网关如果配置正确你会看到模型返回的内容类似「本地 Agent 网关是运行在本机、负责转发模型请求并管理工具调用的中间层」。这就说明 Base URL、API Key、Model ID 三个字段都对上了请求成功打到了 TaoToken 并拿回了结果。想更细一点看请求过程可以加上调试参数openclaw chat --debug 你好确认一下连通性--debug会打印出实际请求的 URL、用的模型名、返回状态码。正常情况你能看到请求地址是https://taotoken.net/api/...状态码 200。如果状态码是 401说明 Key 有问题如果是 404多半是 Base URL 拼错了如果是超时检查网络或者把timeout调大。除了命令行也可以走仪表盘验证。浏览器打开 http://127.0.0.1:18789/ 在对话界面里输入一句话发送。能收到回复就说明整条链路是通的。仪表盘的好处是能直观看到会话历史方便你确认多轮对话是否正常。再补一个健康检查命令它会一次性报告网关和模型的状态openclaw health成功时你会看到 Gateway 是 RunningAI Model 是 Connected。这两个都绿了基本就可以放心用了。如果 AI Model 还是 Disconnected回到第三节核对 settings重点看baseUrl和apiKey这两个字段九成的连接问题都出在这里。5. 本篇常见报错排查401、local proxy failed 与 reading choices配置过程中最容易撞上的几个报错这里逐个对照说清楚。401 Unauthorized。这是最常见的意思是 Key 没通过校验。先检查apiKey字段有没有多余空格复制的时候很容易带上首尾空白。再确认 Key 是不是已经失效或者被删了去 https://taotoken.net/api-keys 看一眼状态。还有一种情况是 Key 填对了但baseUrl指向了错误的地址请求打到了别处自然认不出你的 Key。local proxy failed。这个报错通常出现在网关启动阶段意思是本地代理层没起来。先看openclaw gateway status如果网关本身没 Running重启一下openclaw gateway restart。如果重启还失败检查 18789 端口是不是被占用了lsof -i :18789有别的进程占着就换端口改 settings 里的gateway.port然后重启。另外 WSL2 环境下如果从 Windows 主机访问仪表盘失败也会看到类似代理不通的提示那是网络转发问题不是配置问题按端口转发处理即可。reading choices 相关报错。这类错误一般长这样cannot read property choices of undefined意思是返回体里没有choices字段OpenClaw 按 OpenAI 格式去取结果时取空了。原因通常是 Base URL 少写或多写了路径比如你填了https://taotoken.net/api/v1OpenClaw 又拼了一次/v1路径就重复了。正确做法是 Base URL 只填到 https://taotoken.net/api 路径交给 OpenClaw 自己拼。改完重启网关再测。OAuth 相关报错。如果你看到 OAuth 字样说明配置里混进了需要 OAuth 授权的 provider 设置。OpenClaw 用 API Key 方式接入时不需要 OAuth检查 settings 里provider是不是写成了别的值改回openai-compatible即可。模型名不识别。报错里出现model not found之类说明modelId填的模型名不对。去 https://taotoken.net/doc 核对可用模型列表原样复制模型名注意大小写和连字符。排查的时候有个通用技巧加--debug跑一次把实际请求的 URL 和返回状态码打出来对照上面几种情况基本能定位到是哪个字段的问题。改完配置记得openclaw gateway restart不重启不生效。6. 从安装到可用的闭环与后续接入建议走到这里你应该已经完成了 OpenClaw 从安装到模型接入的完整闭环装好网关、拿到 TaoToken 的 Base URL 和 API Key、改好 settings、发了一次真实对话验证通过。这套流程跑通之后后面换模型或者加通道都是改 settings 里那三个字段的事不用重装。如果你还想在命令行里直接和模型对话可以走模型对话入口 https://taotoken.net/model-chat 快速验证某个模型是否可用。如果打算长期跑编码类 Agent 任务Coding Plan 会更合适地址是 https://taotoken.net/coding-plan 。接入过程中遇到配置问题接入文档 https://taotoken.net/doc 里有各字段的详细说明API Keys 管理在 https://taotoken.net/api-keys 。最后留一个实用习惯每次改完 settings先跑openclaw health看状态再发一句openclaw chat测真实请求两步都过再去做别的。这样能把配置问题和业务问题分开省掉很多来回猜的时间。 
长河君 · 2026/10/8 18:09:09 · 阅读 1.2k OpenClaw 安装指南：把 settings 改到 TaoToken 的完整配置流程
OpenClaw 装完之后卡在模型接入这一步是很多人第一次跑这个项目时最容易停住的地方。它本身是个本地网关型 Agent 框架装好只是把壳子搭起来真正让它能对话、能调工具、能跑任务还得把模型通道接上。默认向导里推荐的模型对国内网络环境不算友好配置项又散落在 settings 文件里改错一个字段就是 401 或者一直转圈。这篇就聚焦「安装完成之后」这一段settings 里 Base URL 和 API Key 到底怎么改改完怎么用一次真实请求验证连通性以及报错时先看哪里。目标很明确让你从装完到能对话一次闭环不用来回翻文档。1. OpenClaw 装完却连不上模型的真实场景与排查思路先说清楚 OpenClaw 是什么、能做什么、适合谁。它是一个跑在本地的 Agent 网关对外暴露一个 18789 端口的仪表盘对内通过 OpenAI 兼容协议去调用各家大模型。你可以把它理解成一个「本地中转站」你的对话请求先到 OpenClaw它再按 settings 里配的地址转发给模型服务把结果拿回来。适合想在自己机器上跑 Agent、又不想把密钥和上下文散落在各个客户端里的人。问题就出在这个「转发」上。OpenClaw 默认走的是官方推荐的模型通道向导里让你填 API Key但很多人填完发现openclaw health里 AI Model 那一栏一直是 Disconnected。原因通常有三类一是 Base URL 没改还指向默认地址二是 Key 填了但格式不对比如多了空格或者少了前缀三是 settings 文件的位置找错了改了一个不生效的副本。我试过在一台 Ubuntu 上装完向导走完显示成功结果发消息一直转圈。后来openclaw gateway status看到网关是 Running但openclaw health里模型连接是红的。翻日志才发现请求打到了默认地址超时了。把 Base URL 换成国内可直连的兼容地址之后立刻就通了。所以排查顺序建议是这样先确认网关本身活着openclaw gateway status再看模型连接状态openclaw health最后去 settings 里核对 Base URL、API Key、Model ID 这三个字段。这三个字段是绑在一起的缺一个或者错一个都连不上。下面第二节先把 TaoToken 这边的准备工作做完再进配置文件。2. TaoToken 前置准备拿到 Base URL 与 API Key 的完整步骤在改 OpenClaw 的 settings 之前你得先有一个可用的模型通道。这里用 TaoToken 来做它提供 OpenAI 兼容接口正好对上 OpenClaw 的调用方式。整个准备过程就两件事注册拿 Key记下 Base URL。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 完成账号注册。这一步不复杂按页面提示走就行。第二步进控制台创建 API Key。地址是 https://taotoken.net/console 登录后在 API Keys 页面点新建复制出来的那串就是你的密钥。注意这个 Key 只在创建时完整显示一次关掉页面就看不全了所以复制完先存到安全的地方。第三步记下 Base URL。TaoToken 的接口地址是 https://taotoken.net/api 这个要填到 OpenClaw 的 settings 里。注意结尾不要多加斜杠也不要自己拼/v1OpenClaw 会按 OpenAI 兼容规范去拼路径多写反而会 404。第四步确认你要用的 Model ID。TaoToken 支持多种模型具体可用的模型名在文档里能查到地址是 https://taotoken.net/doc 。选一个你常用的比如做代码任务就挑代码能力强的做长文本就挑上下文大的。这个 Model ID 后面要原样填进 settings大小写和连字符都不能错。到这里你手上有三样东西Base URLhttps://taotoken.net/api、API Key控制台复制的那串、Model ID文档里选的。这三样就是下一节配置文件的全部输入。如果你还没拿到 Key先去 https://taotoken.net/api-keys 创建再回来继续。提示API Key 属于敏感信息不要提交到 Git 仓库也不要在截图里露出完整串。本地配置文件建议加上文件权限限制。3. 可复制配置把 settings 改到 TaoToken 的完整片段OpenClaw 的配置入口在 settings 文件里。不同安装方式路径略有差异常见的是用户目录下的~/.openclaw/settings.json如果你是用openclaw onboard走完向导的它一般会生成在这个位置。先确认文件存在ls -la ~/.openclaw/settings.json如果不存在可以手动创建目录和文件mkdir -p ~/.openclaw touch ~/.openclaw/settings.json然后编辑这个文件。下面是一份可直接复制的 JSON 片段把三个占位值换成你自己的{ gateway: { port: 18789, host: 127.0.0.1 }, model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, modelId: 你的ModelID, timeout: 60000 }, logging: { level: info } }几个字段说明一下。provider填openai-compatible因为 TaoToken 走的是 OpenAI 兼容协议。baseUrl就是上一步记下的 https://taotoken.net/api 注意这里不要带尾斜杠。apiKey填控制台复制的那串原样粘贴前后不要有空格。modelId填文档里选的模型名。timeout给 60 秒Agent 任务有时候响应慢太短会误判超时。如果你更习惯用 TOML 格式OpenClaw 也支持~/.openclaw/settings.toml等价写法是这样[gateway] port 18789 host 127.0.0.1 [model] provider openai-compatible baseUrl https://taotoken.net/api apiKey sk-你的TaoToken密钥 modelId 你的ModelID timeout 60000 [logging] level info两种格式选一种就行不要同时存在否则 OpenClaw 读取优先级可能让你改的那份不生效。改完保存然后重启网关让配置加载openclaw gateway restart openclaw gateway status看到状态是 Running 就说明配置被读进去了。如果重启报错先检查 JSON 有没有语法问题比如多了一个逗号或者少了引号可以用python3 -m json.tool ~/.openclaw/settings.json验证一下格式。注意如果你之前用向导配过别的模型settings 里可能已经有model段直接覆盖对应字段即可不要重复写两个model键JSON 里重复键会以后一个为准容易让人误判。4. 验证请求发一次真实对话确认连通性配置改完不能只看状态灯得发一次真实请求才算数。OpenClaw 提供了命令行方式直接测模型通道最直接的是用openclaw chat发一句话openclaw chat 用一句话说明什么是本地 Agent 网关如果配置正确你会看到模型返回的内容类似「本地 Agent 网关是运行在本机、负责转发模型请求并管理工具调用的中间层」。这就说明 Base URL、API Key、Model ID 三个字段都对上了请求成功打到了 TaoToken 并拿回了结果。想更细一点看请求过程可以加上调试参数openclaw chat --debug 你好确认一下连通性--debug会打印出实际请求的 URL、用的模型名、返回状态码。正常情况你能看到请求地址是https://taotoken.net/api/...状态码 200。如果状态码是 401说明 Key 有问题如果是 404多半是 Base URL 拼错了如果是超时检查网络或者把timeout调大。除了命令行也可以走仪表盘验证。浏览器打开 http://127.0.0.1:18789/ 在对话界面里输入一句话发送。能收到回复就说明整条链路是通的。仪表盘的好处是能直观看到会话历史方便你确认多轮对话是否正常。再补一个健康检查命令它会一次性报告网关和模型的状态openclaw health成功时你会看到 Gateway 是 RunningAI Model 是 Connected。这两个都绿了基本就可以放心用了。如果 AI Model 还是 Disconnected回到第三节核对 settings重点看baseUrl和apiKey这两个字段九成的连接问题都出在这里。5. 本篇常见报错排查401、local proxy failed 与 reading choices配置过程中最容易撞上的几个报错这里逐个对照说清楚。401 Unauthorized。这是最常见的意思是 Key 没通过校验。先检查apiKey字段有没有多余空格复制的时候很容易带上首尾空白。再确认 Key 是不是已经失效或者被删了去 https://taotoken.net/api-keys 看一眼状态。还有一种情况是 Key 填对了但baseUrl指向了错误的地址请求打到了别处自然认不出你的 Key。local proxy failed。这个报错通常出现在网关启动阶段意思是本地代理层没起来。先看openclaw gateway status如果网关本身没 Running重启一下openclaw gateway restart。如果重启还失败检查 18789 端口是不是被占用了lsof -i :18789有别的进程占着就换端口改 settings 里的gateway.port然后重启。另外 WSL2 环境下如果从 Windows 主机访问仪表盘失败也会看到类似代理不通的提示那是网络转发问题不是配置问题按端口转发处理即可。reading choices 相关报错。这类错误一般长这样cannot read property choices of undefined意思是返回体里没有choices字段OpenClaw 按 OpenAI 格式去取结果时取空了。原因通常是 Base URL 少写或多写了路径比如你填了https://taotoken.net/api/v1OpenClaw 又拼了一次/v1路径就重复了。正确做法是 Base URL 只填到 https://taotoken.net/api 路径交给 OpenClaw 自己拼。改完重启网关再测。OAuth 相关报错。如果你看到 OAuth 字样说明配置里混进了需要 OAuth 授权的 provider 设置。OpenClaw 用 API Key 方式接入时不需要 OAuth检查 settings 里provider是不是写成了别的值改回openai-compatible即可。模型名不识别。报错里出现model not found之类说明modelId填的模型名不对。去 https://taotoken.net/doc 核对可用模型列表原样复制模型名注意大小写和连字符。排查的时候有个通用技巧加--debug跑一次把实际请求的 URL 和返回状态码打出来对照上面几种情况基本能定位到是哪个字段的问题。改完配置记得openclaw gateway restart不重启不生效。6. 从安装到可用的闭环与后续接入建议走到这里你应该已经完成了 OpenClaw 从安装到模型接入的完整闭环装好网关、拿到 TaoToken 的 Base URL 和 API Key、改好 settings、发了一次真实对话验证通过。这套流程跑通之后后面换模型或者加通道都是改 settings 里那三个字段的事不用重装。如果你还想在命令行里直接和模型对话可以走模型对话入口 https://taotoken.net/model-chat 快速验证某个模型是否可用。如果打算长期跑编码类 Agent 任务Coding Plan 会更合适地址是 https://taotoken.net/coding-plan 。接入过程中遇到配置问题接入文档 https://taotoken.net/doc 里有各字段的详细说明API Keys 管理在 https://taotoken.net/api-keys 。最后留一个实用习惯每次改完 settings先跑openclaw health看状态再发一句openclaw chat测真实请求两步都过再去做别的。这样能把配置问题和业务问题分开省掉很多来回猜的时间。