CLI 提供方、账号与模型

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

使用剩余套餐额度可通过 ocx account use-remaining openai main on 开启，再用 ocx account use openai main 选择主账号；status --json 查看状态，off 关闭。将 main 替换为唯一的池账号 ID 或别名即可控制该账号。开启后关闭该账号按用量提前切换；主账号的短、长窗口硬锁阈值延后到 100%。开关跨重启保留，关闭后恢复原有阈值。暂停、重新认证、上游冷却和付费 credits 权限仍然生效；此开关不会开启付费额度。详见英文说明。

提供方

`ocx provider <subcommand>`

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

子命令	支持的标志	操作
`list`	`--json`, `--jsonl`	列出已配置的提供方以及剩余的注册表条目。 `--jsonl` 为每个已配置的提供方输出一行 JSON 对象。
`add <name>`	`--adapter <adapter>`, `--base-url <url>`, `--api-key <key>`, `--default-model <model>`, `--set-default`, `--force`, `--json`, `--sync`	保存到本地。`--force` 允许覆盖；`--sync` 在 JSON 和普通输出模式下均会尝试同步。
`edit <name>`	提供方字段标志，`--headers <json>`，`--json`	在不替换密钥池的情况下，编辑经过校验的在线提供方字段。`--headers` 会合并自定义请求头；传入 `{}` 或 `-` 可清空。
`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 账号的池化或直连路由。
`import-cc-switch`	`--source <FILE>`, `--provider <id>`, `--apply`, `--restore`, `--allow-private-network`, `--json`	从 CC-Switch SQLite（`cc-switch.db`）或旧版 JSON 文件预览、选择性应用或恢复无密钥提供商条目。

默认的 add、remove 和 set-default 修改本地配置。修改运行中的代理需加 --live，在线删除还需 --yes。--sync --json 同样会在保存后尝试同步；失败时保留保存结果，以非零状态退出，并返回 needsSync: true。--live 不能与 --sync 同用。pacing 和 snapshot/apply 操作见英文指南。

ocx provider list --json
ocx provider list --jsonl
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

--jsonl 仅输出已配置的提供方，每行一个 JSON 对象。每个对象的字段与 --json 输出中 configured 数组的元素相同，不包含 registryCount 汇总。脚本可以逐行处理这些对象。--json 与 --jsonl 不能同时使用。

无密钥导入 CC-Switch 提供商

ocx provider import-cc-switch --source ~/.cc-switch/cc-switch.db
ocx stop
ocx provider import-cc-switch --source ~/.cc-switch/cc-switch.db --provider my-provider --apply
# 在另一个终端启动代理（或运行 ocx ensure），再添加密钥：
ocx start
printf '%s\n' "$API_KEY" | ocx account add-key my-provider

# 独立的回滚路径（先停止代理；仅移除未修改的无密钥条目）：
ocx stop
ocx provider import-cc-switch --restore

ocx provider import-cc-switch 仅从普通本地 CC-Switch SQLite 数据库或旧版 JSON 文件中投射显式白名单内的非机密元数据字段（提供商 ID、应用类型、base URL、协议适配器与默认模型）。为扫描输入会临时读取源文件与内嵌配置字节，但密钥/凭据字段、自由文本显示名称与 TOML 注释会在字节层跳过，绝不解码为字符串、写入磁盘或记录日志，且临时字节缓冲区会在 finally 中清零。窄化 base URL 路径规则（http(s)://host[:port] 配空路径或 1–4 个小写 [a-z0-9._-] API 路径段，如 /v1、/api/v1 或 /compatible-mode/v1）与标识符/模型语法校验仅作为纵深防御并拒绝不合规值（不回显原值）。源文件通过 O_NOFOLLOW | O_NONBLOCK 描述符校验单次打开，SQLite 在内存中只读反序列化且不写入临时文件；具有多个硬链接（nlink > 1）的 SQLite 文件会被拒绝以防通过别名路径绕过伴随文件检查，若同级 -wal 或 -journal 文件非空则会拒绝导入并提示先关闭 CC-Switch（或执行数据库 checkpoint）再重试。请仅从受信任的本地 CC-Switch 源文件导入，并在添加凭据前核对输出的每个 ID、模型与 baseUrl：

预览（默认）： 需要 --source <FILE>，不写入任何内容，报告发现、可用、冲突与无效条目数量。
应用（--apply）： 需要 --source <FILE> 且代理已停止（ocx stop），在 Remote Link Child 上会被拒绝。重复指定 --provider <id> 可仅导入所选条目，传入 --allow-private-network 可允许环回或私有网络 base URL。即使未事先预览，--apply 也会在写入无密钥提供商条目及回滚日志 $OPENCODEX_HOME/cc-switch-provider-import-journal.json 之前输出每个导入提供商的 ID、默认模型与目标 URL（文本模式输出到 stdout，--json 模式输出到 stderr）；存在活动回滚日志时再次运行 --apply 会被拒绝。核对输出条目后启动代理（在另一终端运行 ocx start 或运行 ocx ensure），再通过 printf '%s\n' "$API_KEY" | ocx account add-key <provider>（管道标准输入）或 ocx login <provider> 添加凭据。
恢复（--restore）： 独立的回滚路径（而非添加凭据的后续步骤），要求代理已停止（ocx stop），在 Remote Link Child 上会被拒绝，且不接受 --source、--provider 或 --allow-private-network。它会以只读字节方式检查 auth.json（不可读或格式损坏时安全保留），仅从活动日志中移除仍保持导入时无密钥状态、未被选为 defaultProvider，且未被路由、组合（combos）、回退策略（fallback policy）、OAuth 账户或 API 密钥引用的提供商。

认证

`ocx login <provider>`

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

在 ocx status / ocx doctor 报告需要重新认证或终端刷新失败后，也可用同一条命令执行重新认证（或者在仪表盘中使用 Reauthenticate）。Codex 池账号不是上面那些 OAuth / API key 提供方，但 ocx login codex 可以到达：它会转到账号池登录，因此 ocx login codex --reauth 与 ocx account reauth codex 等价。仪表盘里的 Codex 账号池（Reauthenticate）同样可以。这条路径跑在代理内部，需要代理正在运行。

ocx login xai
ocx login anthropic

`ocx logout <provider>`

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

账号与密钥池

`ocx account <subcommand>`

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

Usage: ocx account <list|history|current|use|clear|refresh|auto-switch|alias|priority|pause|resume|pause-exhausted|strategy|sticky|remove|clear-cooldown|add-key|import|import-orca|login|reauth|code|cancel|reset-credits|grok-reset-coupons|main> ...

list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
history openai <pool-account-id> [--limit <1-200>]  Recent routing decisions for one Codex pool account.
current <provider>  Show the active account or key.
use <provider> <id|alias|main|auto> Switch the active credential; 'main' selects the Codex App login, 'auto' clears the selection unless an account carries that id.
clear <provider>  Clear the manual Codex account selection unconditionally.
refresh <provider>  Force-refresh Codex or provider quota reports.
auto-switch <provider> <on|off|status|threshold N>  Control the Codex pool threshold.
alias <provider> <id|alias> <display-name|->  Set or clear an account's display name; '-' clears it.
pause <provider> <id|alias|main>  Hold an account out of automatic selection.
resume <provider> <id|alias|main>  Return a paused account to automatic selection.
pause-exhausted <provider>  Pause every account whose quota is spent.
clear-cooldown <openai|anthropic> <id|alias|main>  Drop a cooldown the proxy set after an upstream failure.
strategy <provider> [<quota|round-robin|fill-first|reset-first>]  Pool placement strategy; omit the value to read it.
sticky <provider> [<1-100>]  Requests a bound thread keeps on one account; omit the value to read it.
priority <provider> <id|alias|main> [first|earlier|normal|later|last|-100..100|reset]  Selection order; omit the value to read it.
remove <provider> <id|alias|main> --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.
grok-reset-coupons [<id>] [--consume --yes] [--token-id <token-id>] [--operation-id <uuid>]  Inspect or redeem Grok reset coupons.
import <provider> --format <format> (--file <path>|--stdin)  Import credentials from a named external format.
import-orca --source <dir> --registry <file> [--apply]  Preview or apply imports from Orca-managed Codex homes.
main <doctor|list|register|add|reauth|switch|recover>  Manage the Codex App login the pool calls 'main'.
Codex pool selection applies to the next request after clearing existing affinity; in-flight requests keep their captured account.

除 import-orca 外，子命令都要求代理正在运行，CLI 会自动解析其记录的运行时端口；import-orca 的预览完全在本地进行，而 import-orca --apply 要求代理已停止。成功操作的退出码为 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",
  "priority": 0,
  "masked": "sk-ab****wxyz",
  "active": true,
  "needsReauth": false,
  "quota": null
}

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

即使主机上没有原生 Codex 主目录，保存的 ChatGPT 池账号仍可列出，包括在仪表盘中和刷新账号时。查询列表不会创建 Codex 主目录，也不会退出原生主账号。禁用 Codex 客户端集成不会停止观测已有原生登录的配额；显式设置的 CODEX_HOME 路径无效时，仍会报告配置错误。如果 OPENCODEX_HOME 存储不安全，即使没有原生 Codex 主目录，也会报告错误。解析默认 Codex 主目录路径时，如果该路径是文件、目标不存在的符号链接，或父目录无法遍历，也会报告错误。

不指定提供方时，会列出 Codex 池、OAuth 账号和已配置的 API 密钥池。除非提供 --all，否则会跳过空的提供方。指定提供方时，只列出该凭据家族。人类可读输出使用 PROVIDER TYPE ID PLAN/LABEL PRIORITY STATUS；手动选中的 Codex 行会标记为 selected。当存有两个或更多符合条件的 Kiro 账号时，默认情况下 429 会自动轮换到另一个账号，并优先选择已知剩余额度最多的账号；轮换由账号存在与否驱动，且无法关闭；oauthAccountFailover.enabled: false 拒绝的是发送前的账号优选，而非 429 恢复。ocx account login 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|alias|main|auto> [--json]`

auto 会清除手动选择，让 Pool 重新按自身策略分配工作 — 但如果某个 Codex 账号的 id 恰为 auto，则精确 id 匹配优先；ocx account clear <provider> 始终恢复自动选择。Codex 账号可以用 ocx account alias 设置的别名代替 id 来指定；priority、pause、resume、clear-cooldown、remove 和 alias 同样如此。对于 Codex 账号，auto、main 和 __main__ 为保留字（不区分大小写），不能设为别名。OAuth 账号和 API 密钥的显示名称仍遵循原有规则。

选择已有的 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 pause|resume anthropic <id|alias> [--json]`

CLI 命令通过 id 或唯一别名暂停或恢复 Anthropic OAuth 账户。别名先精确匹配，再进行不区分大小写的匹配。CLI 和仪表板使用同一个 PUT /api/oauth/accounts/pause，请求体为 { provider: "anthropic", accountId, paused }。paused 保存在账户中，并通过 GET /api/oauth/accounts 返回。即使主动账户池已关闭，暂停账户也会从选择、会话绑定和 429 后继候选中排除。所有账户暂停时，请求返回 403，直到恢复一个账户。已经发送的请求继续执行，凭证和健康状态保持不变。重启或重新登录仍保留暂停，删除账户时一并清除。此操作不包含账户级自动切换阈值。

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

在不解析账号 id 的情况下清除 Codex 账号的手动选择，因此即使存在名为 auto 的账号也有效。仅适用于 Codex Pool；其他提供商类型没有可恢复的自动选择。

`ocx account clear-cooldown <openai|anthropic> <id|alias|main> [--json]`

清除进程本地的失败冷却，但不更改已保存的凭据。Codex Pool 账号使用 openai，Anthropic OAuth 账号使用 anthropic；其他 provider 会被拒绝。两种形式都接受账号 id 或唯一别名，而 main 仅适用于 Codex Pool。

ocx account clear-cooldown anthropic <id-or-alias>

即使没有活动冷却，命令也会成功，JSON 中的 cleared 为 false。清除 Anthropic 冷却还会推进账号 generation，因此旧的 quota probe 无法恢复已清除的状态或发布过期的配额资格。

`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 账户池阈值，或保存通用 OAuth 账户池阈值。on 保存 80%，off 保存 0%，threshold <n> 接受 0–100。通用池的阈值只有在 pool.kernel 打开且 strategy: "fill-first" 时才参与选择；标志关闭时，保存阈值不会启用阈值切换。两种情况下都不会改变提供方启用设置或禁用 429 错误后的轮换。通用池的查询和修改结果使用服务器确认值。通用池的 poolEnabled 是已保存的提供方设置，null 表示未指定，并不代表继承后的实际状态。inert: true 表示阈值已保存但未应用，inert: false 表示账户池正在应用它。没有 inert 字段表示能力未知，此时同样不会报告 enabled: true。API 密钥提供方和无效值会被拒绝。

`ocx account auto-switch anthropic … --account <id>`

Anthropic OAuth 使用 ocx account auto-switch anthropic threshold 90 --account <id> 保存账户专属整数 0–100。off --account <id> 设为 0，on --account <id> 设为 80，inherit --account <id> 恢复继承，status --account <id> 只读查询；可加 --json。账户卡片提供相同控制。未设置/null 继承 anthropicAccountPool.autoSwitchThreshold（默认 80）；0 只禁用该账户按用量切换。设置在重启和重新登录后保留，删除账户时移除。手动选择、affinity、未知或全部耗尽时的后备行为与模型路由限制不变。池禁用时不应用阈值；暂停与 429 恢复仍有效。

openai: { provider, autoSwitchThreshold: number, enabled: boolean }
generic OAuth: { provider, autoSwitchThreshold: number | null, enabled: boolean, poolEnabled: boolean | null, inert: boolean | null }

`ocx account priority <provider> <account-id|alias|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]`

读取或设置某个 Codex pool 账号的选择顺序：数值越大越先使用，默认值为 0，范围是 -100 到 100。只有 openai 的 Codex pool 有选择顺序，其他 provider 返回退出码 1。main 指向 Codex Desktop 登录账号，它与其他 pool 账号一样参与排序：ocx account priority openai main last 就能把它留作备用。

预设词只是小整数的别名：first 为 +2，earlier 为 +1，normal 为 0，later 为 -1， last 为 -2。reset 恢复默认值并删除已保存的条目。省略取值即为读取，不会改写当前顺序。

顺序决定的是先考虑哪些账号，而不是哪些账号可用：选择仍然只在合格账号中进行，取仍有 quota 余量的最高 tier，再由 accountPoolStrategy 在该 tier 内挑选。暂停、cooldown 和重新认证都不受影响。改动从下一个未绑定请求起生效，而不仅限于新开的 session：一旦更高顺序重新有了余量，preemption 会立即把未绑定请求提上去。已绑定账号的 thread 通常会保留该账号直到其用尽；重新认证失败或 quota cooldown 仍可能更早解除绑定。连续的临时失败不再删除仍有效的线程绑定：请求会改由其他账号处理，绑定保留，该账号恢复服务后任务会回到原账号；若 10 分钟后仍在失败，绑定才会按常规解除。任何被接受的写入也会解除手动的“立即使用此账号”固定，无论固定在哪个账号上；写入与当前相同的顺序同样会解除，这是在保留当前所选账号的前提下解除固定的唯一方式（通过管理 API 清空活动账号同样会解除固定，但所选账号也一并丢失）。代理不可达、账号 id 不存在或取值不在允许范围内都会返回退出码 1。--json 返回：

{ ok: true, provider, id, priority: number, preset: string | null }

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

在无头 shell 中通过浏览器或手动代码完成账号认证。提供方对应的命令语法见 ocx account --help。即使 Codex 登录已保存，只要验证或模型目录刷新仍待完成，普通输出和 --json 都会返回退出码 1。已保存的登录信息会保留，不要仅因后续操作待完成就重新发起认证。目录刷新待完成时，普通输出会在 stderr 显示 ocx sync 指引；--json 则在可解析的 stdout 中保留状态和待完成标志，不混入提示文字。

`ocx account remove <provider> <id|alias|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, catalogRefreshPending?: boolean }
{ error: string } // stderr, exit 1

catalogRefreshPending 只出现在 Codex 删除结果中。值为 true 时，账号删除已经保存；人类可读输出会在 stderr 打印通用的 ocx sync 恢复指引，并仍以 0 退出。OAuth 账号和 API 密钥删除的响应结构不会增加此字段。

`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 account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <id>] [--operation-id <uuid>]] [--json]`

检查或兑换 xAI / Grok 账号剩余的重置优惠券。

不带 --consume 调用时，返回可用的优惠券 token 及其有效期窗口：

ocx account grok-reset-coupons
ocx account grok-reset-coupons acc_xai_01 --json

兑换重置优惠券会改变计费状态，并永久消耗一个优惠券 token。--consume 严格要求同时提供 --yes：

ocx account grok-reset-coupons --consume --yes
ocx account grok-reset-coupons --consume --yes --token-id <token-id>

传入 --operation-id <uuid>（必须是有效的 UUIDv4）可保证结算具备幂等性。当网络中断或命令重试时，相同的 operation id 会重放已持久化的结果，而不会再次消耗一个优惠券。

`ocx account main <subcommand>`

管理命名的原生 Codex 主登录配置文件，而不更改 OpenCodex 账号池路由。

ocx account main doctor [--json]
ocx account main list [--json]
ocx account main register <label> [--json]
ocx account main add <label>
ocx account main reauth --device [--no-wait] [--json]
ocx account main reauth status --flow <id> [--json]
ocx account main reauth cancel --flow <id> [--json]
ocx account main switch <profile-id-or-label> --yes [--json]
ocx account main recover [--rollback --yes] [--json]

ocx account main reauth --device --no-wait --json 成功时只向 stdout 输出一个 JSON 对象，不输出供人阅读的 follow up: 提示行。将返回的 flowId 传给 ocx account main reauth status --flow <id> --json 即可查看进度。

每个变更命令都会显示运行中代理返回的规范化有效 CODEX_HOME。该路径可能与调用进程的 CODEX_HOME 不同；支持 JSON 的命令会在 effectiveCodexHome 中返回相同的值。

版本 1 支持基于文件的 Codex 身份验证，使用 AES-256-GCM 加密保存的配置文件，并将加密密钥保存在操作系统凭据存储中。add 会先在受限暂存环境中启动官方 Codex 登录，再导入生成的凭据。切换配置文件前请关闭 Codex。切换成功后会保留本地任务和历史记录，但继续使用前必须重启 Codex。使用 doctor 检查配置文件状态，使用 recover 完成或回滚中断的切换。switch 可接受配置文件 ID 或标签。

v1 恢复矩阵覆盖的是事务文件通过重命名发布后 OpenCodex 进程退出的情况。它不声明能够在操作系统或内核崩溃、突然断电后持久保存：atomicWriteFileAsync() 不会对文件或父目录执行 fsync。

加密保管库、切换日志、恢复标记和日志隔离文件位于规范的 <real CODEX_HOME>/.opencodex-native-main-profiles 目录中。因此，共用该 Codex 主目录的所有 OpenCodex 实例都会看到同一个所有者和同一份恢复状态。明文登录暂存数据仍分别隔离在各自的 <OPENCODEX_HOME>/native-main-profile-staging 目录下。

在允许 native-main 流量或日志恢复之前，生命周期所有者会取得凭据的独占占用权，并且只删除名称与 auth.json.ocx.<pid>.<sequence>.tmp 完全匹配的崩溃残留文件。每个候选文件在整个过程中都必须位于未发生变化的规范 CODEX_HOME 下，并保持为硬链接计数为 1 的普通文件；系统会先将其截断，再刷新其内容，最后取消链接（unlink）。若发生链接或重解析点替换、文件标识发生变化或存在其他歧义，native-main 流量将继续保持关闭；名称仅近似匹配的文件绝不会被自动删除。这项防护针对正常协作的 OpenCodex 发生崩溃的情况，并不能抵御已经以同一操作系统用户身份运行的恶意进程。该用户以及承载 CODEX_HOME 的文件系统仍属于信任范围；截断文件也不保证从写时复制存储、快照或 SSD 残留数据中实现物理擦除。

预览版使用 <OPENCODEX_HOME>/native-main-profiles。该布局绝不会被静默导入。如果 doctor 报告旧版配置文件状态，请停止所有共用同一 CODEX_HOME 的 OpenCodex 代理。然后，请先备份，并在保留仅所有者可访问权限的情况下，将相应的 *.vault.json、*.journal.json、恢复标记以及任何被引用的日志隔离文件一起移动到规范目录中；或者删除旧的预览版文件集，再次运行 ocx account main register。只要仍有任何共用该 CODEX_HOME 的代理正在运行，就不要在多个旧根目录之间选择其一，也不要同时使用两种布局。在 Windows 上，按以前不区分大小写的主目录标识索引的预览状态必须重置，而不能直接移动，因为其加密 AAD 和操作系统密钥环标识被有意设计为不再复用。

模型

`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 拦截。

add 和 remove 默认保存到本地；--live 修改运行中的代理。本地 --json 保存时若无代理，返回 sync.status: "not-attempted"、needsSync: true，退出码为 0。实际尝试的同步失败时保留保存结果，以非零码退出。list-custom 是本地列表。display-name 使用原始上游 ID，order 使用 picker 的 public ID。完整排列、featured 前缀与 native 顺序重置限制见英文步骤。

子命令	支持的标志	操作
`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>`, `--live`, `--json`	在本地注册自定义模型，或使用 `--live` 在运行中的代理上注册。
`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`, `--live`, `--json`	删除自定义模型；使用 `--live` 或 `--json` 时必须加 `--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> [--set-all]\|provider <name> on [--value <tokens>]\|provider <name> off\|all <on\|off>>`	`--json`	读取或设置上下文窗口上限，可全局设置或按提供方设置。`value <tokens> --set-all` 还会把值重新应用到所有已路由提供方（等同于仪表板开关）；不加它则只改变默认值。`provider ... on --value <tokens>` 仅为该提供方设置独立上限（`--value` 仅可用于 `on`）。
`shadow <status\|set> [model\|-]`	`--enabled <on\|off>`, `--json`	读取或设置 Codex 后台辅助调用所替换的模型。`-` 会清除该模型。`status` 还会报告 `sourceModels`，即代理拦截的辅助器 slug（默认值：`gpt-6-luna`, `gpt-5.6-luna`；0.144.x 及更早客户端使用的 `gpt-5.4-mini` 可通过显式 `sourceModels` 覆盖恢复）。

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>

无密钥导入 CC-Switch 提供商

认证

ocx login <provider>

ocx logout <provider>

账号与密钥池

ocx account <subcommand>

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

ocx account current <provider> [--json]

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

ocx account pause|resume anthropic <id|alias> [--json]

ocx account clear <provider> [--json]

ocx account clear-cooldown <openai|anthropic> <id|alias|main> [--json]

ocx account refresh <provider> [--json]

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

ocx account auto-switch anthropic … --account <id>

ocx account priority <provider> <account-id|alias|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]

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

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

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

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

ocx account grok-reset-coupons [<account-id>] [--consume --yes [--token-id <id>] [--operation-id <uuid>]] [--json]

ocx account main <subcommand>

模型

ocx models [subcommand] · ocx model <subcommand>