OpenClaw Chutes 模型提供商插件接入指南：OAuth/API Key 认证、模型发现与默认配置详解

OpenClaw Chutes 模型提供商插件接入指南：OAuth/API Key 认证、模型发现与默认配置详解

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

本篇技术指南围绕 OpenClaw 官方外部插件包@openclaw/chutes-provider展开，完整讲解如何在 OpenClaw 中接入 Chutes（一个通过 OpenAI 兼容 API 开放开源模型目录的推理平台）：包括插件安装、OAuth 与 API Key 两条认证路径、基于GET /v1/models的动态模型发现机制、默认别名与内置启动目录、以及可落地的 JSON5 配置示例。读完本文，你将能够独立完成 Chutes 提供商在 OpenClaw 中的安装、认证与模型选择配置，并理解其底层实现行为。

插件概览与分发方式

Chutes 插件为 OpenClaw 增加chutes模型提供商支持，属于官方外部插件包，其插件参考文档位于 docs/plugins/reference/chutes.md，完整使用指南见 docs/providers/chutes.md。

从源码角度，插件入口位于 extensions/chutes/index.ts，它通过definePluginEntry注册了chutesprovider，并同时提供oauth与api-key两种认证方法（见 index.ts）。插件清单 extensions/chutes/openclaw.plugin.json 声明了providerEndpoints（端点类chutes-native，主机llm.chutes.ai）、modelPricing、providerAuthChoices（chutes与chutes-api-key两个认证选项）等元数据。需要注意的是，插件清单中activation.onStartup为false，但enabledByDefault为true，即默认启用但不要求在启动时主动加载，由使用场景按需触发。

安装插件

安装 Chutes 提供商插件并在网关中生效：

openclaw plugins install @openclaw/chutes-provider openclaw gateway restart

插件包版本信息可在 extensions/chutes/package.json 查看，其中openclaw.install.minHostVersion为>=2026.6.8，compat.pluginApi为>=2026.9.3，安装前请确认宿主 OpenClaw 版本满足这些下限要求。

认证接入：两条路径

无论选择哪条路径，完成 onboarding 后 OpenClaw 都会将默认模型设为chutes/zai-org/GLM-5.2-TEE，并注册 Chutes 模型目录。

方式一：OAuth 浏览器认证

执行以下命令启动 OAuth onboarding 流程：

openclaw onboard --auth-choice chutes

• 在本地环境，OpenClaw 会直接拉起浏览器完成登录；
• 在远程 / 无头 / VPS 环境，OpenClaw 会显示一个 URL，引导你在本地浏览器中打开登录，登录完成后把浏览器地址栏里的完整回调 URL（含code与state参数）粘贴回终端；
• OAuth 令牌会通过 OpenClaw 的 auth profiles 自动刷新，无需手动续期。

从实现细节看，OAuth 流程实现在 extensions/chutes/oauth.ts：采用 PKCE（code_challenge_method=S256）授权码模式，authorize 端点为https://api.chutes.ai/idp/authorize，token 端点为https://api.chutes.ai/idp/token，userinfo 端点为https://api.chutes.ai/idp/userinfo。本地回调监听默认端口为127.0.0.1:1456/oauth-callback，且parseRedirectUri强制要求回调 hostname 必须是 loopback（localhost/127.0.0.1/::1），否则直接报错（见 oauth.ts）。回调未在超时时间内（默认 3 分钟）被检测到时，会自动降级为“粘贴回调 URL”的手动模式。

方式二：API Key 认证

先在 chutes.ai/app/settings/api-keys 创建 API Key，然后执行：

openclaw onboard --auth-choice chutes-api-key

onboarding 向导会提示输入 API Key，也可以直接通过命令行参数传入：--chutes-api-key <key>（对应配置项optionKey: "chutesApiKey"）。API Key 认证方法由createProviderApiKeyAuthMethod工厂创建（见 index.ts），底层读取环境变量CHUTES_API_KEY。

方式三：直接注入 OAuth 令牌（CI 场景）

CHUTES_OAUTH_TOKEN环境变量用于直接提供已获取的 OAuth access token，从而跳过上述交互式浏览器流程，适合 CI 等自动化场景。注意它是“跳过交互”的令牌注入通道，与CHUTES_API_KEY是两个独立的运行时环境变量。

模型发现行为（Discovery Behavior）

当 Chutes 认证可用时，OpenClaw 会携带该凭证调用GET /v1/models（即https://llm.chutes.ai/v1/models），并使用发现到的模型列表。底层实现在 extensions/chutes/models.ts 的discoverChutesModels：

• 缓存：每个凭证的发现结果缓存 5 分钟（CACHE_TTL = 5 * 60 * 1000，见 models.ts），超时 10 秒；
• 严格模式：发现过程使用discoveryMode: "strict"，携带Authorization: Bearer <token>请求头；
• 失败语义：凭证被拒绝时产生目录认证失败（catalog authentication failure），OpenClaw不会匿名重试；其他请求失败则产生“目录不可用”结果，而非回退到静态成功列表；成功但返回空列表则保持为空；
• 统一路径：API Key 与 OAuth 发现共用同一条路径；
• SSRF 防护：请求经fetchWithSsrFGuard包裹，并依据CHUTES_BASE_URL的主机名生成 SSRF 策略白名单（见 models.ts）。

价格来源与语义

Token 价格来自 Chutes 原生模型目录（https://llm.chutes.ai/v1/models）。其数值型prompt、completion、input_cache_read字段已是每百万 token 的美元单价，并非 OpenRouter 那种“每 token 字符串”格式。归一化逻辑见 extensions/chutes/pricing-api.ts：prompt → input、completion → output、input_cache_read → cacheRead，cacheWrite固定为 0；任一必需字段缺失或非法时返回undefined（即不认定为免费，而是视为价格元数据不可用）。价格元数据不可用或无效，不意味着该模型是免费的。

与 models.mode 的交互

• 默认models.mode: "merge"下，新 onboarding 只记录 provider 与别名，不把生成的模型行或价格复制进你的配置，这样线上价格刷新不会覆盖你显式编写的模型成本；
• models.mode: "replace"下禁用发现，onboarding 会把内置目录作为显式离线种子保留在该模式下；
• 重复应用 provider setup 时，已配置的模型行及其价格会被保留。

默认别名（Default aliases）

OpenClaw 为 Chutes 目录注册了两个便捷别名：

别名注册逻辑见 extensions/chutes/onboard.ts 的applyChutesProviderConfig：除了上述两个具名别名，还会为目录内每个模型注册chutes/<model-id>形式的全量引用。此外，applyChutesConfig还会设置默认文本模型（primarychutes/zai-org/GLM-5.2-TEE，fallback 为 DeepSeek-V3.2-TEE 与 Kimi-K2.6-TEE）和默认图像模型（primarychutes/moonshotai/Kimi-K2.6-TEE，fallbackchutes/Qwen/Qwen3.6-27B-TEE），见 onboard.ts。

内置启动目录（Bundled starter catalog）

插件自带一份兜底回退目录（内置在 extensions/chutes/openclaw.plugin.json 的modelCatalog中），包含以下当前启动模型，以及两个仍可选用、但已从选择器隐藏的上一代兼容模型引用：

查看完整列表：

openclaw models list --all --provider chutes

几点补充说明：

• 内置启动模型的兜底价格按原生端点2026 年 8 月 31 日响应刷新过；某个模型在该端点不再出现时，会保留其此前的种子快照——feed 缺席本身不会下架已发布的引用，也不会改变其选择器状态；
• 列表中存在某个模型，不代表你的账号一定可以调用它；
• 内置目录中各模型的上下文窗口与价格见 openclaw.plugin.json（例如 GLM-5.2-TEE 上下文 1,048,576，DeepSeek-V3.2-TEE 上下文 131,072，Kimi-K2.6-TEE 上下文 262,144 且支持图文输入）。

配置示例

以下 JSON5 片段演示了如何把 Chutes 模型设为默认，并为常用模型配置显示别名：

{ agents: { defaults: { model: { primary: "chutes/zai-org/GLM-5.2-TEE" }, models: { "chutes/zai-org/GLM-5.2-TEE": { alias: "Chutes GLM 5.2" }, "chutes/deepseek-ai/DeepSeek-V3.2-TEE": { alias: "Chutes DeepSeek V3.2" }, }, }, }, }

models段为每个模型引用注册可选别名，model.primary指定默认主模型。更完整的配置模式可参考 docs/concepts/model-providers.md（provider 规则、模型引用与故障转移行为）以及 docs/gateway/configuration-reference.md（完整配置 schema）。

OAuth 覆盖环境变量

如需定制 OAuth 流程，可通过以下可选环境变量覆盖默认行为：

对应的代码逻辑位于 extensions/chutes/index.ts：CHUTES_OAUTH_SCOPES按空白拆分后逐个过滤空串再传入loginChutes。回调 URI 的 loopback 约束、OAuth app 的 redirect-app 要求请参照 Chutes 官方“Sign in with Chutes”文档进行配置。当 OAuth 失败时，向导会提示核对CHUTES_CLIENT_ID/CHUTES_CLIENT_SECRET以及回调 URI 是否包含http://127.0.0.1:1456/oauth-callback（见 index.ts）。

使用注意事项

• 模型引用格式：Chutes 模型统一注册为chutes/<model-id>形式，例如chutes/deepseek-ai/DeepSeek-V3.2-TEE；
• 流式使用统计：Chutes 在流式传输过程中不报告 token 用量（supportsUsageInStreaming: false），该标记由decorateChutesModelDefinition统一附加到所有目录模型（见 models.ts）；用量合计会在流结束后展示；
• 令牌刷新：OAuth 令牌通过 auth profiles 自动刷新；若刷新失败或访问被撤销，需重新执行登录。刷新逻辑见refreshChutesOAuthCredential（oauth.ts），它使用grant_type=refresh_token调用 token 端点，且按 RFC 6749 第 6 节允许不轮换 refresh token；
• 令牌过期缓冲：令牌有效期解析带 5 分钟缓冲、至少保留 30 秒剩余时长（见 oauth.ts）。

源码结构速览

若希望深入源码，可按以下路径继续探索：

以上便是 OpenClaw 接入 Chutes 提供商的完整路径：安装插件 → 选择 OAuth 或 API Key 完成认证 → 理解模型发现与价格语义 → 用别名与配置示例落地到实际 agent 中。核心参考文档为 docs/plugins/reference/chutes.md 与 docs/providers/chutes.md，源码佐证集中在 extensions/chutes 目录。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw