CLI 参考

opencodex 的 CLI 是 ocx。它会根据第一个命令名进行分发；文档中列出的别名，例如 setup/init、restore/eject 以及 models/model，都会到达同一操作。未知命令和无效的命令形状都视为错误。

运行 ocx help（或 ocx --help / ocx -h）查看顶层用法。运行 ocx help <command>、ocx <command> --help 或 ocx <command> -h，可查看在帮助表中注册的命令。帮助和版本命令都是只读的：它们不会启动、停止、安装、卸载或改写 Codex 或 opencodex 状态。

命令族

• 生命周期 —— 设置、代理和服务生命周期、健康检查、诊断、目录同步、仪表盘和更新。
• 提供商、账号与模型 —— 提供商配置、认证、凭据池、配额、自定义模型、可见性、已选模型和上下文上限。
• 代理、路由与集成 —— 多代理控制、组合、可观测性、准入密钥、客户端集成、运行时设置、已验证配置，以及只读的 Codex CLI 更新检查。

无头行为

管理命令会通过实时代理的管理 API 往返调用，使用记录下来的运行时端口和身份检查，而不是维护第二条配置路径。已停止或不可达的代理会被表示为 HTTP 503，并导致 CLI 以非零状态退出。明确标注为离线配置操作的命令，则可以在没有实时代理的情况下验证并编辑配置文件。

ocx system codex-cli-update check 不需要实时代理，也不会向软件包注册表发起请求。它只会在限定范围内检查已配置候选项的来源元数据，包括经过脱敏的可执行文件位置和所有权证据。受信任的已发布启动器上下文只能验证该候选项快照，并不证明 Codex 已成功运行。由于这条一次性检查命令绝不会运行 Codex，来自环境变量和持久化记录的候选项仅用于报告（managed: false，通常为 selection_unattested）；JSON 输出包含 candidateAvailable、candidateVersion 和 candidateSource，且 selectionAttested 始终为 false。检查已配置候选项需要受信任的已发布启动器上下文；直接使用 Bun 启动或从源码运行时没有这项证明，因此会忽略环境变量和持久化记录中的候选项状态，并可能报告 candidate_unavailable。在 Windows 上，这个首个切片不会对候选路径或配置路径执行任何文件系统 I/O。只有由受信任启动器捕获的绝对环境候选项可以获得应用捆绑或版本管理器的纯词法标签；其他所有 Windows 候选项都会以失败关闭方式处理。该命令不会安装或修复软件，不会运行 Codex 或 npm，不会控制正在运行的进程，也不会写入配置或缓存状态。

在语义明确时，默认操作是 list 或 status。使用 --json 获取结构化快照，使用 ocx observe logs --follow --jsonl 获取流式请求日志。主题、语言、导航以及其他纯视觉浏览器状态都没有 CLI 对应项；Cloudflare Tunnel 的设置不在这组命令之内。

退出码与确认

成功的命令退出码为 0。无效用法、未知命令或资源、API 操作失败，以及必需服务不可用时，退出码都非零。ocx health 只有在代理健康时才以 0 退出，否则以 1 退出，因此可作为服务探针。脚本应检查退出码，而不是解析人类可读输出。

声明需要确认的破坏性删除、导入、额度消耗和更新操作，在非交互用法中都要求 --yes。该标志是显式选择加入；省略它时，绝不能在静默情况下确认该操作。

版本与内部分发目标

ocx --version、ocx -v 和 ocx version 会打印一行适合脚本读取的版本信息并退出。

有两个分发目标会刻意不出现在普通帮助中：__refresh-version [preview] 会在分离进程中刷新更新通知缓存，而 __gui-update-worker <job-id> [latest|preview] [restart] 会运行一个仪表盘更新任务。它们是实现细节，不是稳定的面向用户命令。仪表盘会记录 worker PID，恢复 worker 已死亡但仍处于活动状态的任务，把更早的、没有 PID 的活动记录在十分钟后视为过期，并保护存活的 worker 不受并发更新影响。