CLI 提供方、账号与模型

这些命令用于配置上游提供方、认证账号、管理凭据池，并控制暴露给 Codex 的模型目录。

提供方

`ocx provider <subcommand>`

非交互式提供方管理。注册表条目按名称预置；自定义名称必须同时提供 --adapter 和 --base-url。

子命令	支持的标志	操作
`list`	`--json`	列出已配置的提供方以及剩余的注册表条目。
`add <name>`	`--adapter <adapter>`, `--base-url <url>`, `--api-key <key>`, `--default-model <model>`, `--set-default`, `--force`, `--json`, `--sync`	添加一个注册表/自定义提供方。`--force` 会覆盖；`--sync` 会在有人类输出模式运行的代理上刷新配置。
`edit <name>`	提供方字段标志，`--json`	在不替换密钥池的情况下，编辑经过校验的在线提供方字段。
`test <name>`	`--json`	探测真实的上游模型端点。
`show <name>`	`--json`	显示已屏蔽 API 密钥的配置。
`remove <name>`	`--json`	移除一个非默认提供方；最后一个提供方不能被移除。
`set-default <name>`	`--json`	将现有提供方设为默认提供方。
`selected <name>`	`--set <ids>`, `--clear`, `--json`	读取或更新提供方模型允许列表。
`quota`	`--refresh`, `--json`	读取提供方配额报告。
`presets`	`--json`	列出仪表盘提供方预设。
`account-mode`	`pool`, `direct`, `--json`	选择 Codex 账号的池化或直连路由。

ocx provider list --json
ocx provider test ark
ocx provider add anthropic --api-key sk-ant-... --set-default --sync
ocx provider add local-dev --adapter openai-chat --base-url http://localhost:11434/v1
ocx provider show anthropic --json
ocx models --provider anthropic --json
ocx models live --provider ark --json

认证

`ocx login <provider>`

启动该提供方已注册的登录流程。OAuth 提供方会打开浏览器，并将自动刷新的凭据存储在 ~/.opencodex/ 下；API 密钥登录提供方会打开其密钥控制台，提示输入密钥，在可行时进行校验，并保存生成的提供方配置。当名称缺失或未知时，命令会打印当前可接受的 OAuth 和 API 密钥提供方 id。

在 ocx status / ocx doctor 报告需要重新认证或终端刷新失败后，也可用同一条命令执行重新认证（或者在仪表盘中使用 Reauthenticate）。Codex 池账号不是一个公开的 ocx login 提供方 - 请通过仪表盘里的 Codex 账号池（Reauthenticate）或无头模式的 ocx account reauth 流程重新认证。

ocx login xai
ocx login anthropic

`ocx logout <provider>`

移除某个提供方已存储的 OAuth 凭据。

账号与密钥池

`ocx account <subcommand>`

通过正在运行的代理列出并切换提供方账号和 API 密钥池。随附的帮助输出如下：

Usage: ocx account <list|current|use|refresh|auto-switch|login|reauth|code|cancel|remove|add-key|reset-credits> ...

list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
current <provider>  Show the active account or key.
use <provider> <id> Switch the active credential; 'main' selects the Codex App login.
refresh <provider>  Force-refresh Codex or provider quota reports.
auto-switch <provider> <on|off|status|threshold N>  Control the Codex pool threshold.
remove <provider> <id> --yes  Remove a stored account or key after an existence check.
add-key <provider> [--label <label>]  Add a key read only from piped stdin.
login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.
reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.
Codex pool selection applies to the next request after clearing existing affinity; in-flight requests keep their captured account.

所有子命令都要求代理正在运行；CLI 会自动解析其记录的运行时端口。成功操作的退出码为 0。无效用法、未知的提供方或账号/密钥 id、无法访问的代理，或 API 失败都会以 1 退出。凭据字段会严格按管理 API 返回的样子显示（包括其屏蔽格式）；原始 API 密钥和 OAuth token 永远不会返回。显示上的便利字段都像仪表盘一样在客户端侧合成：main 是 openai 账号池中 Codex App 登录的 CLI 别名，没有邮箱的 OAuth 账号会显示为 Account N，而 plan/label 列会在 plan、屏蔽后的邮箱、label 和屏蔽后的密钥之间回退。

--json 账号行使用以下通用结构（不可用时会省略可选字段）：

{
  "provider": "openai",
  "type": "codex | oauth | api-key",
  "id": "__main__",
  "label": "plus",
  "email": "m***@example.com",
  "plan": "plus",
  "masked": "sk-ab****wxyz",
  "active": true,
  "needsReauth": false,
  "quota": null
}

`ocx account list [provider] [--json] [--all]`

不指定提供方时，会列出 Codex 池、OAuth 账号和已配置的 API 密钥池。除非提供 --all，否则会跳过空的提供方。指定提供方时，只列出该凭据家族。人类可读输出使用 PROVIDER TYPE ID PLAN/LABEL STATUS；手动选中的 Codex 行会标记为 selected。当存在已存储的 Kiro 账号时，输出会提示 Kiro 只有一个登录槽位，并且再次登录会替换当前账号。空结果仍然算成功。--json 返回：

{ accounts: AccountRow[], notes: string[] }

`ocx account current <provider> [--json]`

显示当前活动账号或密钥。没有手动固定的 Codex 池会报告自动选择最低使用量的结果；没有活动凭据的其他家族会报告该状态，但仍然以 0 退出。--json 返回：

{ provider, type, activeId: string | null, autoSwitchThreshold?: number, account: AccountRow | null }

`ocx account use <provider> <account-or-key-id|main> [--json]`

选择已有的 Codex 账号、OAuth 账号或 API key。对 openai 而言，main 选择 Codex App 登录。 Codex Pool 选择会清除进程本地 affinity，并从下一次请求开始生效，包括已有可见任务的请求；代理重启或 affinity eviction 后，任务也可能变为未绑定，但进行中的请求保留已捕获账号。此选择只控制 Pool routing；Direct mode 继续使用 caller-owned/native main credential。基于用量的主动切换、401/403 重新认证、429/retry-after cooldown、排除，以及输出前 429/402 故障恢复之后仍可能选择其他合格 Pool 账号。这些恢复路径在关闭基于用量的切换时仍然有效。账号变化后 OpenCodex 会重放对话上下文，但 provider prompt cache 可能需要重新预热。未知 provider 或 id 返回退出码 1。--json 返回：遇到 401/403 时，App 登录会清除该账户的进程内 affinity 并要求重新认证。遇到 429 时，它会遵循 Retry-After、启动账户 cooldown、清除 affinity，并可将请求切换到另一个符合条件的 Pool 账户。即使 autoSwitchThreshold: 0，这些故障恢复流程仍然有效；0 只会禁用基于用量的主动切换。

{ ok: true, provider, type, activeId }

`ocx account refresh <provider> [--json]`

对于 Codex 池，请使用 ocx account refresh openai [--json]。它会强制刷新账号配额，并打印可用的周/月百分比和重置时间；缺失的配额数据会报告为未知，而不是 0%。其 JSON 外壳是 { accounts: AccountRow[] }，每个 Codex 行上都会带有 quota。

对于 OAuth 和 API 密钥提供方，这会强制刷新提供方的配额报告端点；它不是重新登录 token，也不是简单重读账号列表。--json 返回 { provider, report: ProviderQuotaReport | null }。不支持配额报告的提供方会打印 no quota report available for <provider> 并以 0 退出。未知提供方和管理 API 失败会以 1 退出；上游配额探测如果失败或超时，则会降级为 null 或陈旧报告（以 0 退出），与仪表盘的配额条保持一致。

`ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]`

只控制 openai 的 Codex 账号池。on 会设为 80%，off 会设为 0%，status 会读取当前值，而 threshold <n> 接受 0 到 100 之间的整数。其他提供方和无效值都会以 1 退出。--json 返回：

{ provider, autoSwitchThreshold: number, enabled: boolean }

`ocx account login|reauth|code|cancel ...`

在无头 shell 中运行基于浏览器或手动代码的账号认证。请使用 ocx account --help 查看与提供方相关的命令形式。

`ocx account remove <provider> <id|main> --yes [--json]`

这个受保护的非交互式删除需要 --yes。删除前，它会验证 id 是否存在；缺失的 id 会以 1 退出，而不会发送 DELETE。主 Codex App 登录不能被移除，因此会拒绝 remove openai main --yes。删除后会重新读取该家族：移除已固定的 Codex 账号会清除固定并回到自动选择；OAuth 会提升第一个剩余账号，或者报告不存在；API 密钥池会提升第一个剩余密钥，或者报告不存在。--json 的成功和失败结构如下：

{ ok: true, provider, id, removedActive: boolean, promotedActiveId: string | null }
{ error: string } // stderr, exit 1

`ocx account add-key <provider> [--label <label>] [--json]`

为 API 密钥提供方添加并激活一个密钥。该密钥只会从非 TTY 的管道/重定向 stdin 读取；交互式 TTY 输入、空输入、OAuth/Codex 提供方，以及 API 失败都会以 1 退出。密钥永远不会回显，即使它出现在 label 里也是如此。建议使用秘密管理器或 here-string：

ocx account add-key openrouter --label personal <<< "$OPENROUTER_API_KEY"
security find-generic-password -w openrouter | ocx account add-key openrouter --json

--json 返回 { ok: true, id: string | null, label?: string }，并且绝不会包含该密钥。

`ocx account reset-credits <id|main> [--consume --yes]`

查看某个账号的 Codex 重置额度。消耗额度会造成破坏性影响，因此同时需要 --consume 和 --yes。

模型

`ocx models [subcommand]` · `ocx model <subcommand>`

ocx model 是 ocx models 的别名。没有子命令时，列出已配置提供方中静态预置的模型。 --provider 可过滤单个已配置提供方，而 --json 会返回模型元数据。live 读取运行中的目录；add、edit、remove 和 list-custom 管理手动目录条目；enable、 disable 和 provider 控制可见性；selected 控制提供方允许列表；context 控制提供方上下文上限；shadow 管理后台 shadow-call 拦截。

这里提供仪表盘中所有逐模型操作，因此无头安装永远不需要 GUI 来管理目录。add、 remove 和 list-custom 针对配置文件工作，并通过目录同步应用到正在运行的代理；其余命令会与在线管理 API 通信，并要求代理正在运行（ocx start，或已安装的服务）。

子命令	支持的标志	操作
`list` (默认)	`--provider <name>`, `--json`	列出已配置提供方中预置的模型。
`live`	`--provider <name>`, `--json`	读取运行中的目录，包括运行时发现的模型。各行会标记为 `native`/`routed`、`custom`，以及 `enabled`/`disabled`。
`add <provider> <modelId>`	`--display-name <name>`, `--context-window <tokens>`, `--modalities <text,image,audio>`	注册一个提供方目录未公布的模型。
`edit <custom-id>`	`--model-id <id>`, `--display-name <name\|->`, `--context-window <tokens\|0>`, `--modalities <text,image,audio\|->`, `--json`	编辑自定义模型。`-` 会清空字段；`0` 会清空上下文窗口。
`remove <custom-id\|provider/modelId>`	`--yes`	删除一个自定义模型。当 stdin 不是交互式终端时，必须提供 `--yes`。
`list-custom`	`--json`	显示所有自定义模型，以及其他子命令所使用的 `custom-id`。
`enable <provider/model\|native-model>`	`--native`, `--json`	让一个模型对 Codex 可见。
`disable <provider/model\|native-model>`	`--native`, `--json`	对 Codex 隐藏一个模型。
`provider <name> <on\|off>`	`--json`	一次写入中启用或禁用某个提供方的全部模型。
`selected <provider>`	`--set <id,id...>`, `--clear`, `--json`	读取或替换提供方模型允许列表。`--clear` 会移除允许列表，使所有模型都可提供。
`context <status\|value <tokens>\|provider <name> <on\|off>\|all <on\|off>>`	`--json`	读取或设置上下文窗口上限，可全局设置或按提供方设置。
`shadow <status\|set> [model\|-]`	`--enabled <on\|off>`, `--json`	读取或设置 Codex 后台辅助调用所替换的模型。`-` 会清除该模型。`status` 还会报告 `sourceModels`，即代理拦截的辅助器 slug（默认值：`gpt-5.4-mini` 和 `gpt-5.6-luna`）。

ocx models live --json                                  # what Codex can actually see right now
ocx models disable anthropic/claude-haiku-4             # hide one routed model
ocx models enable gpt-5.6-sol                           # no slash, so it is treated as native
ocx models provider zenmux off                          # hide a noisy provider wholesale
ocx models selected anthropic --set claude-opus-5,claude-fable-5
ocx models selected anthropic --clear                   # drop the allowlist again
ocx models add deepseek deepseek-v4 --display-name 'DeepSeek V4' --context-window 128000 --modalities text,image
ocx models list-custom --json                           # read the custom-id for edit/remove
ocx models remove deepseek/deepseek-v4 --yes

带斜杠的模型选择器会按 routed 处理（anthropic/claude-opus-5）；裸 id 会被视为 native 的 OpenAI 模型，因此只有当某个 id 本来会被看成 routed 时，才需要 --native 来强制按这种方式解释。

--modalities 只接受 text、image 和 audio。Codex 会把该字段解析为封闭枚举，并拒绝任何包含其他值的完整目录，因此 add、edit 和管理 API 都会直接拒绝这个错误值，而不会存下一个目录写入器之后还得再剥离的内容（#759）。

CLI 提供方、账号与模型

提供方

ocx provider <subcommand>

认证

ocx login <provider>

ocx logout <provider>

账号与密钥池

ocx account <subcommand>

ocx account list [provider] [--json] [--all]

ocx account current <provider> [--json]

ocx account use <provider> <account-or-key-id|main> [--json]

ocx account refresh <provider> [--json]

ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]

ocx account login|reauth|code|cancel ...

ocx account remove <provider> <id|main> --yes [--json]

ocx account add-key <provider> [--label <label>] [--json]

ocx account reset-credits <id|main> [--consume --yes]

模型

ocx models [subcommand] · ocx model <subcommand>