ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

OpenClaw系列---【OpenClaw接入三方白山智算平台:从Base URL到模型调用的完整配置】

OpenClaw系列---【OpenClaw接入三方白山智算平台:从Base URL到模型调用的完整配置】 1. OpenClaw 接入白山智算平台到底在解决什么问题OpenClaw 是一个本地优先的 Agent 运行框架它把模型调用、工具执行、会话管理都放在你自己的机器上跑。默认情况下它只认官方那几家的模型通道但真正干活的时候你往往想用更便宜、额度更足、或者特定能力更强的第三方模型服务。白山智算就是这类第三方平台里比较有代表性的一个它提供 OpenAI 兼容的 completions 接口模型覆盖 MiniMax、GLM、Kimi 这些国产主力对 OpenClaw 这种吃 token 很凶的 Agent 场景来说成本优势相当明显。问题在于OpenClaw 的配置不是改一个环境变量就完事。它有两层模型注册表一层在~/.openclaw/openclaw.json的models.providers里负责全局的 provider 定义另一层在~/.openclaw/agents/main/agent/models.json里负责具体 agent 能看到的模型清单。很多人只改了第一层结果启动后报model not found或者对话时提示reading choices解析失败就是因为第二层没同步。这篇就把这两处配置、Base URL、API Key、Model ID 三件套一次讲清楚再演示一次真实对话请求验证接入是否生效。适合谁看已经在本地跑 OpenClaw、想接第三方模型服务省钱的开发者手里有白山智算的 Key、但不确定 OpenClaw 配置格式的人以及想用一套统一通道管理多个平台凭据、不想每次切平台都改配置的人。下面所有路径和字段都按 OpenClaw 2026.3.8 版本的实际结构写你直接对照改就行。2. 接入前的准备Base URL、API Key 与模型清单怎么拿在动配置文件之前先把三样东西备齐Base URL、API Key、Model ID。白山智算的 OpenAI 兼容入口是https://api.edgefn.net/v1注意结尾的/v1不能少OpenClaw 的openai-completions适配器会在这个地址后面拼/chat/completions。API Key 在白山智算控制台的密钥管理页生成复制出来是一串sk-开头的字符串先存到记事本里等会儿要往两个 JSON 文件里各填一次。模型 ID 这块要特别小心。OpenClaw 配置里id字段必须和平台实际暴露的模型名完全一致大小写都不能错。白山智算当前常用的几个是MiniMax-M2.5、GLM-5、GLM-4.7、Kimi-K2-Instruct。其中Kimi-K2-Instruct的input要写成[text, image]因为它支持图片输入其余三个是纯文本写[text]就行。contextWindow和maxTokens也要按平台文档填填大了请求会被拒填小了浪费上下文。比如MiniMax-M2.5的上下文窗口是 196608最大输出 32768GLM-5和GLM-4.7都是 202752 上下文、16384 输出Kimi-K2-Instruct是 262144 上下文、32768 输出。如果你同时用多个第三方平台每个平台一套 Key、一套 Base URL管理起来很烦。我自己的做法是通过 TaoToken 统一 Key 和 API 通道来收口把各平台的凭据登记到 TaoToken 的 console 里OpenClaw 侧只认一个入口切换平台时改的是 TaoToken 的配置而不是 OpenClaw 的 JSON。这样 OpenClaw 的openclaw.json和models.json基本不用动减少来回改配置出错的机会。TaoToken 的 API 入口是https://taotoken.net/api控制台在https://taotoken.net/console密钥管理在https://taotoken.net/api-keys接入文档在https://taotoken.net/doc。这套组合不是必须的但如果你手上有三四个平台的 Key用它统一管理会省很多事。3. 可复制配置openclaw.json 与 models.json 两处同步改OpenClaw 的配置分两个文件必须都改缺一个就会出问题。第一个是主配置C:\Users\用户名\.openclaw\openclaw.jsonmacOS/Linux 是~/.openclaw/openclaw.json。打开它找到models.providers这一层把下面这段baishan整个粘进去。注意apiKey换成你自己的别直接抄。{ models: { mode: merge, providers: { baishan: { baseUrl: https://api.edgefn.net/v1, apiKey: sk-你的白山智算Key, api: openai-completions, models: [ { id: MiniMax-M2.5, name: MiniMax-M2.5, reasoning: false, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 196608, maxTokens: 32768 }, { id: GLM-5, name: GLM-5, reasoning: false, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 202752, maxTokens: 16384 }, { id: GLM-4.7, name: GLM-4.7, reasoning: false, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 202752, maxTokens: 16384 }, { id: Kimi-K2-Instruct, name: Kimi-K2-Instruct, reasoning: false, input: [text, image], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 262144, maxTokens: 32768 } ] } } } }接着改agents.defaults这一段。model.primary决定默认用哪个模型我一般设成baishan/GLM-4.7日常对话够用models里把四个模型都列上这样 agent 在会话中可以按需切换。注意这里的写法是provider/modelId斜杠不能省。{ agents: { defaults: { model: { primary: baishan/GLM-4.7 }, models: { baishan/MiniMax-M2.5: {}, baishan/GLM-5: {}, baishan/GLM-4.7: {}, baishan/Kimi-K2-Instruct: {} }, workspace: C:\\Users\\xxxx\\.openclaw\\workspace, compaction: { mode: safeguard }, maxConcurrent: 4, subagents: { maxConcurrent: 8 } } } }第二个文件是 agent 级模型注册表C:\Users\用户名\.openclaw\agents\main\agent\models.json。这个文件很多人会漏掉但它是 agent 实际读取模型清单的地方。把providers下的baishan整段复制进去结构和上面主配置里的 provider 定义基本一致只是每个模型多带一个api: openai-completions字段。{ providers: { baishan: { baseUrl: https://api.edgefn.net/v1, apiKey: sk-你的白山智算Key, api: openai-completions, models: [ { id: MiniMax-M2.5, name: MiniMax-M2.5, reasoning: false, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 196608, maxTokens: 32768, api: openai-completions }, { id: GLM-5, name: GLM-5, reasoning: false, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 202752, maxTokens: 16384, api: openai-completions }, { id: GLM-4.7, name: GLM-4.7, reasoning: false, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 202752, maxTokens: 16384, api: openai-completions }, { id: Kimi-K2-Instruct, name: Kimi-K2-Instruct, reasoning: false, input: [text, image], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 262144, maxTokens: 32768, api: openai-completions } ] } } }两个文件都改完后重启 OpenClaw 的 gateway 让配置生效。Windows 下在任务栏托盘右键退出再启动或者命令行openclaw gateway restart。重启后先别急着对话用openclaw models list看一眼模型清单里有没有出现baishan/开头的条目有就说明注册成功了。注意openclaw.json里如果原本已经有models.providers下的其他 provider粘贴时注意 JSON 逗号别把前一个 provider 的结尾逗号弄丢否则整个文件解析失败OpenClaw 会直接起不来。4. 验证请求一次对话确认接入是否生效配置改完最直接的验证方式就是发一次真实请求。OpenClaw 提供了命令行对话入口在终端里执行openclaw chat --model baishan/GLM-4.7 --message 用一句话说明你是什么模型如果接入正常你会看到类似这样的返回[baishan/GLM-4.7] 我是 GLM-4.7一个由智谱训练的大语言模型通过白山智算平台提供服务。返回里带上了 provider 前缀和模型名说明请求确实走了baishan这个 provider而不是回落到默认通道。这一步能过基本就说明 Base URL、API Key、Model ID 三件套都对上了。如果你想更底层地验证可以绕过 OpenClaw 直接用 curl 打白山智算的接口确认 Key 本身没问题curl https://api.edgefn.net/v1/chat/completions \ -H Authorization: Bearer sk-你的白山智算Key \ -H Content-Type: application/json \ -d { model: GLM-4.7, messages: [{role: user, content: ping}], max_tokens: 16 }正常返回是一个 JSONchoices[0].message.content里有内容。如果这一步就报 401那问题在 Key 或平台侧跟 OpenClaw 配置无关如果 curl 通了但 OpenClaw 不通那问题一定在 JSON 配置的字段上。再进一步验证多模型切换是否都可用。依次跑openclaw chat --model baishan/MiniMax-M2.5 --message test openclaw chat --model baishan/GLM-5 --message test openclaw chat --model baishan/Kimi-K2-Instruct --message test四个模型都能返回内容说明models.json里的注册清单和主配置完全同步了。如果某个模型报model not found回去检查那个模型的id拼写以及它有没有同时出现在两个文件的models数组里。如果你是用 TaoToken 统一通道的验证方式类似只是 Base URL 换成https://taotoken.net/apiKey 换成 TaoToken 的 Key模型 ID 用 TaoToken 侧登记的别名。这样 OpenClaw 配置里只保留一个 provider切换平台时改 TaoToken 的 console 就行不用再动本地 JSON。模型对话入口在https://taotoken.net/chat可以先用它确认通道本身是通的再回来配 OpenClaw。5. 常见报错排查401、local proxy failed、reading choices、OAuth接入过程里最容易撞上的几个报错我按实际遇到的频率排一下每个都给定位思路。401 Unauthorized。这个最直接Key 不对或者没带上。先确认openclaw.json和models.json两处的apiKey都填了而且填的是同一个 Key。常见坑是只改了主配置忘了改 agent 级配置结果 agent 读到的还是空 Key。另外检查 Key 有没有多余空格从控制台复制时容易带上换行。如果 Key 确认没问题还报 401去白山智算控制台看这个 Key 是不是被禁用或者额度用完了。local proxy failed。这个报错通常出现在 OpenClaw 的 gateway 层意思是本地代理转发请求失败。原因一般是baseUrl写错比如漏了/v1或者写成了https://api.edgefn.net没有路径。OpenClaw 的openai-completions适配器会在baseUrl后面拼/chat/completions所以baseUrl必须以/v1结尾。另一个可能是本机网络到api.edgefn.net不通先用 curl 测一下连通性。reading choices 解析失败。报错信息里带reading choices或者Cannot read properties of undefined (reading choices)说明请求发出去了但返回的 JSON 结构里没有choices字段。这通常是平台返回了错误对象而不是正常响应比如{error: {message: ...}}。把 OpenClaw 的日志级别调高看原始响应体是什么。常见原因是模型 ID 写错平台不认识这个模型名返回了错误或者maxTokens填得超过了平台上限被拒了。OAuth 相关报错。如果你在 OpenClaw 里同时配了需要 OAuth 的 provider比如某些官方通道可能会看到 OAuth token 刷新失败的提示。这个跟白山智算无关是另一个 provider 的问题。排查方法是先临时把那个 provider 从models.providers里注释掉确认白山智算单独能跑通再逐个加回来定位。模型列表为空。openclaw models list输出里没有baishan/条目说明models.json没被正确加载。检查文件路径是不是agents/main/agent/models.json注意main是你的 agent 名如果你建了别的 agent路径要对应改。另外确认 JSON 格式合法可以用python -m json.tool models.json校验一下。CC Switch / Cline MCP / Codex auth.json 场景。如果你是在这些工具里配 OpenClaw 的模型通道三件套要写全Base URL 填https://api.edgefn.net/v1Key 填白山智算的 KeyModel ID 填GLM-4.7这类具体模型名。CC Switch 里对应的是 provider 配置块Cline MCP 里对应的是 model provider 设置Codex 的auth.json里则是api_key和base_url两个字段。三处都别漏漏一个就连不上。提示改完配置后如果 OpenClaw 行为诡异先删掉~/.openclaw/agents/main/agent/下的缓存文件再重启有时候旧缓存会覆盖新配置。6. 多平台凭据统一管理用 TaoToken 收口 Key 与通道前面整套配置跑通后你可能会发现一个问题每接一个第三方平台就要在openclaw.json和models.json里各加一段 providerKey 散落在多个 JSON 文件里改起来容易漏。如果你手上同时有白山智算、还有其他平台的 Key管理成本会越来越高。我自己的做法是用 TaoToken 做统一入口。具体来说把各平台的 Key 登记到 TaoToken 的 consolehttps://taotoken.net/console在 API Keys 页面https://taotoken.net/api-keys生成一个 TaoToken 的 Key然后 OpenClaw 侧只配一个 providerBase URL 指向https://taotoken.net/apiKey 用 TaoToken 的。这样切换平台时改的是 TaoToken 侧的通道配置OpenClaw 的 JSON 完全不用动。模型 ID 用 TaoToken 侧登记的别名具体映射关系在接入文档https://taotoken.net/doc里有说明。对于长期跑编码任务或者 Agent 工作流的场景TaoToken 的 Coding Planhttps://taotoken.net/coding-plan可以按套餐方式管理调用额度比逐个平台充值省心。如果你只是临时验证某个模型用模型对话入口https://taotoken.net/chat先试一下确认通道通了再往 OpenClaw 里配。Claude Code 这类工具如果要接 Anthropic 兼容通道TaoToken 也有对应的接入方式具体在文档里查。需要说明的是TaoToken 在这里的角色是凭据和通道的统一管理层不是替代 OpenClaw 本身。OpenClaw 该跑的 Agent 逻辑、工具调用、会话管理都还在本地TaoToken 只负责把模型请求转发到正确的平台。这样分工的好处是你的 OpenClaw 配置保持稳定平台侧的变化在 TaoToken 里消化掉。最后给一个实操建议配置改完后把openclaw.json和models.json各备份一份命名带上日期。下次再改的时候先 diff 一下当前文件和备份确认只动了该动的地方。我踩过的坑就是手滑删了一个逗号结果整个 OpenClaw 起不来排查了半小时才发现是 JSON 语法问题。用python -m json.tool校验一遍再重启能省很多时间。
返回列表