已连接服务

将提供商订阅与 API 密钥关联至 Kaiwu，在支持的后端之间复用，并在可用时监控配额快照。

已连接服务允许你在 Kaiwu 中一次性存储提供商凭据，并在受支持的后端与会话间反复复用。

它不同于提供商设置中的提供商身份验证：

已连接服务存储在 Kaiwu 中，可在兼容的后端之间复用
提供商身份验证则反映某台特定设备上提供商 CLI 的原生登录状态

参见提供商身份验证。

该功能旨在帮助你：

关联订阅和 API 密钥，无需为每个后端反复手动输入
将凭据加密保存在 Kaiwu Cloud 中，仅在客户端 / 守护进程上解密
在启动会话时按服务选择身份验证方式，而不单纯依赖各后端的原生身份验证
监控受支持服务的使用量与额度快照
简化多设备工作流，使目标设备能直接复用 Kaiwu 托管的同一凭据

什么是已连接服务

Kaiwu 将不同类型的凭据分别建模为独立的已连接服务：

openai-codex：OpenAI Codex 订阅身份验证
openai：OpenAI API 密钥身份验证
claude-subscription：Claude 订阅身份验证
anthropic：Anthropic API 密钥身份验证
gemini：Gemini OAuth 身份验证
github：用于版本控制工作流的 GitHub 令牌身份验证

这种拆分是刻意设计的。订阅身份验证和 API 密钥身份验证在提供商行为、计费途径以及后端具象化需求上均有不同，因此 Kaiwu 不会将它们合并为泛化的“Claude”或“OpenAI”单一凭据类型。

GitHub 是首个非智能体/后端凭据的已连接服务，供 GitHub 代码仓库发布、GitHub 拉取请求操作等版本控制功能使用。

如何管理已连接服务

在客户端中：

设置 -> 已连接服务

你可以在此处：

为同一服务添加一个或多个配置
为配置添加自定义标签
为每个服务设置默认配置
查看提供商邮箱、账户 ID 和额度计量表等配置详情
断开单个配置的连接

在 CLI 中：

kaiwu connect status
kaiwu connect codex ...
kaiwu connect claude ...
kaiwu connect gemini

连接方式

OpenAI Codex

支持的方式：

设备代码（device code）
粘贴重定向 URL
应用内浏览器（仅限原生客户端）

OpenAI Codex 也支持通过 API 密钥连接，但在架构上被建模为独立的 openai 服务。

OpenAI API 密钥

支持的方式：

手动输入 API 密钥

若希望基于 OpenAI 的后端直接调用你自己的 API 密钥运行，而非使用 Codex 订阅登录，请使用此项。

Claude 订阅

支持的方式：

setup-token
粘贴重定向 URL
应用内浏览器（仅限原生客户端）

推荐默认使用 setup-token。可在已登录 Claude Code 的任意设备上生成：

claude setup-token

然后将其粘贴到 Kaiwu 中。

Anthropic API 密钥

支持的方式：

手动输入 API 密钥

此项对应 Anthropic Console 的 API 密钥途径，独立于 claude-subscription。

Gemini

支持的方式：

粘贴重定向 URL
应用内浏览器（仅限原生客户端）

GitHub

支持的方式：

输入 Token / 个人访问令牌（Personal Access Token）
已连接服务之外的本地 GitHub CLI 身份验证

连接 GitHub 令牌后，Kaiwu 可调用 GitHub REST API 执行以下操作：

将本地仓库发布至 GitHub
列出并打开当前分支的拉取请求
创建或复用拉取请求

本地 gh CLI 不会作为已连接服务存储。若已安装 gh 并通过 gh auth login 完成身份验证，Kaiwu 可将其作为 GitHub 版本控制工作流的可选备用方案。

当前 GitHub OAuth 说明：

当前构建版本未启用 GitHub OAuth / 设备代码流。
请在已连接服务中使用 GitHub 令牌，或对本地 gh CLI 进行身份验证。

GitLab 目前尚未作为 Kaiwu 的已连接服务提供。GitLab 合并请求工作流优先使用经身份验证的本地 glab CLI（若可用），或回退至免验证的比对 URL。

Web 端表现差异的原因

Kaiwu 在 Web 端不采用内嵌式 OAuth 捕获。由于浏览器环境无法可靠地自动捕获提供商向 localhost 发起的重定向，Web 端会回退至基于粘贴的流程。

后端兼容性

已连接服务并非“处处通用”的全局凭据。各个后端会明确声明自身支持的服务 ID 与凭据类型。

后端	支持的已连接服务
Claude	`claude-subscription`（setup-token 或 OAuth），`anthropic`（API 密钥）
Codex	`openai-codex`（OAuth），`openai`（API 密钥）
Gemini	`gemini`（OAuth）
OpenCode	`openai-codex`（OAuth），`openai`（API 密钥），`claude-subscription`（仅限 setup-token），`anthropic`（API 密钥）
Pi	`openai-codex`（OAuth），`openai`（API 密钥），`claude-subscription`（OAuth 或 setup-token），`anthropic`（API 密钥）

重要限制：

仅当配置为 setup-token 配置而非 Claude OAuth 配置时，OpenCode 才接受 claude-subscription。
Pi 接受 claude-subscription 的 OAuth 与 setup-token 配置。Claude 订阅 OAuth 会具象化至 Pi 隔离的 auth.json 中；setup-token 配置则具象化为 Pi 的 API 密钥凭据。
在 Kaiwu 中，anthropic 仅支持 API 密钥。
智能体后端不使用 github，该服务仅由版本控制工作流使用。

版本控制兼容性

版本控制工作流	首选凭据	回退方案
将仓库发布至 GitHub	已连接的 `github` 令牌	经身份验证的 `gh` CLI
GitHub 拉取请求	已连接的 `github` 令牌	经身份验证的 `gh` CLI，其次为比对 URL
GitLab 合并请求	目前未提供已连接服务	经身份验证的 `glab` CLI，其次为比对 URL
Bitbucket 拉取请求	目前未提供已连接服务	仅支持比对 URL

这意味着，如果用户已安装 gh 并完成身份验证，无需先在 Kaiwu 中连接 GitHub 即可直接使用 GitHub PR 与发布功能。不过，连接 GitHub 仍是跨设备场景下的首选方案，因为目标设备上的守护进程可以直接复用该凭据。

在新建会话流程中使用已连接服务

若所选后端支持已连接服务，新建会话界面将显示身份验证选择器。

该选择器是动态加载的：

仅在后端支持已连接服务时才会显示
仅展示与所选后端兼容的服务
仅展示适用于该后端的已连接配置
允许你针对每个兼容服务选择 native 身份验证或 connected 身份验证

若某服务不存在兼容的已连接配置，Kaiwu 会将该服务保留为原生身份验证，并提供打开“已连接服务”设置的快捷入口。

已连接服务与浏览会话（Codex）

对于某些提供商，已连接服务的选择会决定 Kaiwu 在浏览会话时应使用哪一个提供商“主目录（home）”。

最典型的例子是 Codex：

使用原生身份验证时，Kaiwu 会从该设备的标准 Codex 主目录中浏览会话。
为 Codex 选用已连接服务配置时，Kaiwu 则从该已连接服务对应的 Codex 主目录中浏览会话。

这一机制在以下两个场景中发挥作用：

直连 → 浏览提供商会话：浏览时可明确指定数据源/主目录。
浏览会话：选择器会锁定为新建会话选择所决定的生效 Codex 主目录，确保所选会话在该身份验证下能够正常恢复。

若需要浏览其他 Codex 主目录，请先切换身份验证选项，然后再重新浏览。

已连接服务与会话交接

在跨设备场景下，已连接服务通常是保持会话连续性最便捷的途径。

原因在于：

凭据保存在 Kaiwu 中，而非局限于单台设备的本地提供商登录信息
兼容的后端可在另一台设备上重新具象化该凭据
你可以交接同一个 Kaiwu 会话并继续执行，无需完全依赖目标设备上的原生提供商 CLI 身份验证

该特性在以下场景中尤其有用：

将会话从一台台式机/笔记本电脑迁移到另一台
在宿主机与虚拟机之间迁移会话
当仅有一侧设备此前通过应用完成设置时，仍能保持操作连续

已连接服务并不能替代所有的原生提供商登录流程。某些提供商与运行时仍依赖设备本地的身份验证。不过对于受支持的后端，已连接服务是实现跨设备连续性的首选方案。

参见：

配置、默认值与标签

每个已连接服务均可拥有多个配置，例如：

个人 OpenAI 订阅与工作 OpenAI 订阅
多个 Anthropic API 密钥
多个 Claude setup-token 配置

针对每个服务，你可以：

设置一个默认配置
在启动会话时覆盖默认配置
指定易懂的标签，使身份验证选择器展示更直观的信息，而非仅仅显示 work 或 default

账户池

账户池将同一服务的多个账户归为一组，并由系统判定当前应由哪个账户处理任务。它是解决交互轮次中途额度耗尽问题的方案：会话不必停滞等待配额重置，账户池会自动切至其他账户并继续处理。

使用账户池的所有会话共享该池。当某个会话发现当前活动账户额度耗尽时，账户池会遴选替代账户；绑定到该池的其他会话也会同步采用新账户，无需各自再去触碰同一个已失效的账户。

选择活动账户

策略	说明
受限最少 (默认)	选取剩余额度最多的成员。
优先级	按照你设定的顺序依次使用，依列表向下回退。
手动	不自动选择，完全由你自行指定。

你可以通过调整成员顺序来设定回退优先级，也可以在不移除账户的情况下单独启用或禁用特定账户。

触发切换的条件

自动切换默认处于关闭状态，需针对各个账户池单独开启。开启后，将在以下情况触发切换：

触发条件	默认状态
账户达到使用上限	开启
身份验证过期	开启
活动账户意外变更	开启
凭据刷新失败	关闭

系统还可在触及硬性上限之前提前切换：当活动账户的剩余额度低于 15% 且有更优成员可用时即可触发。该阈值支持自定义配置。

防抖限制

为了避免配置异常的账户池或反复出现的身份验证失败导致无限循环切换，切换行为受到以下约束：

单轮次内最多切换 1 次
单个会话每小时最多切换 3 次
切换之间设有 30 秒冷却时间
遵循提供商的重置时间，对于已知即将在短时间内重置额度的成员，不会将其视作永久失效

触及硬性上限后的恢复

当会话确实遇到额度上限受阻时，后续处理行为支持配置：

模式	行为
切换或等待 (默认)	切至其他账户；若无可替换账户则等待重置。
切换后继续	完成切换并立即继续。
等待直至重置	保持当前账户并等待。
关闭	暂停并交由你决定。

恢复运行时，系统可以发送 Kaiwu 的标准继续提示词、由你自定义编写的提示词，或者完全不发送任何内容。

时效性检查

在执行轮次前，若额度快照的时间已超过五分钟，系统会重新探测。默认情况下，Kaiwu 仅在快照过期时才触发探测，并优先检查当前账户，随后再检查备选成员——你也可以将其配置为每轮均探测或从不探测，并调整检查顺序。

每次切换都会作为事件记录在会话记录中，注明生效的账户及其原因。常规的低额度检测日志不会写入会话记录，以免淹没对话内容。

额度

额度 / 使用量界面受 connectedServices.quotas 特性开关控制。

当前支持查看额度快照的服务包括：

openai-codex
claude-subscription
gemini

GitHub 已连接账户目前在 Kaiwu 中不显示额度计量表。

额度信息会在以下位置展示：

“已连接服务”列表中当前生效配置上的徽标
单个配置的详情界面
新建会话时针对已连接配置的身份验证选择器

每个配置详情视图均允许你：

刷新快照
查看提供商套餐标签（若可用）
置顶特定的计量表，以便在界面的其他区域以摘要徽标的形式呈现

达到使用上限时的处理

当触及提供商的使用上限时，会话不会静默卡住。Kaiwu 会展示横幅提示，说明当前正在等待的内容以及应对操作，并显示已达上限、临时限流或准备恢复等状态。

横幅提供的操作选项取决于当前实际可行的方案：

操作	适用场景
立即检查上限	认为限制已经解除，希望立即重新探测而非继续等待。
应用重置配额	账户存在可用的用量重置额度——详见下文。
立即切换账户	账户池中有其他账户可立即接管。
立即切换到备用方案	直接切至已配置的备用方案，无需等待账户池决策。
上限重置时恢复	保持等待；限流窗口重新开启后 Kaiwu 会自动为你恢复运行。
立即重试	阻断原因为临时限流而非硬性上限。
停止等待	放弃自动恢复，由你手动处理。

选择一律等待并恢复可针对该账户记住当前决策，横幅将不再弹窗提示；选择每次都询问则会恢复每次提示。

用量重置额度

部分 Codex 账户会获得提供商发放的用量限制重置额度。若存在该额度，横幅会显示当前可用数量及下一笔额度的过期时间；点击应用重置配额即可直接在 Kaiwu 内消耗额度，无需跳转至单独的账户网页，也无需重启会话。

Kaiwu 会如实反馈实际的执行结果，而非默认操作一定成功：包括重置成功、无需重置、无剩余额度或额度已被使用等。一旦提供商重新开始接收请求，被阻断的会话便会自动继续运行。## 安全模型

对于基于 OAuth 的服务，Kaiwu 客户端不会直接向提供商用授权码换取令牌。

具体流程如下：

客户端通过设备授权、粘贴或内嵌浏览器捕获获取 OAuth 授权码
客户端调用 Kaiwu 服务端 /v2/connect/<serviceId>/oauth/exchange
服务端向提供商换取令牌
服务端使用客户端公钥加密令牌并返回加密数据包
客户端在本地解密数据包，并保存解密后的凭据记录

这样可以避免将提供商机密（包括服务端 OAuth 客户端密钥）暴露在 UI 打包产物中。

基于令牌的服务（包括 GitHub 令牌配置）会作为已连接服务的凭据进行存储，且仅在客户端或守护进程需要使用时才会解密。在当前构建版本中，这种方式无需 Kaiwu 运行单独的 GitHub OAuth 应用。

会话启动时，守护进程会在本地解密所选凭据记录，且仅实例化本次进程启动所需的特定后端认证信息。

特性门控与覆盖

已连接服务采用规范的特性门控系统。

服务端特性标志：

connectedServices
connectedServices.quotas

UI 构建门控：

EXPO_PUBLIC_Kaiwu_FEATURE_CONNECTED_SERVICES__ENABLED
EXPO_PUBLIC_Kaiwu_FEATURE_CONNECTED_SERVICES_QUOTAS__ENABLED

参见：

高级服务端配置覆盖

大多数用户无需配置这些项。它们主要用于自托管部署以及减少环境偏差。

全局服务端令牌交换超时：

Kaiwu_CONNECTED_SERVICES_OAUTH_EXCHANGE_TIMEOUT_MS

OpenAI Codex OAuth：

Kaiwu_CONNECTED_SERVICES_OPENAI_CODEX_OAUTH_CLIENT_ID
Kaiwu_CONNECTED_SERVICES_OPENAI_CODEX_OAUTH_TOKEN_URL

Gemini OAuth：

Kaiwu_CONNECTED_SERVICES_GEMINI_OAUTH_CLIENT_ID
Kaiwu_CONNECTED_SERVICES_GEMINI_OAUTH_CLIENT_SECRET
Kaiwu_CONNECTED_SERVICES_GEMINI_OAUTH_TOKEN_URL

Claude 订阅 OAuth：

Kaiwu_CONNECTED_SERVICES_CLAUDE_SUBSCRIPTION_OAUTH_CLIENT_ID
Kaiwu_CONNECTED_SERVICES_CLAUDE_SUBSCRIPTION_OAUTH_TOKEN_URL

配额获取器：

Kaiwu_CONNECTED_SERVICES_QUOTAS_STALE_AFTER_MS
Kaiwu_CONNECTED_SERVICES_QUOTAS_USER_AGENT
Kaiwu_CONNECTED_SERVICES_OPENAI_CODEX_USAGE_URL
Kaiwu_CONNECTED_SERVICES_CLAUDE_SUBSCRIPTION_USAGE_URL
Kaiwu_CONNECTED_SERVICES_ANTHROPIC_USAGE_URL

Kaiwu_CONNECTED_SERVICES_ANTHROPIC_USAGE_URL 仍可作为获取 Claude 订阅配额的回退覆盖项，但主服务标识仍为 claude-subscription。

On this page