企业官网建设流程全解析

OpenClaw Fireworks 插件：接入 Fireworks 模型提供商的完整实践

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

本文以 OpenClaw 仓库中的 Fireworks 插件参考文档 为主体，结合 Fireworks 提供商文档 与插件源码，完整讲解@openclaw/fireworks-provider插件的分发方式、安装配置步骤、内置模型目录、模型 id 解析规则与 Kimi thinking 强制关闭机制。读完后你可以独立完成 Fireworks 提供商的接入、定制模型 id、排查凭证问题，并理解该插件在 OpenClaw 内部的实现原理。

插件概览与分发方式

Fireworks（fireworks.ai）通过 OpenAI 兼容 API 提供开源权重模型与路由（router）模型。OpenClaw 通过独立的官方提供商插件接入它，插件的官方定位是：

Adds Fireworks model provider support to OpenClaw.（为 OpenClaw 增加 Fireworks 模型提供商支持）

按照插件参考文档（docs/plugins/reference/fireworks.md）的定义，其分发与表面（Surface）信息为：

需要注意的一点：参考文档头部标注了<!-- Generated file. Do not edit by hand. -->，说明该参考页由pnpm plugins:inventory:gen从插件清单自动生成，人工内容只允许写在openclaw-plugin-reference:manual-start与openclaw-plugin-reference:manual-end标记之间。因此插件能力的“事实源头”是插件目录下的清单文件 openclaw.plugin.json，而参考文档是其自动投影。

插件入口 index.ts 使用defineSingleProviderPluginEntry注册了一个单提供商插件，关键注册字段包括：

• id: "fireworks"，别名aliases: ["fireworks-ai"]；
• catalog: { discoveryMode: "strict", allowExplicitBaseUrl: true, liveModelDiscovery: true }，即模型目录为严格发现模式、允许显式指定 Base URL、并支持运行时模型发现；
• wrapStreamFn: wrapFireworksProviderStream与resolveThinkingProfile，分别负责请求载荷改写与 thinking 策略（后文展开）；
• resolveDynamicModel：运行时接受任意 Fireworks 模型/路由 id 的动态解析钩子。

快速开始：安装、认证与验证

Fireworks 的认证凭据统一使用环境变量FIREWORKS_API_KEY。这一点在插件清单中有双重声明：openclaw.plugin.json 中setup.providers声明了envVars: ["FIREWORKS_API_KEY"]，providerAuthChoices则定义了 onboarding 选项fireworks-api-key（对应 CLI flag--fireworks-api-key <key>）。

第一步：安装插件

openclaw plugins install @openclaw/fireworks-provider

第二步：设置 Fireworks API key

提供三种方式（引自 Fireworks 提供商文档）：

# 方式一：Onboarding 引导 openclaw onboard --auth-choice fireworks-api-key

# 方式二：直接命令行传参 openclaw onboard --non-interactive --accept-risk --skip-health \ --auth-choice fireworks-api-key \ --fireworks-api-key "$FIREWORKS_API_KEY"

# 方式三：仅环境变量 export FIREWORKS_API_KEY=fw-...

Onboarding 会把密钥写入fireworks提供商的 auth profiles，并将 Fire Pass 的 GLM 5.2 Fast 路由设为默认模型。这一行为在源码 onboard.ts 中可以完整对应：applyFireworksConfig通过createDefaultModelsPresetAppliers生成，写入primaryModelRef（即fireworks/accounts/fireworks/routers/glm-5p2-fast）、Base URL、API 类型，并注册别名{ modelRef: "fireworks/...", alias: "GLM 5.2 Fast" }。

第三步：验证模型可用

openclaw models list --provider fireworks

输出应包含GLM 5.2 Fast、Kimi K2.6、Kimi K2.6 Fast三个目录模型。若FIREWORKS_API_KEY未能解析，openclaw models status --json会把缺失的凭证报告在auth.unusableProfiles字段下。

非交互/CI 场景

对于脚本化或 CI 安装，官方给出的一键命令为：

openclaw onboard --non-interactive \ --mode local \ --auth-choice fireworks-api-key \ --fireworks-api-key "$FIREWORKS_API_KEY" \ --skip-health \ --accept-risk

内置模型目录（Built-in Catalog）

插件清单中内置了 3 个目录模型，其核心参数如下（数据来自 openclaw.plugin.json 的modelCatalog.providers.fireworks.models）：

补充两个清单里的细节：

• 提供商baseUrl为https://api.fireworks.ai/inference/v1，api为openai-completions（OpenAI 兼容），defaultModel为accounts/fireworks/routers/glm-5p2-fast；
• Kimi K2.6 Fast路由带有兼容项compat.unsupportedToolSchemaKeywords: ["not"]，即该路由的 tool schema 不支持 JSON Schema 的not关键字，OpenClaw 在为它构造工具定义时会规避这一关键字；
• discovery配置为"fireworks": "refreshable"，配合liveModelDiscovery: true，意味着目录可刷新、支持运行时发现新模型。

文档同时说明：Setup 只保存连接设置与别名，不会把生成的目录行复制进你的配置文件；若显式设置models.mode: "replace"，则保持目录播种（catalog seeding）启用、自定义模型行保持完整。这与 onboard.ts 中defaultModels: cfg.models?.mode === "replace" ? buildFireworksCatalogModels() : []的三元判断严格一致。

模型 id 前缀规则与动态解析

OpenClaw 约定：所有 Fireworks 模型 ref 都以fireworks/开头，后接 Fireworks 平台上的精确 id 或路由路径，例如：

• 路由模型：fireworks/accounts/fireworks/routers/kimi-k2p6-turbo
• 直接模型：fireworks/accounts/fireworks/models/<model-name>

发起 API 请求时，OpenClaw 会剥掉fireworks/前缀，把剩余路径作为 OpenAI 兼容请求的model字段发给 Fireworks 端点。这个前缀剥离逻辑在 provider-catalog.ts 中可以看到：FIREWORKS_DEFAULT_MODEL_ID = FIREWORKS_DEFAULT_MODEL_REF.slice("fireworks/".length)，目录模型 id 本身不带前缀，ref 由前缀 + id 组成。

任意模型 id 的运行时解析

OpenClaw 接受运行时传入的任意 Fireworks 模型或路由 id。动态解析入口是 index.ts 的resolveFireworksDynamicModel，其行为可以概括为：

1. 空 id 直接返回undefined；
2. 若 id 已在内置目录中（isFireworksCatalogModelId命中），返回undefined，交给目录条目本身处理；
3. 对未收录的 id，克隆默认模型（GLM 5.2 Fast 路由）作为模板，并按 id 特征打补丁：
   • 若 id 匹配 Kimi 模式（isFireworksKimiModelId），则reasoning: false；
   • 输入模态：GLM id 标记为["text"]（仅文本），其余动态 id 标记为["text", "image"]；
4. 模板克隆失败时兜底为normalizeModelCompat构造的兼容条目（openai-completions+ Fireworks Base URL + 目录默认上下文窗口/最大 token 数）。

其中 GLM 判定函数 isFireworksGlmModelId 取 id 最后一段，用/^glm[-_.]/正则匹配；Kimi 判定函数 isFireworksKimiModelId 用/^kimi-k2(?:p[56]|[.-][56])(?:[-_].+)?$/匹配kimi-k2p5/kimi-k2p6系列及其后缀变体（大小写不敏感）。

自定义模型配置

要为其他模型指定不同的能力（例如输入模态），在 OpenClaw 配置中显式声明自定义模型行即可：

{ agents: { defaults: { model: { primary: "fireworks/accounts/fireworks/models/<your-model-id>", }, }, }, }

Kimi 的 thinking 强制关闭机制

这是 Fireworks 插件最核心的实现细节：OpenClaw 把所有经 Fireworks 提供的 Kimi 模型固定为thinking: off。原因是 Fireworks 侧的 Kimi 没有独立的 reasoning 通道，若不在请求中显式禁用 thinking，思维链可能泄漏到可见的content流里。若要端到端使用 Kimi 推理输出，官方建议改走 Moonshot 提供商路由同一模型（见 Moonshot 文档 与 thinking modes）。

该机制由三层代码共同保证：

1. 请求载荷改写：stream.ts 的wrapFireworksProviderStream在 provider 为fireworks/fireworks-ai、API 为openai-completions且模型 id 命中 Kimi 模式时，用createPayloadPatchStreamWrapper包装流，注入：

   payload.thinking = { type: "disabled" }; delete payload.reasoning; delete payload.reasoning_effort; delete payload.reasoningEffort;

   即发送 Anthropic 风格的 thinking 关闭开关，并从载荷中剥离reasoning、reasoning_effort、reasoningEffort三个字段，防止任何一层配置把 thinking 重新打开。

2. Thinking 策略对齐：thinking-policy.ts 对 Kimi id 返回{ levels: [{ id: "off" }], defaultLevel: "off" }，非 Kimi id 返回undefined（走通用策略）。这保证手动/think切换和提供商策略表面都只呈现off一个档位，与运行时契约一致。

3. 目录层声明：清单中两个 Kimi 模型的reasoning均为false，与上述运行时行为一致。

对应的测试用例位于 stream.test.ts、index.test.ts 与 onboard.test.ts，覆盖了载荷改写、动态模型解析与 onboarding 写配置的边界行为，可作为行为契约的参考。

守护进程场景下的环境变量可见性

若 Gateway 以托管服务运行（launchd、systemd、Docker 或容器），Fireworks 密钥必须对该进程可见，而不仅仅是你的交互式 shell。文档给出的明确警告：

仅在交互式 shell 中export的密钥，不会传递到 launchd/systemd 守护进程（除非该环境被导入）。应将密钥写入~/.openclaw/.env，或通过env.shellEnv配置，使 gateway 进程可读。

OpenClaw 在加载配置时会自动加载~/.openclaw/.env，因此存放在那里的密钥可以在所有平台上被托管的 gateway 服务读到。轮换密钥后，需要重启 gateway（或重新执行openclaw doctor --fix）。

小结

回到参考文档给出的最小事实——包名@openclaw/fireworks-provider、ClawHub 安装路由clawhub:@openclaw/fireworks-provider、Surfacefireworks——它们在源码中的落点分别是 package.json、openclaw.plugin.json 的providers: ["fireworks"]与 index.ts 的PROVIDER_ID = "fireworks"。整个插件以“OpenAI 兼容 API + 严格目录 + 运行时动态发现”为骨架，用前缀剥离实现任意模型 id 的接入，用流包装与 thinking 策略双重保障 Kimi 的思维链不外泄，是 OpenClaw 提供商插件体系中一个典型的“清单即事实、钩子即行为”的实现样本。

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