fw-ai/fireconnect
GitHub: fw-ai/fireconnect
FireConnect 是一个 CLI 工具，用于一键将多种 AI 编程代理和 IDE 连接到 Fireworks AI 模型推理服务。
Stars: 31 | Forks: 7
# FireConnect
[](https://github.com/fw-ai/fireconnect/blob/main/LICENSE)
**一行命令安装：**
```
sh -c "$(curl -fsSL https://raw.githubusercontent.com/fw-ai/fireconnect/main/install.sh)"
```
或者直接使用 `bash`：
```
curl -fsSL https://raw.githubusercontent.com/fw-ai/fireconnect/main/install.sh | bash
```
**Windows：** 在 Git Bash 中运行安装。在 PowerShell 中，使用管道 `curl | bash`
会破坏脚本的换行符（你会看到 `set: pipefail\r: invalid option
name`）；请保持管道在 bash 内部执行：
```
bash -c "curl -fsSL https://raw.githubusercontent.com/fw-ai/fireconnect/main/install.sh | bash"
```
安装一次 `fireconnect` CLI，然后用它来管理 Claude Code、OpenCode、Codex、Pi、Cursor、VS Code 和 Deep Agents 的 Fireworks 路由。运行 `fireconnect help` 查看它的功能。
## 快速设置
在终端中运行以下命令：
```
curl -fsSL https://raw.githubusercontent.com/fw-ai/fireconnect/main/install.sh | bash
```
安装程序会安装 `fireconnect` CLI；它不会提示输入密钥。完成后，登录并启用某个 harness：
```
fireconnect login # guided sign-in (browser or paste a key)
fireconnect claude on # route Claude Code through Fireworks
```
Fire Pass 用户可以直接使用 `fpk_...` 密钥 —— FireConnect 会检测密钥类型并为 Fire Pass 使用正确的默认值（所有别名使用 `glm-fast-latest`）。
如果你更喜欢从 SSH 检出安装：
```
mkdir -p ~/.fireconnect && git clone git@github.com:fw-ai/fireconnect.git ~/.fireconnect && bash ~/.fireconnect/install.sh
```
安装程序会：
- 要求 Node.js 18+。如果缺失或版本过旧，在 macOS 上会使用 Homebrew 进行安装，在其他平台上会打印升级说明（nvm / nodejs.org / NodeSource）。
- 将 FireConnect CLI 源码克隆到 `~/.fireconnect/cli`，并为其唯一的一个运行时依赖（`cross-keychain`，用于安全的 API 密钥存储）运行 `npm install --omit=dev`。
- 将 `fireconnect` CLI 启动器安装到 `~/.local/bin` 并将其添加到你的 shell `PATH` 中。
它**不会**让你登录或写入任何 harness 设置 —— 完成后，请运行 `fireconnect login`，然后运行 `fireconnect on`（例如 `claude`、`opencode`、`codex`、`pi`、`cursor`、`vscode`、`deepagents`），然后完全重启该工具。
## 升级
要更新 FireConnect，请重新运行安装程序（不要使用 `fireconnect upgrade`）：
```
sh -c "$(curl -fsSL https://raw.githubusercontent.com/fw-ai/fireconnect/main/install.sh)"
```
如果 Claude Code 正通过 FireConnect 连接，安装程序会检测到它，在临时恢复你的原始设置之前会询问你，安装最新的 CLI，并提示你使用 `fireconnect claude on` 重新连接。你的其他 harness 设置和存储的 API 密钥将被保留。
默认模型（Claude Code）：
```
main -> glm-fast-latest
opus -> glm-fast-latest
fable -> glm-fast-latest
sonnet -> kimi-fast-latest
haiku -> deepseek-v4-flash
subagent -> deepseek-v4-flash
```
## 手动设置
在此处创建 Fireworks API 密钥：
```
https://app.fireworks.ai/settings/users/api-keys
```
然后在终端启用 Fireworks 路由：
```
fireconnect login # sign in (browser or paste); stores the key in the OS keychain
fireconnect claude on # writes an owner-only X-Fireworks-Api-Key header
```
完成后重启 Claude Code。
## 写入的内容
设置会写入这些 Claude Code 设置。Claude Code 通过
`X-Fireworks-Api-Key` 自定义标头（在 `ANTHROPIC_CUSTOM_HEADERS` 中）进行身份验证，而**不是**
`apiKeyHelper`：
```
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.fireworks.ai/inference",
"ANTHROPIC_MODEL": "glm-fast-latest[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-fast-latest[1m]",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "kimi-fast-latest",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
"ANTHROPIC_DEFAULT_FABLE_MODEL": "glm-fast-latest[1m]",
"CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-flash",
"ANTHROPIC_CUSTOM_HEADERS": "X-Fireworks-Api-Key: fw_..."
}
}
```
**为什么使用自定义标头（而不是 `apiKeyHelper`）？** 网关通过
`X-Fireworks-Api-Key` 进行身份验证，它会优先于用户的 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`（在 shell 环境或 `settings.json` 中）原本会发送的任何 `x-api-key` / `Authorization` —— 这样，一个多余的 Anthropic 密钥就不会破坏路由。代价是 Fireworks 密钥会以明文形式写入 `settings.json`（作为 `key export` 和其他 harness 的可信来源，它仍然存储在 OS 钥匙串中）。FireConnect 会逐字节备份你之前的设置，以便 `fireconnect claude off` 可以准确恢复它们，并预先批准 `~/.claude.json` 中多余的 `ANTHROPIC_API_KEY`，这样 Claude Code 在首次启动时就不会提示它。
在 harness 支持自定义标头的地方，FireConnect 还会添加注重隐私的请求归因：
```
X-Title:
HTTP-Referer: fireconnect/v
```
FireConnect 绝不会覆盖 `User-Agent`；harness 会发送其自身的原生名称和版本。`X-Title` 标识该 harness，而 `HTTP-Referer` 仅携带 FireConnect 规范化的版本标签。这些值不包含任何用户、账户、本地路径、仓库、prompt、会话或凭证数据。重新运行 `on` 仅刷新 FireConnect 管理的标头并保留不相关的自定义标头；`off` 会逐字节恢复连接前的配置。Cursor 和 Deep Agents 目前未暴露自定义请求标头接口，因此 FireConnect 在这些工具中省略了遥测。
当 Claude Code 通过 Fireworks 路由时，`fireconnect claude on` 还会将 `WebSearch` 和 `WebFetch` 添加到 `settings.json` 中的 `permissions.deny`。这些是网关无法运行的 Anthropic **服务器端**工具，否则它们会出错；你自己的 `permissions` 规则将被保留，并且在 `fireconnect claude off` 时会移除拒绝条目。如果你的账户有权使用 Fireworks 网络搜索，系统会安装一个 `fireworks-websearch` MCP 服务器作为可用的替代方案。
到处都接受短模型 ID。例如，`glm-fast-latest` 作为 `accounts/fireworks/routers/glm-fast-latest[1m]` 写入 Claude Code 设置中。
### Cursor IDE
Cursor 将其 AI 设置存储在 SQLite 数据库（`state.vscdb`）中，而不是 JSON 文件中，因此 Cursor harness 直接在其中写入：
- API 密钥 -> `cursorAuth/openAIKey`
- Base URL -> `openAIBaseUrl`（设置为 `https://api.fireworks.ai/inference/v1`，即 Cursor 兼容 OpenAI 的 endpoint）
- 自定义模型 -> `aiSettings.userAddedModels` + `aiSettings.modelOverrideEnabled`
- 每个模式的模型 -> `aiSettings.modelConfig[mode]`（例如 `composer`、`cmd-k`）
`cursor on --model ` 会注册该模型，并将 `modelConfig` 中**已存在**的所有模式设置为该模型（非破坏性操作 —— 它不会创建原本不存在的模式条目）。`status` 会报告当前活跃/默认的模型。
Cursor 会注册首选的最新/最新目录。Cursor 不支持 FireRouter。直接的 Fireworks 模型 ID 在选择器、所有权跟踪器和每个受管理的模式选择中均以短 slug 形式存储。旧版的规范 `accounts/fireworks/...` 条目仍然可读，并在下次执行 `on` 时进行迁移。
```
fireconnect cursor on --api-key fw_... # quit Cursor first; sets all existing modes
fireconnect cursor status # read-only; works while Cursor is open
fireconnect model list --search glm
fireconnect cursor on --model glm-fast-latest
fireconnect cursor off # restores your previous settings
```
**在执行 `on` 或 `off` 之前退出 Cursor（`Cmd-Q` / File > Quit）** —— 否则
Cursor 的内存状态会在下次刷新时覆盖写入的内容。在交互式
终端中，如果 Cursor 仍在运行，fireconnect 会要求你退出它并
**按 Enter 继续**；如果之后 Cursor 仍在运行，则会报错。`status` 和 `model list` 是只读的，随时可以使用。传递 `--force`
即可无需等待直接写入。`off` 仅移除 FireConnect 注册的模型；你自己的自定义模型会被保留。
**当 FireConnect 开启时，只有你的选择器中的 Fireworks 模型能正常工作** —— Cursor
订阅模型、Opus 模式和其他内置模型将无法响应。如需
模型访问或设置帮助，请联系 Fireworks 团队。运行
`fireconnect cursor off` 以恢复内置的 Cursor 模型。
### VS Code Chat
VS Code Chat 的自定义语言模型在 `chatLanguageModels.json`（一个由提供商组成的 JSON 数组）中进行配置。fireconnect 会添加一个 `Fireworks` 提供商（vendor 为 `customendpoint`，`apiType: responses` —— 即 OpenAI Responses API），其模型指向 `https://api.fireworks.ai/inference`（VS Code 会自动追加 `/v1/responses`）。Microsoft Foundry (Azure) 模式使用 `apiType: chat-completions`。FireRouter 只是同一提供商上的 `firerouter` 模型（`apiType: responses`）。
VS Code 会注册首选的最新/最新目录。Workspace-BYOK 账户也会自动接收 `firerouter`；否则运行 `vscode on --model firerouter`。直接的 Fireworks `models[].id` 值是简短的 slug；旧版的规范 ID 仍然可读，并在下次执行 `on` 时进行迁移。
API 密钥**不会**存储在 JSON 中 —— VS Code 通过其密钥存储解析 `${input:chat.lm.secret.}` 引用，将密钥作为 VS Code 应用作用域内的 `state.vscdb`（SQLite `ItemTable`，键为 `secret://`）中的 Electron `safeStorage` 加密 blob 保留。`fireconnect vscode on` 会同时写入两者：将提供商条目写入 `chatLanguageModels.json`，并将加密的密钥写入 `chat.lm.secret.fw-*` id 下的 `state.vscdb`。
```
fireconnect vscode on --api-key fw_... # quit VS Code first
fireconnect vscode status # read-only; works while VS Code is open
fireconnect model list --search glm
fireconnect vscode on --model deepseek-v4-flash
fireconnect vscode off # restores chatLanguageModels.json + removes the key
```
**在执行 `on` 或 `off` 之前退出 VS Code（`Cmd-Q` / File > Quit）** —— 如果 VS Code 仍在运行，fireconnect 会提示你退出并按 Enter（与 Cursor 相同）。传递 `--force` 即可无需等待直接写入。`status` 和 `model list` 是只读的，随时可以使用。
每个模型的 `toolCalling`/`vision`/`maxInputTokens`/`maxOutputTokens` 与 serverless 定价一起定义在 `packages/setup-cli/lib/fireworks/model-specs.mjs` 中（数据来源于 Fireworks 模型库和 API）。未映射的模型默认为 `toolCalling: true` 和 `vision: false`；在将模型添加到 specs 注册表之前，会省略 token 限制。VS Code 会将 `maxOutputTokens` 作为 `max_output_tokens` 发送，因此映射的值不得超过模型限制。
在 macOS 上，`safeStorage` 使用 VS Code 存储在登录钥匙串中的“ Safe Storage”（例如 `Visual Studio Code Safe Storage`）下的主密钥进行加密；打开一次 VS Code 就会创建它，因此第一次执行 `on` 时可能需要此操作。Insiders 版本会被自动检测（它会读取 `Code - Insiders Safe Storage` 并以 Insiders 的 `state.vscdb` 为目标）；也可以推断出指向 Insiders 用户数据目录内部的 `--vscode-path`。在 Windows 上，`safeStorage` 使用 AES-256-GCM，密钥由 DPAPI 保护并存储在 VS Code 的 `Local State` 文件中 —— 打开一次 VS Code 就会创建密钥。在 Linux 上，`safeStorage` 需要 `libsecret`（`secret-tool`）才能进行真正的加密 —— 如果没有它，Chromium 会回退到硬编码的密码（仅经过混淆，未加密），fireconnect 仍然会写入但会发出警告。`off` 会逐字节恢复你原来的 `chatLanguageModels.json`，并从 `state.vscdb` 中删除 `chat.lm.secret.fw-*` 密钥行；你手动配置的任何提供商都将被保留。
### FireRouter 模式
`fireconnect vscode on --model firerouter` 会在 Fireworks 提供商中注册 **`firerouter` 模型** —— 与其他所有模型一样，通过 **OpenAI Responses API** 在常规网关上提供服务。在 VS Code Chat 模型选择器中选择它即可。
```
fireconnect vscode on --model firerouter --api-key fw_... --anthropic-api-key sk-ant-...
fireconnect vscode status
fireconnect vscode off
```
Fireworks 密钥在 `state.vscdb`（提供商 `apiKey`）中保持**加密**状态 —— 没有明文。Anthropic BYOK 密钥是可选的；提供时，它会作为 `anthropic_api_key` 和 `requestHeaders["x-anthropic-api-key"]` 写入 `firerouter` 模型中。配置了 Workspace-BYOK 的账户以及具有有效 `ANTHROPIC_API_KEY` 的会话，会随首选别名一起接收 `firerouter`；否则请使用 `on --model firerouter`。
`fireconnect vscode off` 会逐字节恢复你的 `chatLanguageModels.json` 并移除该密钥。
## FireRouter（`firerouter` 模型）
FireRouter 是一个判别式模型路由器，它会对每个请求进行评分，并将简单的任务分配给更便宜的模型，同时将困难的任务直接传递下去 —— 它在常规的 Fireworks 网关（`https://api.fireworks.ai/inference`）上作为一个顶级的 **`firerouter` 模型**呈现。像选择任何其他模型一样选择它：
```
fireconnect claude on --model firerouter
fireconnect claude on --opus firerouter
fireconnect opencode on --model firerouter
fireconnect codex on --model firerouter
```
每个标准的 Fireworks 密钥（非 Fire Pass）均可使用 FireRouter，但只有在服务器端配置了工作区 BYOK（`enable-workspace-byok`），或者对于可以转发密钥的 harness 存在有效的 `sk-ant-...` `ANTHROPIC_API_KEY` 时，它才会自动包含在受支持的模型列表/选择器中。否则，请使用 `on --model firerouter` 显式选择它；Claude 使用诸如 `on --opus firerouter` 之类的位标志。Cursor 不支持 FireRouter。它绝不是默认模型。
**前沿模型的 BYOK。** FireRouter 使用你的 Anthropic 密钥将困难的请求路由到 Anthropic 前沿模型。如果你的工作区在服务器端配置了 BYOK（`enable-workspace-byok`），FireRouter 会自动使用它，因此选择 FireRouter 模型/槽位**无需额外的密钥**。否则，请在支持的地方传递 `--anthropic-api-key sk-ant-...`；如果没有它，FireRouter 仍会在 Fireworks 模型之间进行路由。在填充模型目录时，FireConnect 会首先检查本地是否存在有效的 Anthropic 密钥，然后再检查工作区标志。（不支持 OpenAI BYOK。）
**Claude Code。** `--model` 设置主要的 `ANTHROPIC_MODEL`；别名标志独立设置其对应的槽位。例如，`--opus firerouter` 仅更改 Opus，并将主要模型保留为推荐的 `glm-fast-latest`，而 `--model firerouter` 则显式将 FireRouter 设为主要模型。当多个别名都应使用它时，可以组合使用标志。Claude 通过 `X-Fireworks-Api-Key` 自定义标头使用 Fireworks 密钥进行身份验证。该标头会优先于用户的 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`（来自环境变量或 `~/.claude/settings.json`）原本会发送的任何 `x-api-key`/`Authorization`，因此即使存在 Anthropic 密钥，FireRouter 模式也能正常工作。解析出的 Anthropic 密钥将作为 `x-anthropic-api-key` BYOK 标头转发，以便 FireRouter 可以将困难的请求传递给 Anthropic 模型；它是可选的（仅 Fireworks 路由只需要 Fireworks 密钥）。Claude Code 在直接和 FireRouter 设置中都需要静态 Fireworks 标头，因此 FireConnect 会以 `0600` 模式将密钥写入 `settings.json`，并在执行 `off` 时恢复之前的文件。
**纯文本模型与图像。** Claude Code 无法将某个模型标记为非视觉模型。
如果你在纯文本槽位（例如 `glm-fast-latest` 或 `deepseek-v4-flash`）处于活跃状态时粘贴或附加图像，会话可能会中断，你可能需要使用 `/rewind` 来恢复。
当你的配置映射包含纯文本模型时，`fireconnect claude on` 会发出警告，并且 `fireconnect claude status` 会用 `vision` 或 `text-only` 标记每个槽位。
## 浏览和配置模型
浏览 Fireworks 目录，然后通过 `on` 配置 harness：
```
fireconnect model list --search glm
fireconnect claude on --sonnet kimi-latest
fireconnect opencode on --model glm-fast-latest
fireconnect codex on --model glm-fast-latest
fireconnect cursor on --model glm-fast-latest
```
### `fireconnect model list`
使用全局 Fireworks 密钥列出共享的 Fireworks serverless 目录。
从 Fireworks serverless 模型 API 获取带有 coding 标签的 serverless 模型（`GET /v1/serverless/models?use_cases=coding`），并合并已知的公共平台路由器（`glm-latest`、`glm-fast-latest`、`glm-5p2-fast`、`kimi-fast-latest`、`kimi-latest` 和 `kimi-k2p7-code-fast`）。每一行都被标记为 `serverless`（稍后将添加按需 endpoint）。
```
fireconnect model list
fireconnect model list --search glm
fireconnect model list --json
```
按照文档说明的顺序解析密钥：首先是 `--api-key`，然后是 `FIREWORKS_API_KEY`，最后是全局存储的凭证。标准密钥包含 `firerouter`；Fire Pass 密钥会省略它，仅显示 Fire Pass 支持的路由器。
Fire Pass 密钥（`fpk_...`）显示 Fire Pass 支持的路由器：`glm-latest`、`glm-fast-latest`、`glm-5p2-fast`、`kimi-fast-latest` 和 `kimi-k2p7-code-fast`。
### `fireconnect claude status` 与 `fireconnect model list` 对比
| 命令 | 显示内容 |
|---------|--------|
| `fireconnect claude status` | 你当前的提供商、身份验证、已配置的别名映射，以及每个槽位的 **Fireworks serverless 费率** |
| `fireconnect model list` | Fireworks API 中可用的 serverless endpoint，以及已知的 **IN / OUT 定价** |
### Claude Code 定价估算（重要）
Claude Code 的 `/model` 选择器和会话成本估算使用 **Anthropic 目录价格**（对应模型层级），而 **Fireworks 按 serverless 模型费率计费**。因此，UI 上的估算值可能远高于你的实际账单。
FireConnect 无法覆盖 Claude Code 的价格列。请使用 `fireconnect claude status` 和 `fireconnect model list` 获取 Fireworks 费率，查看[当前 serverless 定价](https://docs.fireworks.ai/serverless/pricing)，并使用 [Fireworks 账单仪表板](https://app.fireworks.ai/account/billing) 了解实际支出。
执行 `fireconnect claude on` 后，`settings.json` 会立即更新。要使用新模型，请退出 Claude Code，然后使用 `claude --resume ` 恢复对话，或者开始一个新的会话。
### 推荐的模型 slug
任何地方都接受短 ID 和规范的 `accounts/fireworks/...` ID。
OpenCode、Codex、Pi、Cursor、VS Code 和 Deep Agents 将直接的 Fireworks 选择存储为短 slug；现有的规范配置仍然兼容，并在下次运行 `on` 时进行迁移。Microsoft Foundry (Azure) 部署名称保持不变。
| 短 ID | 最适合 | 说明 |
|----------|----------|-------|
| `glm-latest` | 通用用途，agentic 任务 | 版本跟踪路由器；强大的推理能力，1M 上下文。 |
| `glm-fast-latest` | 对延迟敏感的 agentic 用途 | `main`、`opus` 和 `fable` 槽位的默认设置。在高速 Fast 服务路径（100+ tok/s）上的版本跟踪路由器，单 token 价格较高。1M 上下文。 |
| `glm-5p2-fast` | 对延迟敏感的 agentic 用途 | 与 `glm-fast-latest` 相同，但固定为 GLM 5.2 而不是版本跟踪。1M 上下文。 |
| `kimi-fast-latest` | 通用用途（较轻量） | 默认的 `sonnet` 槽位。高速 Fast 服务路径上的版本跟踪 Kimi 路由器。 |
| `glm-5p1` | 通用用途（较轻量） | 速度和质量的良好平衡。 |
| `deepseek-v4-flash` | 后台 / 快速任务 | 默认的 `haiku` 和 `subagent` 槽位。最低延迟。 |
**Fire Pass 密钥**（`fpk_...`）：所有槽位默认为 `glm-fast-latest`。
**切换单个槽位**（仅限 Claude Code）：
```
fireconnect model list --search glm
fireconnect claude on --opus glm-fast-latest --sonnet glm-5p1
fireconnect claude on --haiku deepseek-v4-flash --subagent deepseek-v4-flash
```
**OpenCode 和 Pi** 使用单一默认模型；在执行 `on` 时传递 `--model `。
## FireConnect CLI
该 CLI 是 harness 优先的：`fireconnect `。少数命令是全局的（不需要 harness）。以下命令的顺序与 `fireconnect help` 中一致。
**全局**
```
fireconnect login Sign in — browser (creates a key) or paste a key you have.
fireconnect logout Clear the stored key (keychain entry + config ref).
fireconnect status Show sign-in state, machine environment, and where the key is stored.
fireconnect configure Set the provider (Azure/Foundry) and the Anthropic key.
fireconnect demo Race your provider vs Fireworks GLM 5.2 Fast on the same prompt.
fireconnect uninstall Disable + restore all harnesses, then remove FireConnect.
fireconnect --version Print the installed CLI version (-V; --json for machine-readable).
fireconnect help Show help.
```
`login` 只询问一个重要问题：为这台机器创建 API 密钥，还是粘贴你已有的密钥。创建操作会打开浏览器（登录或注册），生成 `fireconnect-{hostname}`，并将其存储在 OS 钥匙串中 —— 同时确认它所属的账户以及密钥的具体去向。粘贴操作会引导你进入密钥页面，屏蔽粘贴的密钥，实时验证它，并且仅在成功时才进行存储。`--paste` 会跳过选择器直接进入粘贴步骤；`--with-token` 从 stdin 读取密钥（用于 CI）。一切操作都是可逆的，并且会明确告知：`logout` 会移除本地密钥，并提议在服务器端撤销机器密钥（`--revoke`/`--keep-key` 可跳过该询问）；` off` 会恢复已备份的设置。你不必从 `login` 开始 —— 像 `fireconnect claude on` 这样需要密钥的命令会以 inline 方式执行相同的登录，然后完成工作。
推荐流程：
```
fireconnect login # guided sign-in (browser or paste)
fireconnect claude on # Claude: static Fireworks header + optional websearch MCP
fireconnect codex on # Codex/OpenCode/Pi/Deep Agents: bake literal into harness config
```
`~/.fireconnect/config.json` 存储 `{keychain:fireworks-api-key}`（正常情况）。旧版安装可能仍有 `{env:FIREWORKS_API_KEY}` —— 配置中绝不会有明文的 Fireworks 密钥。
Fireworks 密钥本身存在于 OS 钥匙串中（或加密文件/明文回退层级中）。Harness 配置为 Codex、OpenCode、Pi、Deep Agents 和 Claude 的自定义标头保留了**内置的文字常量**；Cursor 和 VS Code 使用 IDE 的 safeStorage。
对于 **login 和其他显式存储路径**，`FIREWORKS_API_KEY` 和 FireConnect 管理的存储是互斥的。当设置了环境变量时，`fireconnect login` 会验证并使用它，而不会将其复制到 FireConnect 的密钥存储中。将登录与存储密钥的选项（`--api-key`、`--with-token`、浏览器登录或粘贴）结合使用，会在进行任何更改之前失败。当希望 FireConnect 将密钥存储在 OS 钥匙串/密钥环中时，请先取消设置 `FIREWORKS_API_KEY`。
对于 `fireconnect on`，可能仍会读取 `FIREWORKS_API_KEY`，将其持久化到钥匙串中（针对文件配置型 harness），并将其内置到该 harness 的配置中。
托管的 shell hook（`export FIREWORKS_API_KEY="$(fireconnect key export)"`）仅为 Claude websearch MCP（在 `~/.claude.json` 中的 `${FIREWORKS_API_KEY}`）安装。重新运行 `install.sh` 会将已启用的 harness 配置重新生成为文字常量，包括磁盘上留下的任何旧版环境变量引用身份验证。
**每个 harness**（`claude`、`opencode`、`codex`、`pi`、`cursor`、`vscode`、`deepagents`）
```
fireconnect on Route the harness through Fireworks (default if no command).
fireconnect off Restore your previous provider/config.
fireconnect status Show the provider, auth, and model mapping.
fireconnect help Show help for that harness.
```
全局目录发现：`fireconnect model list`。
所有的模型更改都通过 ` on` 进行；`--model ` 设置主要/默认模型，Claude 的别名标志则用于设置各个语义槽位。
Claude 还具有 `fireconnect claude usage`（根据会话日志估算使用成本）。
运行 `fireconnect help` 获取概述，或运行 `fireconnect help`（例如 `fireconnect claude help`、`fireconnect cursor help`、`fireconnect vscode help`、`fireconnect deepagents help`）了解 harness 级别可用的所有功能。
## Codex Harness
FireConnect 通过 Responses API 将 [OpenAI Codex CLI](https://developers.openai.com/codex) 通过 Fireworks 进行路由：
```
fireconnect login
fireconnect codex on # route Codex through Fireworks (~/.codex/config.toml)
fireconnect codex status # check current provider and model
fireconnect codex on --model glm-5p1 # switch model (non-interactive)
fireconnect codex on --model firerouter # route requests through FireRouter
fireconnect codex off # restore your original config
```
它的作用是：
- 为 Codex 0.134+ 设置根 `model_provider` / `model`（将 `model` 存储为短 slug），并添加一个 `[model_providers.fireworks-ai]` 块，其中包含 `wire_api = "responses"` 和一个**内置的** `experimental_bearer_token` 文字常量（文件模式 `0600`）。Codex 从配置中读取密钥 —— 正常的 Fireworks 路由不需要 shell hook。
- 将**首选的 serverless 目录**（`*-latest`、`*-fast-latest` 或最新的具体系列版本）写入 `~/.codex/fireworks-model-catalog.json`，并通过 `model_catalog_json` 指向 Codex（短 slug；首选 latest 别名；过滤掉 embeddings/no-tools/deprecated 模型）。来自 Fireworks API 和旧目录的规范模型 ID 仍然被接受。配置了 Workspace-BYOK 的账户和具有有效 `ANTHROPIC_API_KEY` 的会话也会接收 `firerouter`；否则使用 `on --model firerouter` 选择它。`codex off` 会移除目录文件和引用。
- 在首次更改之前，对你的原始 `~/.codex/config.toml` 进行快照。`fireconnect codex off` 会逐字节恢复它，并在没有其他地方需要 `FIREWORKS_API_KEY` 时协调 shell hook。
- 通过精准的 TOML 编辑，保留不相关的 Codex 设置（例如 `[[mcp_servers]]`）。
**Codex 不支持 MiniMax 模型。** Codex 使用 Fireworks Responses API，可能会在 `tool_calls` 和 `tool_results` 之间插入 assistant 消息。MiniMax chat 模板要求 `tool_results` 紧跟在 `tool_calls` 之后，因此 Codex 会话会因模板错误而失败。MiniMax 仍可通过 Chat Completions harness（例如 Claude 或 OpenCode）使用。如果你运行 `fireconnect codex on --model minimax-m3`，FireConnect 会拒绝该请求并给出解释。
### FireRouter 模式
`fireconnect codex on --model firerouter 会在常规的 Fireworks 网关提供商（`https://api.fireworks.ai/inference/v1`，Responses API）上注册 `firerouter` 模型。像任何其他 Fireworks 模型一样，Fireworks 密钥被内置到 `config.toml` 中。可选的 Anthropic BYOK 密钥会作为 `env_http_headers` 的 `x-anthropic-api-key` 引用附带发送，以便 FireRouter 可以将困难的请求传递给 Anthropic；请 export `ANTHROPIC_API_KEY` 或依赖工作区 BYOK。（FireRouter 不支持 OpenAI BYOK。）
```
export ANTHROPIC_API_KEY=sk-ant-...
fireconnect codex on --model firerouter
```
`fireconnect codex off` 会逐字节恢复原始的 `config.toml`。
在执行 `fireconnect codex on` 或 `off` 之后，`config.toml` 会立即更新。要使用更新后的路由，请退出 Codex，然后使用 `codex resume ` 恢复，或者开始一个新的会话。
## OpenCode Harness
FireConnect 使用 harness 优先的命令将 [OpenCode](https://opencode.ai) 通过 Fireworks 进行路由：
```
fireconnect login
fireconnect opencode on # route OpenCode through Fireworks
fireconnect opencode status # check current provider
fireconnect opencode on --model glm-5p1 # switch model (non-interactive)
fireconnect opencode off # restore your original config
```
它的作用是：
- 将 `provider.fireworks-ai` 块合并到 `~/.config/opencode/opencode.json` 中，将默认 `model` 设置为 `fireworks-ai/`，并通过短 slug 为提供商模型添加键值。`options.apiKey` 是一个**内置的明文文字常量**（文件模式 `0600`）。现有的规范模型引用仍然兼容。
- 在 OpenCode 的 `/model` 选择器中的提供商 `models`（`*-latest` / `*-fast-latest`，否则为最新的具体系列版本）中注册**首选的 serverless 目录** —— 对于 workspace BYOK 或有效的 `ANTHROPIC_API_KEY`，还会加上 `firerouter`。当无法获取目录时（离线状态），回退到当前活跃的模型。`on --model firerouter` 仅注册 `firerouter` 模型（它在服务器端进行路由）。
- 在首次更改之前，对你的原始 `opencode.json` 进行快照。`fireconnect opencode off` 会**逐字节**恢复它。快照位于 `~/.fireconnect/opencode/` 中。
使用 `--config-path ` 指向非默认的配置文件（也方便在不动你真实配置的情况下进行测试）。运行 `fireconnect help` 获取完整的 CLI 参考。
OpenCode 还支持在 Microsoft Foundry (Azure) 上通过 Fireworks 模型进行路由 —— 请参阅 [Azure (Microsoft Foundry) endpoint](#azure-microsoft-foundry-endpoints)。
## Pi Harness
FireConnect 使用 harness 优先的命令将 [Pi](https://pi.dev) 通过 Fireworks 进行路由：
```
fireconnect login
fireconnect pi on # route Pi through Fireworks
fireconnect pi status # check current provider
fireconnect pi on --model glm-5p1 # switch model (non-interactive)
fireconnect pi on --model firerouter # route Anthropic models through FireRouter
fireconnect pi off # restore your original settings and auth
```
它的作用是：
- 在 `~/.pi/agent/settings.json` 中设置 `defaultProvider` / `defaultModel`，并在 `fireworks.key`（`auth.json`，模式 `0600`）中存储一个**内置的明文文字常量**。除非你传递 `--model`，否则 `on` 会应用默认模型（`glm-fast-latest`）。
- 在 `~/.pi/agent/models.json`（`*-latest` / `*-fast-latest`，否则为最新的具体系列版本）中为 Pi 的 `/model` 选择器注册**首选的 serverless 目录**，对于 workspace BYOK 或有效的 `ANTHROPIC_API_KEY`，还会加上 `firerouter`。`settings.defaultModel`、托管状态 ID 和提供商模型 ID 均为短 slug。每个受管理的短 ID 模型都会获得一个完整的 `models` 条目，因此尽管 Pi 的内置目录是以规范 ID 为键的，Pi 仍能保留上下文、定价、推理和视觉元数据。在离线状态下回退到捆绑的路由器集合；`on --model firerouter` 仅注册 `firerouter` 模型。
- 在首次更改之前，在 `~/.fireconnect/pi/` 下对这两个文件进行快照。`fireconnect pi off` 会**逐字节**恢复它们。`auth.json` 以模式 `0600` 写入。
- 如果 Pi 已经在运行，请在执行 `on` 或 `off` 之后重启 Pi。
### FireRouter 模式
`fireconnect pi on --model firerouter` 会在 Pi 常规的 Fireworks 提供商上选择 `firerouter`。Fireworks 密钥的解析方式与所有其他 Fireworks 模型完全相同。Anthropic BYOK 密钥是可选的，在提供时，它会作为 `x-anthropic-api-key` 模型标头附加：
```
fireconnect pi on --model firerouter --anthropic-api-key sk-ant-...
fireconnect pi on --model firerouter
```
FireConnect 会备份 `settings.json`、`auth.json` 和 `models.json`，`fireconnect pi off` 会逐字节恢复这三个文件。重新运行 `on --model ` 或使用 Pi 的模型选择器切换到另一个 Fireworks 模型。
使用 `--settings-path ` 指向非默认的设置文件。
Pi 还支持在 Microsoft Foundry (Azure) 上通过 Fireworks 模型进行路由 —— 请参阅 [Azure (Microsoft Foundry) endpoint](#azure-microsoft-foundry-endpoints)。
## Azure (Microsoft Foundry) endpoint
Fireworks AI 模型还可以在 [Microsoft Foundry](https://docs.fireworks.ai/ecosystem/integrations/azure-foundry)（前身为 Azure AI Foundry）中作为第一方模型使用，其使用量通过 Azure 计费并计入你的 MACC。Foundry 暴露了一个 **OpenAI 兼容**的 endpoint，因此 **OpenCode、Codex、Pi、Deep Agents、Cursor 和 VS Code** 可以通过你的 Foundry 资源而不是 Fireworks 网关进行路由。
**只需配置一次 endpoint**，然后 ` on` 就会利用它 —— 无需每个命令都加标志：
```
fireconnect configure --provider azure \
--base-url https://.services.ai.azure.com \
--api-key
fireconnect opencode on # routes through the configured Foundry endpoint
fireconnect codex on
fireconnect pi on
fireconnect deepagents on
fireconnect cursor on
fireconnect vscode on
```
`configure` 将顶层的 `provider` 和 `azure` endpoint 存储在 `~/.fireconnect/config.json` 中；这种设计可扩展到未来的提供商，而无需触及 harness。要切回去，请运行 `fireconnect configure --provider fireworks ...`。
你也可以通过 `--azure` 为每个命令选择启用（或覆盖已配置的 endpoint）：
```
fireconnect opencode on --azure --base-url https://.services.ai.azure.com \
--api-key --model FW-GLM-5.2
```
各个 harness 的共同行为：
- **Endpoint。** 将你的 Foundry endpoint 传递给 `--base-url`。无论你粘贴的是什么 —— 裸资源根目录、门户的 **project endpoint**（`.../api/projects/`）还是 `/models` 路由 —— FireConnect 都会将其规范化为正确的资源根目录 base `https://.services.ai.azure.com/openai/v1`。在 Microsoft Foundry 门户的 **Project settings** 下找到该 endpoint。
- **身份验证。** 使用你的 **Azure** API 密钥（不是 `fw_`/`fpk_` 密钥）进行身份验证。传递 `--api-key` 以将其字面写入，或者 export `AZURE_API_KEY` 使其作为环境变量引用写入。
- **模型。** 模型 ID 是你的 Foundry **部署**名称 —— 即不带 `fireworks-ai/` 发布者前缀的目录模型名称（例如 `FW-GLM-5.2`、`FW-MiniMax-M2.5`）。默认为 `FW-GLM-5.2`；传递 `--model ` 选择另一个。
- **提供商隔离与恢复。** 每个 harness 都会写入一个与 Fireworks 网关截然不同的专用 `fireworks-azure` 提供商，并且 `off` 会**逐字节**恢复你的原始配置。在 Fireworks 和 Azure 模式之间切换可以干净地替换受管理的提供商。
各个 harness 的具体情况：
| Harness | 写入位置 | 提供商 |
|---------|--------|----------|
| OpenCode | `opencode.json` 中的 `provider.fireworks-azure`（`@ai-sdk/openai-compatible`，`options.baseURL` + `options.apiKey`） | `fireworks-azure/` |
| Codex | `config.toml` 中的 `[model_providers.fireworks-azure]`（`wire_api = "chat"`，bearer 或 `env_key = "AZURE_API_KEY"`） | `fireworks-azure` |
| Pi | `models.json` 中的自定义 `openai-completions` 提供商（`baseUrl`、`authHeader`、字面量 `apiKey` 或 `$AZURE_API_KEY`） + `settings.json` 中的 `defaultProvider` | `fireworks-azure` |
| Deep Agents | `config.toml` 中的 `[models.providers.fireworks-azure]` | `fireworks-azure:` |
| Cursor | Cursor 的 `state.vscdb` 中兼容 OpenAI 的 URL、部署和密钥 | `` |
| VS Code | `chatLanguageModels.json` 中的自定义 endpoint 模型；VS Code `safeStorage` 中的密钥 | `` |
`fireconnect status` 会报告 `azure` 作为提供商，以及 endpoint 和模型。
## Deep Agents Harness
FireConnect 将 [LangChain Deep Agents Code](https://docs.langchain.com/oss/python/deepagents/cli)（`dcode`）通过 Fireworks 进行路由：
```
fireconnect login
fireconnect deepagents on # route Deep Agents through Fireworks
fireconnect deepagents status # check current provider
fireconnect deepagents on --model glm-5p1 # switch model (non-interactive)
fireconnect deepagents off # restore your original config
```
它的作用是：
- 将 `[models].default` 设置为 `fireworks:`，并在 `~/.deepagents/config.toml` 中配置 `[models.providers.fireworks]`，使用 Fireworks 兼容 OpenAI 的 base URL（`https://api.fireworks.ai/inference`）和一个**内置的** `api_key` 文字常量（文件模式 `0600`）。现有的规范 `fireworks:accounts/fireworks/...` 模型引用仍然兼容。
- 通过 `fireconnect login` 或 `deepagents on --api-key` 将你的 Fireworks API 密钥存储在 FireConnect 钥匙串中，然后将其内置到 `config.toml` 中。FireConnect 不会写入 `~/.deepagents/.state/auth.json` —— 请使用 dcode 的 `/auth` 来管理存储在该文件中的凭证。
- 在首次更改之前，在 `~/.fireconnect/deepagents/` 下对 `config.toml` 进行快照。`fireconnect deepagents off` 会逐字节恢复它。
- 在执行 `on` 或 `off` 之后重启 `dcode`。
使用 `--config-path ` 指向非默认的配置文件。
标签：AI模型接入, Cutter, GNU通用公共许可证, MITM代理, Node.js, 开发辅助, 文档结构分析, 暗色界面, 自定义脚本