Claude API 0.9.18 新增

Claude API 提供商用 Claude Console 的 API 密钥而不是你的 Claude 订阅来运行 Claude 对话。智能体是同一个：中继机器上的 Claude Code，具有相同的工具、模式、提问卡片、子智能体、引导和后台任务。只有账单会变。轮次会计费到该密钥所属的 Console 组织。

Claude API 与你的订阅并存，而不是取代它。你可以用密钥开始一个对话，也可以用订阅开始一个对话，还可以在轮次之间把 Claude 对话从一方切换到另一方，同时保留其会话。可选的每月上限会在本中继的估算达到上限时停止该密钥上的花费。所有提供商的对照表见提供商一览。

API 密钥 #

你需要一个来自 Claude Console 的 API 密钥，位于 platform.claude.com 的 API keys（API 密钥）页面。请在工作区内创建它；见限制。打开 Settings → Providers → Claude API（设置 → 提供商 → Claude API），即 Claude 之后的子选项卡。

控制	默认值	作用
Enable Claude API for New Chat and the billing switch（在新建对话和计费开关中启用 Claude API）	保存密钥后开启	在 New Chat（新建对话）中提供 Claude API，并在 Claude 对话中提供计费开关。在保存密钥之前无法勾选，切换后立即生效。
密钥字段（`Claude Console API key…`）	空	你的密钥。保存密钥后，字段显示为 `Saved API key (enter to replace)`。留空以保留已保存的密钥。
Default model（默认模型）	若密钥支持，则取 Claude 选项卡的默认模型，否则取第一个 Sonnet	新的 Claude API 对话一开始所用的模型。见模型。
Monthly cap in US dollars (optional)（每月上限，美元，可选）	空（`No cap`）	当本月估算达到它时，停止密钥上的新轮次。见每月上限。
Save Claude API settings（保存 Claude API 设置）		保存上述字段。密钥的第一次保存也会开启 Claude API。
Refresh models（刷新模型）		再次向 Anthropic 询问该密钥可用的模型。
Remove saved key（删除已保存的密钥）		询问 `Remove the saved Claude API key?`，然后删除密钥、该密钥的模型列表和你在 Select Models（选择模型）中的选择，并关闭 Claude API。
Claude tab（Claude 选项卡）		打开 Claude 子选项卡，其中包含两者共享的设置。见与 Claude 共享的设置。

字段下方的一行会说明当前所处的状态：

状态	含义
`No API key saved. Claude chats run on the relay host's Claude login.`	没有保存密钥。
`API key saved, Claude API is off. Switch it on to offer it in New Chat.`	已保存密钥但开关关闭。
`API key saved. Claude API is on: pick it in New Chat, or switch a Claude chat to the API key.`	就绪。
`API key saved, but Anthropic refused it: …`	Anthropic 在保存密钥或刷新模型时没有接受该密钥。密钥仍保持保存状态；该行会一直显示，直到一次保存或 Refresh models 成功。

然后照常开始对话：在 New Chat 中选择 Claude API。见开始对话。Claude API 对话带有一个金色 Claude API 标签，输入区的锁定提示显示为 🔒 Session locked to Claude API models.。

接受哪些密钥 #

Console API 密钥，即以 sk-ant- 开头、8 到 512 个字符且不含空格的密钥。
Claude 登录和会话令牌，以及 Admin 密钥，在保存时会被拒绝，并带有一条说明所粘贴内容的提示，例如 This is an Anthropic Admin API key (it manages an organisation and cannot run models), not an API key.。其他厂商的密钥会得到 This does not look like a Claude API key.。任何提示都不会引用密钥本身。
Anthropic 是否接受该密钥，会在中继请求其模型时显示（见模型）。被拒绝的密钥仍保持保存状态，状态行会说明原因。

保存、更换与移除密钥 #

保存不同的密钥会清空该密钥的模型列表，并停止正在运行的 Claude API worker，包括处于一轮之中的，因此请在轮次之间更换密钥。下一条消息会用新密钥启动它们。
当任何 Claude API 对话已发送消息或有排队中的消息时，移除密钥会被拒绝：Cannot remove the Claude API key while N Claude API conversation(s) still exist. Switch Claude API off for new conversations instead.。当仍有 worker 在该密钥上运行时，也会被拒绝。
移除密钥或关闭 Claude API，会把尚未发送消息的 Claude API 对话移回 Copilot。已在密钥上开始的对话会保留它的计费开关，因此你可以把它移到订阅；当 Claude API 关闭时，它在密钥上的轮次不会运行。

在订阅与密钥之间切换对话 #

无论使用哪种计费方式，Claude 对话的锁定提示下方都有一个开关：Subscription | API key（订阅 | API 密钥）。当 Claude API 已开启且保存了密钥时，它才会显示。正在使用密钥的对话在 Claude API 关闭后仍保留这个开关，因此可以切回订阅。

从下一轮起。 正在运行的轮会在它开始时的计费方式上结束。已排队的消息会运行在新的计费方式上。
会话保持不变。 中继会在轮次之间重启该对话的 Claude Code，并恢复同一个会话。它会等待正在运行的轮、未回答的问题、压缩或后台任务，开关会说明等待的是哪一项，例如 Moves to the API key after the running turn.。
密钥上的第一轮更贵。 它没有提示词缓存。开关会这样说明：The first turn on the API key has no prompt cache and costs more.。
对话记录会记下每次切换，例如 💳 Billing: this chat runs on the Claude API key from the next turn.，并在适用时附上 (switched by an agent) 或 (switched at the usage limit)。
当某一侧无法选择时，它的按钮会变灰，其提示文字会说明原因。当 Claude API 没有密钥或已关闭、本月上限已达（开关此时显示 This month's Claude API cap is reached: the chat stays on the subscription.）、切回订阅时 Claude 被关闭（CLAUDE_NOT_CONFIGURED）、或该对话的模型不在另一侧的模型列表中时，切换会被拒绝。
页面未及时更新。 从仍显示旧计费方式的页面发送的消息，不会以新的计费方式发送：它的文本会退回草稿。

除此之外，没有任何东西会切换对话的计费方式。切换途径共有三种：开关、用量上限横幅，以及智能体的 send：

在用量上限处。 当订阅对话在 Claude 用量上限处暂停时，如果该对话可以移动，横幅会提供 Switch this chat to API key（将此对话切换到 API 密钥）。暂停的轮随后会立即在密钥上继续。在上限处，横幅会显示 No switch to the API key: this month's Claude API cap is reached.。
由智能体。 relay_tool 的 send 对 Claude 会话接受 provider（claude 或 claude-api），并随消息一起切换。审批卡片此时会显示 Switches billing to API key。

计费没有按文件夹的设置：每个对话都有自己的计费方式，在 New Chat 中选择并通过开关更改。文件夹所设置的，即它的提交署名，对两种计费方式都适用。

每月上限 #

Monthly cap in US dollars (optional) 按本中继自己的估算，限制本中继在一个自然月内在该密钥上的花费。金额大于 0，最高 1,000,000，最多两位小数；留空表示无上限。

一旦本月估算达到上限：

密钥上的新轮不会运行。 对话会收到一条以 Error code: relay.claude-api-cap-reached. 结尾的提示，以及 Claude API settings（Claude API 设置）和 Switch to subscription（切换到订阅）两个按钮；前者会打开该选项卡并定位到上限字段。
切换到密钥会被拒绝，无论是通过开关、用量上限横幅还是智能体。
New Chat 会拒绝 Claude API 对话。 对话框保持打开，并显示原因、Claude API settings 和 Start on subscription（使用订阅开始），后者会改为在 Claude 上开始同一个对话（当 Claude 开启时提供）。在手机上，对话框会滚动到它。
智能体也会被拒绝。 智能体对密钥上会话的 send，以及它为 Claude API 对话发起的 create_session，都会被拒绝：中继回答 409 CLAUDE_API_CAP_REACHED，且不会有任何内容排队或创建。
Claude Code 在密钥上自行开始的轮（在后台任务回报结果时）会收到该提示，且该对话的后台任务会被停止，因为每次回报都会再开始一个这样的轮。它的第一个请求可能已经被计费。该提示在每个对话只出现一次，直到上限解除、保存了某个 Claude API 设置，或该对话的某轮再次在密钥上运行。

已经在运行的轮会结束。一轮的成本在它结束时入账，因此正在运行的轮可能把本月推到超过上限。上限只计算估算中有价格的部分（见限制）。当设置了上限而花费无法读取时，上限视为已到达。月份以中继为准：在中继时区的每月 1 日午夜重新开始。Console 中设置的花费限制会叠加生效。

当 Claude API 没有密钥（relay.claude-api-not-configured）或被关闭时，也会出现同样的提示和按钮：该轮不会运行。此时 New Chat 也会以 CLAUDE_API_NOT_CONFIGURED 拒绝 Claude API 对话。

用量卡片 #

只要保存了密钥，即使 Claude API 已关闭，📊 Check Usage（查看用量）也会有一个 Claude API 标签页，让本月的花费始终可见。它显示本中继在该密钥上的轮次估计花费了多少：

部分	显示内容
Monthly cap（每月上限）条	仅在设置了上限时：本月估算相对上限的情况，标记为 estimated（估算），以及它重新开始的时间。
Estimated today（今日估算）、Estimated this month（本月估算）	当天和本月迄今的花费。
Estimated spend by model, this month（按模型估算花费，本月）	每个模型一行，附上它今天的费用。
Tokens by model, this month（按模型的 token，本月）	每个模型的缓存读取、其他输入（包括写入提示词缓存的部分）和输出，以及输入中有多少来自缓存。
估算说明	这些数字的来源。

与所有进度条一样，该条在用到上限的 50% 和 75% 时变色，到 90% 时变红；见阅读卡片。卡片链接到 Console billing（Console 计费）和 Console limits（Console 限额）。

数字的来源。 它们是 Claude Code 根据自己的价格表对本中继已保存密钥上的轮次所做的估算，因此子智能体、压缩和网络搜索都包含在内。OAR 不保留自己的价格表。天和月份遵循中继的时钟和时区。用 Max 或 Team 套餐附带的 API 额度支付的轮次也会被计入；OAR 看不到该额度，也看不到 Console 余额。Console 的计费页面才有真实数字和余额。

没有价格的 token。 Claude Code 没有其价格的模型会显示 no price known 而不是金额，绝不是 $0。把这类 token 排除在外的合计会显示 (estimate incomplete)。

智能体可以用 relay_tool 的 usage 操作读取同一张卡片。

模型 #

在你保存密钥、再次开启 Claude API，以及在该选项卡上按 Refresh models 或在 🤗 Select Models 中按 Refresh（刷新）时，中继会向 Anthropic 询问该密钥可用的模型（GET /v1/models）。请求会在 10 秒后放弃。

在收到第一次答复之前，该选项卡会提供 Claude 选项卡的模型，并带提示 Not listed by Anthropic yet: these are the Claude tab's models until the key's list is read.。
失败的请求会保留中继已有的列表；Refresh models 会显示 Claude API model discovery failed. The stored models were kept: …。
长上下文。 窗口为 100 万 token 或更多的模型，或 Claude 选项卡列出了其 1M 变体的模型，也会得到它的 [1m] 变体，与 Claude 上一样在 Context window（上下文窗口）下拉菜单中提供。
哪些会显示。 🤗 Select Models → Claude API（选择模型 → Claude API）决定输入区提供哪些模型。Default model 始终提供。
按消息。 对话可以在轮次之间更换模型，与 Claude 上相同。

推理强度 #

强度选择器的工作方式与 Claude 上相同。级别来自 Anthropic 的模型列表：none 以及模型所报告的级别，再加上具有 xhigh 的模型上的 Ultracode。报告无强度支持的模型只提供 none。在读取到该密钥的列表之前，模型使用 Claude 选项卡为它提供的级别。🧠 对话框中有与 Claude 上相同的 Thinking（思考）控件。

与 Claude 共享的设置 #

提交署名、后台命令上限、推理强度级别和压缩窗口都沿用 Claude 选项卡的设置，因此切换只会改变由谁付费：

提交署名，文件夹的选择来自 🧠 对话框；
后台命令上限；
自动压缩窗口。

一个 Claude 配置文件夹。 Claude API 对话使用与订阅对话相同的 Claude Code 文件夹（~/.claude，或 CLAUDE_CONFIG_DIR）：相同的技能、插件、MCP 服务器和对话记录。这就是对话在切换时能保留会话的原因。该文件夹或对话文件夹 .claude/ 中的设置无法重定向密钥：中继会在它们之上固定 Anthropic 的地址和密钥。

密钥上不适用的部分。 Claude 的套餐用量计量和用量上限暂停不适用：被 Anthropic 拒绝的轮会失败，并附上一条提示。Claude API 对话以关闭所有钩子和状态行的方式运行；见安全。

其余情况，以 Claude 为准。 当其他页面描述 Claude 对话的行为时，例如子智能体、后台任务、压缩、计划看板、提问卡片或一轮期间的发送按钮，Claude API 对话的做法相同。

限制 #

工作区之外的密钥会得到 HTTP 400。 Anthropic 对未绑定到工作区的密钥回答 HTTP 400，选项卡会显示 API key saved, but Anthropic refused it: …。请在 Claude Console 的某个工作区内创建密钥，并保存这个密钥。在 OAR 中指定工作区的功能已在计划中。
没有价格的模型。 Claude Code 没有其价格的模型（目前是 Claude Haiku 5.5）会在卡片上显示 no price known。它的 token 会被排除在估算和上限之外。
估算以本中继为准。 该密钥的其他使用不包含在内；Console 有每一次请求。
没有余额。 OAR 不读取 Console 余额或套餐的 API 额度。
没有基础 URL。 密钥只发往 https://api.anthropic.com。没有针对其他端点的设置。
智能体可以读取密钥。 见安全。

错误码 #

失败的 Claude API 回复以 Error code: relay.<code>. 结尾，对某些代码还会带有直达修复的按钮：

代码	何时出现	按钮
`relay.claude-api-cap-reached`	本月估算已达到上限；该轮未运行。	Claude API settings（在上限字段处）、Switch to subscription
`relay.claude-api-not-configured`	Claude API 没有密钥、已关闭，或中继无法检查；该轮未运行。	Claude API settings、Switch to subscription
`relay.claude-api-key`	Anthropic 没有接受该密钥（HTTP 401 或 403）。	Claude API settings
`relay.claude-api-key-source`	Claude Code 以已保存密钥之外的凭据启动，该轮被停止。见安全。	Claude API settings
`relay.claude-api-credit`	账户的额度余额过低。	Add funds（添加资金）、Claude API settings
`relay.claude-api-billing`	Anthropic 因计费原因拒绝了请求（HTTP 402）。	Console billing
`relay.claude-api-spend-limit`	账户达到了 Console 中设置的花费限制。	Console limits
`relay.claude-api-rate-limit`	Anthropic 正在对该密钥限流或过载（HTTP 429 或 529）。	Console limits

Claude API settings 打开 Settings → Providers → Claude API。Add funds 和 Console billing 打开 Console 的计费页面，Console limits 打开它的限额页面。Switch to subscription 会从下一轮起把对话移到你的订阅；然后重新发送消息。

中继自己的拒绝也有代码：

代码	位置	含义
`CLAUDE_API_CAP_REACHED`	New Chat、计费开关、智能体的 `send` 或 `create_session`	已达到上限。
`CLAUDE_API_NOT_CONFIGURED`	New Chat、计费开关	Claude API 没有密钥，或已关闭。
`CLAUDE_NOT_CONFIGURED`	New Chat、计费开关	Claude 提供商（订阅）已关闭：无法开始 Claude 对话，密钥上的对话也无法切回。请在 Settings → Providers → Claude（设置 → 提供商 → Claude）中开启 Claude。
`CLAUDE_BILLING_MODEL_UNAVAILABLE`	计费开关	该对话的模型不在另一侧的列表中。选一个它有的模型，再切换。
`CLAUDE_BILLING_SWITCH_REQUIRED`、`CLAUDE_BILLING_CHANGED`	发送消息时	消息指定了另一种计费方式，或来自仍显示旧计费方式的页面。不会发送任何内容；文本退回草稿。

疑难解答 #

问题	怎么办
New Chat 中没有 Claude API，或开关拒绝 API key	在 Settings → Providers → Claude API 中保存密钥，检查 Enable Claude API for New Chat and the billing switch 是否勾选，以及本月花费是否已达到上限。开关的提示文字会说明原因。
`API key saved, but Anthropic refused it: …` 带有 400，或每一轮都因 HTTP 400 失败	该密钥未绑定到工作区。请在 Claude Console 的工作区内创建一个并保存。
`relay.claude-api-key`	密钥错误或已被撤销。在轮次之间粘贴有效密钥并保存。
`relay.claude-api-credit`、`relay.claude-api-billing` 或 `relay.claude-api-spend-limit`	按 Add funds、Console billing 或 Console limits，在 Claude Console 中修复，然后重新发送消息。
`relay.claude-api-cap-reached`	按 Switch to subscription，或用 Claude API settings 提高上限。上限在每月 1 日重新开始。
New Chat 说已达到上限	按 Start on subscription，或提高上限。
卡片对某模型显示 `no price known`	Claude Code 还没有它的价格（目前是 Claude Haiku 5.5）。它的 token 会列出，但不在估算或上限中。
卡片的花费低于 Console 的	卡片只计算本中继在密钥上的轮次。
`relay.claude-api-key-source`	从中继机器上的 Claude Code 设置（`settings.json`）中移除 `apiKeyHelper` 或其他凭据，检查选项卡上的密钥，然后重新发送消息。
`Cannot remove the Claude API key while …`	归档或删除那些对话，或把它们移到订阅，或改为关闭 Claude API。

安全 #

密钥保存在哪里。 密钥存储在中继机器的中继数据库中，绝不会发送到浏览器：选项卡上只显示已保存了一个密钥。中继自己仅在一个请求（模型列表）中使用它，并且只发送到 https://api.anthropic.com，别无他处。它只会到达 Claude API 对话的 worker，在会话于 tmux 下运行时，通过一个只有中继用户可读的文件传递。在 worker 内部，它通过其环境和通过标准输入交给它的设置到达 Claude Code，绝不会出现在命令行上，因为机器上的其他用户能读到命令行。中继自身环境中的密钥（ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN）不会到达任何对话。

智能体能看到什么。 智能体自己的命令可以从其环境读取密钥，正如 CLI 持有的任何密钥一样。从保存那一刻起，中继会在 worker 发布的任何内容和 worker 的日志中把密钥替换为 [redacted]，与 DeepSeek 相同。这能让密钥不出现在 OAR 存储和显示的内容中；但它对智能体不构成屏障。

凭据会被检查，且一个模型请求可能先发出。 Claude API 对话共享你的 Claude 登录所在的 Claude Code 文件夹。中继会把已保存的密钥固定在该文件夹或对话文件夹设置中的任何凭据之上，并且当 Claude Code 的启动报告把另一个来源列为它的密钥时，中继会立刻停止该轮（relay.claude-api-key-source）。Claude Code 不会等待那次检查：它会在报告后大约 50 到 90 毫秒发送第一个模型请求，因此在停止生效之前，可能已经有一个模型请求在另一个凭据（例如你的 Claude 登录）上发出。该检查能把错误凭据限制在那一个模型请求；它并不能阻止它。同样的检查会在你的订阅对话中以相反方向运行；见 Claude。

没有钩子。 Claude API 对话中的 Claude Code 以关闭所有钩子的方式启动：无论是你自己的（~/.claude）、对话文件夹的（.claude/settings.json、settings.local.json），还是插件的，都不会运行，状态行命令也不会。它们会以中继用户的身份运行，环境中带着密钥。该设置位于 Claude Code 的命令行上，因此设置文件无法把它们重新打开。托管设置（机器管理员的）中的钩子仍会运行。订阅上的对话会保留它们的钩子和状态行。

发送给 Anthropic 的内容。 智能体在一轮期间读取和写入的一切，与订阅对话相同。

详见安全。