API 密钥与模型账户

ORG-2 不转售推理。每一次模型调用都由你自己接入的账户付费：可以是你粘贴进来的服务商 API 密钥，也可以是你已经拥有的智能体 CLI 订阅，比如 Claude Code、Codex 或 Cursor。两者放在同一个位置、保存在你自己的机器上，并按会话选择。本页覆盖 ORG-2 认识的每一个服务商、每个服务商需要填的字段，以及密钥保存之后会发生什么。

密钥在应用里的位置

打开 设置 → 模型 & Keys。页面标题是 模型 & CLI，它自己的帮助文字说得很清楚：「添加 API 密钥并配置 CLI 工具。密钥仅保存在本机，不会离开您的设备。」

顶部横排着三个标签页：

• 模型 —— 你已接入的账户暴露出来的全部模型，每个模型带一个开关。
• 我的 Keys —— 账户本身。添加账户 会启动向导。
• 模型百科 —— 一份模型参考目录，与你接入了什么无关。

另有一个 CLI 客户端 视图，逐个列出智能体 CLI：是否 已安装、密钥 状态（已配置 / 未配置）、安装方式，以及它的安装与卸载脚本。添加 Agent 启动的是同一个向导，只是预先过滤到了 CLI。On prem 视图负责本地运行时。

为模型付费的两种方式

ORG-2 把 API Key 账户和订阅账户区分开，在每一行账户上以认证方式显示：

• API Key —— 你粘贴进来的一段密钥。ORG-2 用它直接调用服务商的 HTTP API。ORG-2 自带的 Rust 智能体可以用它，外部 CLI 在支持的情况下也可以用。
• OAuth —— 你登录一个已有的套餐，ORG-2 把拿到的 token 存在本地。认证方式 字段会写明具体是哪种变体：OAuth（ChatGPT 登录）、OAuth (Session Capture)、OAuth (GitHub PAT)、OAuth (AWS SSO)。

区别在于计费方式和适用范围。API 密钥由服务商按 token 计量。订阅则复用你已经在付费的套餐——例如用 Claude Code 登录，会保存一个 claude_code OAuth 账户，ORG-2 自带的 Rust 智能体可以通过原生 Anthropic 协议使用它，而不只是调用 claude 这个二进制文件。对于会上报这些数据的服务商，配额信息 面板会显示套餐、已使用、限额和重置日期。

支持的模型服务商

每个 API 服务商都有一个默认端点、一个约定俗成的环境变量名（在向导里显示为 环境变量：）和一种传输协议。它们全都接受自定义 base URL。

两个 Azure 条目没有默认端点——你要自己填资源 URL（AZURE_OPENAI_ENDPOINT / AZURE_ANTHROPIC_ENDPOINT），并在 Deployment Model 下填入你的部署名称。

支持的智能体 CLI

「兼容的 API 密钥」这一列，就是 CLI 那一行的 兼容的 API Key 区块所列的内容：只要你持有它自己的订阅账户，或者持有其中任一服务商的密钥，这个 CLI 就算已配置。

添加一个 API 密钥

1. 进入 设置 → 模型 & Keys → 我的 Keys，点 添加账户。
2. 选择 模型供应商。账户名称 可以不填——留空则使用服务商名称，之后依次是 Provider-1、Provider-2，以此类推。重名会被拒绝。
3. 把密钥粘贴到 API Key（「用于向 API 服务商发送请求的密钥」）。
4. Base URL 保持在 官方 URL，除非你要走代理（见下文）。
5. 点 验证。成功后你会看到 「检测到 {n} 个模型 — 在下一步中配置」，或者 「Key 验证成功 — 未自动检测到模型，请在下方手动添加模型」。
6. 在表格里启用你要用的模型，然后点 完成。

如果自动检测什么也没找到——用代理时很常见，因为它们往往没有实现 /v1/models——就会出现一张 Manual Models（手动模型）表格，你在其中把标准名称映射到代理期望的模型别名。添加自定义模型 则可以添加任意 id，显示名称和图标是选填的。

添加一个 CLI 订阅

切到 CLI 客户端，点 添加 Agent，然后选择 CLI。设置方式 这一步会给出下面这些选项的一个子集：

• 登录 —— 在应用内走一遍浏览器流程。使用 Claude Code 登录、使用 Codex 登录（ChatGPT Plus/Pro）和 Sign in with Gemini 都会接住回调，并把 OAuth token 存在本地。Cursor 走的是配合内置浏览器的 引导式设置，之后还需要一个在 Cursor 控制台里生成的 User API Key。
• 自动检测 —— 「扫描本地配置文件和环境变量」。Codex 读 ~/.codex/auth.json 和 OPENAI_API_KEY；Gemini 读 ~/.gemini/oauth_creds.json 和 GEMINI_API_KEY；Anthropic 的检测会先看 ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN，再看 ~/.claude.json、~/.claude/config.json、~/.config/claude/config.json、~/.config/anthropic/config.json，最后看 ~/.zshrc、~/.bashrc、~/.bash_profile、~/.profile；Cursor 读它的 state.vscdb；Kiro 读 kiro-cli 的本地存储。如果找到了好几个，你会看到一个 发现多个密钥 选择器。
• 输入 Key / 输入 Token —— 直接粘贴。GitHub Copilot 需要一个以 github_pat_ 开头、并且启用了 Copilot Chat、Editor Context 和 Requests 的 PAT。
• 提取配置 —— 粘贴一段杂乱的文本（配置文件、聊天消息都行），让 ORG-2 从里面把密钥和 base URL 解析出来。

环境变量只是检测来源，不是运行时的兜底。一旦保存，ORG-2 始终读取已存储的账户；它不会在开会话时悄悄取用你 shell 里的 OPENAI_API_KEY。而当它启动外部 CLI 时，会把存储的值再注入回该 CLI 自己的变量——ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL、OPENAI_API_KEY / OPENAI_BASE_URL、GEMINI_API_KEY / GOOGLE_GEMINI_BASE_URL、CURSOR_API_KEY、GH_TOKEN、KIRO_API_KEY、MOONSHOT_API_KEY / MOONSHOT_BASE_URL。

自定义 base URL、代理与本地模型

点 添加自定义 Base URL（选填），把 官方 URL 切换成 自定义 URL。应用会给出一条警告，这条警告值得再说一遍：

警告： 使用自定义 Base URL 可能将您的 API 密钥和数据暴露给第三方服务器。仅在使用可信代理、自建部署或已知安全端点时使用。

要做本地推理，请用 vLLM / Local 这个服务商，它会打开 本地模型 Cookbook：选一个运行时预设 —— Ollama（端口 11434）、LM Studio（端口 1234）、vLLM（端口 8000）、llama.cpp（端口 8080）或自定义 —— 端点和起步用的模型 id 会自动帮你填好。大多数本地运行时接受任意非空的 API 密钥，所以除非你的服务器强制要求，保留占位值即可。先启动运行时再验证；也可以手动填进模型 id，不验证直接保存。

密钥是全局的，账户是按会话选的

每个安装只有一份密钥存储。密钥不按仓库、工作区或智能体划分——你添加的账户在任何地方都看得到。变化的是某一次运行用哪个账户：

• 按会话。 模型选择器的布局是左边模型、右边账户，所以选完模型，再选为它付费的那把密钥。它会显示 选择密钥 或 无兼容密钥。
• 按智能体。 智能体定义里带着一个首选账户和一个首选模型（外加一个可选的、更快的摘要模型），这些在智能体自己的设置里配置，不在这里。
• 按模型。 每个账户暴露一组模型，你可以逐个启用或禁用，另外还有一个总开关 启用密钥。被禁用的账户什么也不提供，哪怕有东西明确指向它。

存储，以及密钥会不会离开你的机器

账户写入 ~/.orgii/credentials.json（可以用 ORGII_HOME 环境变量改位置）。这个文件是原子写入的——先写临时文件、设好权限、再重命名——在 macOS 和 Linux 上最终是 0600 模式，在 Windows 上则是一份受限 ACL。

警告： 密钥以明文 JSON 保存。ORG-2 不使用操作系统钥匙串、Windows 凭据管理器或 Linux Secret Service，也不对这个文件做静态加密。文件权限是唯一的保护，因此任何以你的身份运行的进程都能读到它。参见安全与隐私。

密钥用于从你的机器直接调用你的服务商。它们不经过 ORG-2 代理，也绝不会被纳入云同步。显示时只保留首尾各四个字符，其余打码。

轮换、停用与移除

密钥没法就地修改。编辑账户 只能改名字和描述，界面上也写明了这一点：「如需更新 API Key、密钥或服务商设置，请删除此账户并重新添加」。要轮换，就先添加新账户、确认它验证通过，再移除旧的。

• 重新验证 —— 「检查此密钥是否恢复正常」，用在你已经在上游修好了某个问题之后。
• 启用密钥 —— 一个总开关，可以把账户搁置起来而不删除它。
• 移除本地 —— 删除本地保存的密钥；如果还有活跃会话在用它，确认框会提示你，因为这些会话在下一轮就会失败。

认证问题排查

「密钥无效」/「已暂停 - API Key 验证失败」。 服务商返回 401 或 403 就会把账户标记为无效。去服务商那边重新核对密钥，然后添加一个新账户。健康状态按密钥跟踪，取值为 有效、降级、无效 或 未知，那一行还会显示最后一次验证的错误。

一部分模型失败，另一部分正常。 这是密钥降级状态——「{n} 个模型不可用。仅 {m} 个模型正常工作。」把出问题的模型禁用掉，或者重新跑一次 自动检测。

OAuth 订阅突然不好使了。 token 会自动刷新。刷新遇到临时性失败时，账户会退避大约五分钟；永久性失败（invalid_grant、refresh token 过期或被吊销）在连续三次之后会停用该账户。重新走一遍登录流程即可。服务商故障会把密钥搁置最多 30 分钟；触发限流则会记下一个重置时间。

密钥有效，却检测不到模型。 多半是你的端点没有实现列举模型的接口。手动把模型添上就行——密钥本身没问题。

企业代理或 TLS 拦截。 自定义 base URL 会把你的密钥发给那台主机，所以只指向你信任的目标。网络层面的问题——代理、VPN、HTTP 版本——见故障排查。

区域提示。 ORG-2 会检测你所在的区域，并可能显示 「{provider} 可能在您检测到的区域不可用。」 设置仍可继续，只是有些模型可能不会列出来。

下一步

• 智能体 —— 哪个智能体用哪个账户，以及 ORG-2 如何驱动外部 CLI。
• 会话 —— 开始干活时怎么选模型和账户。
• 安全与隐私 —— 磁盘上有什么、传输了什么。
• 故障排查 —— 逐个症状的修复办法。