Codex 多账号切换教程：用 codex-account-switcher 管理本地登录

如果你在同一台 Mac 上使用多个 Codex 账号，最容易打断节奏的，往往是反复退出、重新登录，以及切换后重新确认项目和当前身份。

codex-account-switcher 提供了一种更集中的管理方式：先保存各账号已经完成登录的本地凭据，再从终端菜单中选择要使用的账号。它保留共享本地状态，不需要为每个账号整包替换 Codex 数据目录。

这篇教程以 macOS 为主，按“安装工具 → 保存账号 → 添加账号 → 日常切换 → 排查问题”的顺序说明。第一次配好以后，日常主要就是选择账号，并核对切换结果。

阅读前先确认：这是第三方开源工具，本文依据 0.1.5 版本进行真实多账号桌面切换实测。

一、它解决什么问题，适合什么人？

它适合在同一台电脑上管理自己有权使用的多个账号，例如在个人用途和另一套工作安排之间切换。每个账号第一次加入时，都要通过官方流程完成登录；工具保存的是登录之后产生的本地状态。

操作方式很直观：给账号取一个容易辨认的保存名，例如 personal 和 work，之后在列表里选中目标即可。这里的保存名只是本机标签，不会修改账号邮箱，也不是 Codex 模型配置里的 profile。

切换账号也不会合并账号订阅、转移额度或改变套餐权限。使用前仍应遵守对应账号及工作区的使用要求。

二、开始之前，先确认这几个条件

1. 准备 Mac、Codex 客户端和 Node.js

先确认 Codex 能正常打开，并且至少有一个账号已经登录。工具通过 npm 安装，因此终端里还需要能运行 Node.js 和 npm：

node -v
npm -v

如果提示找不到命令，先从 Node.js 官方下载页（备用下载链接：百度网盘 提取码: 22dq ｜夸克网盘 提取码：mpuu）选择当前 LTS 版本，按自己的 Mac 芯片架构安装，再重新打开终端。项目没有声明明确的最低 Node.js 版本，本文不把某个旧版本写成通用兼容下限。

2. 确认登录凭据确实保存在文件中

这个工具默认读取 ~/.codex/auth.json。但 Codex 也可能把凭据放在操作系统凭据库中：官方配置支持 file、keyring、auto 和 ephemeral 等存储方式。

已经登录，不一定就有可供这个工具使用的 auth.json。如果当前使用 keyring 或内存凭据，不能把“文件不存在”直接理解为账号失效；auto 模式下，还可能优先使用凭据库。已有旧文件也不代表它就是客户端正在使用的登录状态。

组织管理的设备应遵循管理员设置，不要为了使用切换器而改动强制认证策略。

3. 切换前结束正在运行的任务

先保存编辑内容，等待任务完成或正常停止，再退出使用同一认证目录的 Codex 桌面端、CLI 和 IDE 会话。不要让旧账号的任务在后台继续运行时覆盖登录文件。

第一次使用前，建议在仅自己可访问的位置保留本地数据备份。工具自动生成的备份只覆盖当前认证文件，不是整个项目或全部聊天记录的备份。

三、安装 codex-account-switcher

本文按核对过的 0.1.5 版本演示。在 macOS 的“终端”中执行：

npm install -g @lchmpm/[email protected] --registry=https://registry.npmjs.org/

安装完成后，检查命令是否可用：

codex-account help --lang zh

能显示帮助说明，就可以继续。需要核对安装版本时，运行：

npm ls -g @lchmpm/codex-account-switcher --depth=0

工具不替代 Codex 本身。若还没有完成 Codex 的首次登录，应先完成登录，再添加账号。

四、把需要的账号保存进列表

第 1 步：保存当前已登录账号

打开中文菜单：

codex-account --lang zh

1. 选择 添加账号。
2. 选择 保存当前已登录账号。
3. 核对终端识别出的邮箱，输入保存名，例如 personal。
   

保存名用英文字母或数字开头，后续可以使用字母、数字、下划线和连字符，例如 work、personal_2。不要给两个不同账号使用同一个保存名，同名保存会覆盖已有快照。

第 2 步：添加另一个账号

再次打开菜单，进入 添加账号 → 打开 Codex，我先登录另一个账号。工具会尝试打开 Codex，接下来由你在官方登录流程中切换到另一个账号。

1. 完成另一个账号的登录，确认客户端显示的账号正确。
2. 回到终端，按回车继续。
3. 再次核对终端识别的邮箱，再保存为 work 等名称。
   

如果终端仍显示原来的邮箱，先不要保存。“打开了另一个登录页面”并不等于本地认证已经更新，应先确认登录完成、凭据目录一致，再继续。

第 3 步：检查保存结果

codex-account status --lang zh

检查当前识别的邮箱、当前匹配的保存名和已保存账号列表。这里显示的是本地凭据摘要，不是服务器在线验证结果。

如果工具无法自动打开你的客户端，也可以手动打开客户端并登录，确认使用的是同一个文件认证目录后，执行：

codex-account capture work --lang zh

这条命令保存的是“此刻本地登录文件中的账号”。work 是示例名称，请按当前账号实际身份填写。

五、日常切换：退出客户端，保存最新状态，再切换

先结束任务、保存文件，在客户端核对当前账号，然后正常退出所有共用这个认证目录的客户端。下面的状态检查、保存和切换命令，在 macOS 的独立“终端”窗口里执行。

1. 更新当前账号的保存副本

Codex 使用过程中可能刷新登录令牌，而 0.1.5 不会自动把刷新后的凭据写回之前保存的账号快照。切换前，先查看当前身份：

codex-account status --lang zh

例如确认当前确实是 personal 后，再更新它的快照：

codex-account capture personal --lang zh

这样可以减少下次切回来时使用旧凭据的情况，但不能保证凭据永不失效。若账号已退出、令牌撤销或服务端要求重新验证，仍需重新登录并保存。

2. 选择目标账号，执行切换

确认相关客户端仍处于退出状态，运行：

codex-account switch --lang zh

用上下键选择目标账号，按回车确认。也可以直接指定已经保存的名称：

codex-account switch work --lang zh

默认流程会备份当前认证文件，复制目标账号的认证文件，再尝试退出并打开名为 Codex 的 macOS 应用。由于源码的顺序是先替换认证文件、后执行重启，提前退出旧客户端更有利于避免它继续写回旧状态。

第一次切换可以先预演：

codex-account switch work --dry-run --lang zh

--dry-run 不写入文件、不重启应用，但也不会联网检验目标凭据是否仍然有效。终端里出现计划动作，不代表真实切换已经完成。

3. 核对客户端中的账号和项目

切换后，先在客户端个人菜单核对账号和工作区，再打开熟悉的本地项目，确认文件路径、配置与任务入口符合预期。最后发起一个新的简单请求，确认当前账号能正常使用。

可以再运行一次 codex-account status --lang zh 作为本地对照；如果终端和客户端显示不一致，应停止继续切换，先按下文排查。

六、常见问题，按情况处理

提示 command not found

先确认包确实安装在当前 Node.js 环境中，再查看 npm 的全局目录：

npm ls -g @lchmpm/codex-account-switcher --depth=0
npm config get prefix

macOS 的全局可执行文件通常位于该目录下的 bin 中。使用 nvm 等版本管理工具时，切换 Node.js 版本也可能切换全局包目录。先重新打开终端、确认当前环境和 PATH；不必一遇到权限或路径错误就加 sudo。

已经登录，却找不到 auth.json

优先核对凭据存储方式和实际 Codex 数据目录。0.1.5 默认使用 ~/.codex，不会自动读取 CODEX_HOME 环境变量；自定义目录时，需要显式指定：

codex-account status --codex-home "/你的实际/Codex目录" --lang zh

把示例路径替换为实际路径。保存、切换、检查等后续命令也要使用相同的 --codex-home 参数。--state-dir 则是切换器保存账号和备份的目录，两者不是同一项。

提示无法打开 Codex.app，或者应用名称不同

当前版本的默认启动名称是 Codex，命令行没有提供修改应用名称的参数。如果你使用的是 ChatGPT 桌面中的 Codex、改名后的应用或其他封装版本，不能直接假设自动重启兼容。

若已确认客户端使用的是这个文件认证目录，可先完全退出客户端，再只切换文件：

codex-account switch work --no-restart --lang zh

然后手动打开实际使用的客户端，重新核对账号。--no-restart 只是跳过自动重启，并不保证其他客户端会接受该文件。重启报错时，认证文件也可能已经替换，不要把报错理解为“什么都没发生”。

本地显示切换成功，客户端仍要求登录

先排查旧客户端是否还在运行、当前使用的认证目录是否正确，以及是否优先使用了操作系统凭据库。如果是保存的令牌过期或失效，重新走官方登录，再按实际账号名称执行 capture 更新快照。

不要反复复制失效文件，也不要把认证文件上传给别人代查。需要反馈时，提供系统版本、工具版本、命令和脱敏后的错误提示即可。

检查配置显示异常，是否说明账号不能用了？

codex-account doctor --lang zh

它主要检查认证文件、已保存快照及若干本地状态文件。该版本把 config.toml 和 .codex-global-state.json 列为必需检查项，因此纯 CLI 环境或目录结构不同的客户端也可能被标记异常。检查通过不代表令牌在线有效，检查异常也不等于账号被封禁。

Windows 和 Linux 能照着用吗？

本文不把这两个平台纳入同样的操作保证。项目主要按 macOS 场景实现和验证，自动打开与重启使用 macOS 命令；在其他平台默认执行切换，可能先改了认证文件，再因重启不支持而报错。应等待明确的平台支持说明，或采用官方客户端的正常登录流程。

七、账号快照存在哪里，删除时要注意什么？

默认情况下，相关文件分布如下：

这些文件包含登录凭据，0.1.5 没有为它们提供额外加密。请放在仅自己可访问的本地位置，不要上传 Git 仓库、公开网盘或粘贴到客服工单中；共享电脑尤其需要注意操作系统账户和文件访问权限。

要移除列表里的某个账号，运行：

codex-account remove --lang zh

通过交互菜单选择并确认。这个操作删除对应的保存目录，不会注销 OpenAI 账号、取消订阅，也不会自动退出当前登录或清理 backups 中的旧副本。若你要彻底停止保留某个账号的本地凭据，还需要另行核对相关备份。

工具保留共享本地状态，也意味着它不能代替个人与公司的数据隔离方案。需要严格区分项目、会话和凭据时，应采用符合组织要求的独立环境。

八、后续更新与我的使用建议

日常可以固定成一个顺序：结束任务并退出客户端 → 核对本地账号 → 更新当前快照 → 切换 → 打开客户端核对新账号。花几秒确认身份，比切错账号后再排查更省事。

后续准备升级时，先查看项目变更，再执行：

npm install -g @lchmpm/codex-account-switcher@latest --registry=https://registry.npmjs.org/

升级后重新检查帮助说明和实际行为，尤其关注凭据存储、应用启动方式和备份规则。本教程核对的是 0.1.5，未来版本如果改了实现，应以对应版本为准。

对经常在同一台 Mac 上切换账号的人来说，这个工具的价值在于把重复操作集中起来。把账号标签、凭据有效期和客户端状态确认好，才能让切换真正成为一个可重复的日常流程。