企业官网建设流程全解析

如何使用codex-auth的--json API搭建自己的GUI账号切换器？完整参考文档

【免费下载链接】codex-authA CLI tool to switch and manage Codex accounts项目地址: https://gitcode.com/gh_mirrors/co/codex-auth

如果你正在给 Codex 多账号工作流加一个图形界面，codex-auth的--jsonAPI 就是官方给出的集成入口：它为 GUI 和自动化脚本提供了一套带版本号的 JSON 契约，codex-auth本身则是一个专门用来切换和管理 Codex 账号的命令行工具。本文带你从零跑通三个核心命令，读懂返回结构与错误处理规则，照着做就能搭出一个稳定可靠的 GUI 账号切换器。

一、--json API 是什么：一条 stdout，一份 JSON

整套 JSON 契约的核心约定只有几条，但每一条都直接决定 GUI 的稳定性（完整契约见 docs/json-api.md）：

• stdout 永远只有一份 JSON 文档，后面跟一个换行；所有诊断、警告都走stderr，绝不混进 JSON；
• 每个文档都带"schema_version": 1，客户端应忽略未知字段、对未知错误码和枚举值使用通用兜底逻辑；
• GUI 应串行调用命令，每次只读一份 JSON，不要用 stderr 里的警告文本做程序逻辑。

退出码约定如下，你的 GUI 必须同时判断"退出码 + JSON 内容"：

二、快速安装与首次调用

安装只需一条命令：

npm install -g @loongphy/codex-auth

不想全局安装时，也可以用npx @loongphy/codex-auth list临时运行。

安装后先用"冒烟命令"验证 JSON 通道是否打通：

codex-auth list --json

此时你会收到类似这样的文档（字段可能因账号而异）：

{ "schema_version": 1, "command": "list", "active_account_key": "user-abc::account-123", "accounts": [] }

如果 stdout 是纯 JSON、stderr 只有警告，说明集成环境没问题，可以继续往下走。🚀

三、三个核心命令：GUI 切换器的全部积木

--json目前支持以下四个变体（交互式与 live 模式不支持）：

codex-auth list [--api|--skip-api] [--active] --json codex-auth switch <query> --json codex-auth remove <selector> [<selector>...] --json codex-auth remove --all --json

下面逐个看返回结构。

3.1 codex-auth list --json：拉取账号列表

这是 GUI 主界面的数据源。accounts数组的顺序和行号与终端表格完全一致，active_account_key告诉你当前激活的是哪个账号（详情见 docs/commands/list.md）。

• 默认模式会做前台的用量/账号名 API 刷新；
• 加--active则只刷新激活账号的用量，其余行用本地缓存快照，适合做轮询刷新；
• 加--skip-api完全禁止远程调用，界面刷新最快、最安全。

3.2 codex-auth switch --json：无交互切换

{ "schema_version": 1, "command": "switch", "switched_to": {} }

switched_to里就是完整账号对象，其中plan已被 CLI 归一化为最终产品套餐（如business、enterprise），GUI 无需重复做任何映射。

注意两点（详见 docs/commands/switch.md）：

• <query>支持行号、别名片段、邮箱片段、账号名片段；
• --json模式下永远不会弹交互式选择器，查询有歧义时直接返回带候选账号列表的 JSON 错误，GUI 应把它渲染成一个候选列表让用户二次点选。

3.3 codex-auth remove --json：原子化删除

{ "schema_version": 1, "command": "remove", "removed": [], "new_active_account_key": null }

JSON 模式下的删除是逻辑原子操作：所有选择器先解析、后删除，任何一个选择器缺失或有歧义，就一个账号都不会被删，并返回包含全部解析结果的错误文档（详见 docs/commands/remove.md）。删除激活账号后，new_active_account_key会告诉你的 GUI 哪个账号被自动提升为新的激活账号。

四、账号对象字段指南：认准 account_key

list/switch返回的账号对象是 GUI 列表渲染的核心，关键字段如下：

其中usage把"可展示快照"和"本次刷新结果"分开了：刷新失败时旧快照字段依然保留，usage.source标明数据来源（api/local/cache/none），usage.refresh.status只描述本次调用是否刷新成功。这样设计的好处是——刷新挂了，界面也不会白屏。💪

五、错误处理：GUI 必须接住的七种情况

所有错误文档都是同一形状：

{ "schema_version": 1, "error": { "code": "account_not_found", "message": "no account matches \"work\"" } }

state_uncertain是最容易被忽视的坑：遇到它时 GUI 不要盲目重试删除/切换，先拉一次列表恢复界面真实状态。

六、开发 GUI 的 5 条黄金实践

1. 串行调用：一次只发一个命令，等 JSON 读完整；
2. 只信 stdout 的 JSON：stderr 只用于日志面板展示，不用于逻辑判断；
3. 持久化account_key，绝不持久化number；
4. 向前兼容：忽略未知字段，未知错误码按通用失败处理（schema 1 内新增字段/错误码不视为破坏性变更）；
5. 歧义即列表：ambiguous_query和selector_resolution_failed都是把"二次选择权"交还给用户的信号，别直接弹报错框。

七、延伸阅读

• JSON 契约全文：docs/json-api.md
• 命令参考总目录：docs/commands/README.md
• 项目总览与 JSON GUI 说明：README.md

想从源码层面理解 JSON 输出怎么生成，可以看 src/cli/json_output.zig；需要参与贡献时，克隆仓库：

git clone https://gitcode.com/gh_mirrors/co/codex-auth

掌握以上契约后，一个账号列表页、一个点击即切换的按钮、一个带二次确认的删除流程，就是你 GUI 切换器的全部骨架——剩下的，只是界面美化了。✨

【免费下载链接】codex-authA CLI tool to switch and manage Codex accounts项目地址: https://gitcode.com/gh_mirrors/co/codex-auth