codex-account-switcher

A CLI for switching between multiple local Codex accounts while keeping shared local state.

• 中文文档: 跳转到中文
• English docs: Jump to English

中文文档

这是什么

codex-account-switcher 是一个给 Codex 多账号用户准备的小工具。

它解决的是这个问题：

• 你在一台机器上会切多个 Codex / ChatGPT Plus 账号
• 你不想每次都重新登录
• 你不想因为切号把本地项目、信任状态、桌面端状态一起弄乱

它的做法比较保守：

• 只切换 auth.json
• 保留共享本地状态
• 切换后自动重启 Codex

所以它本质上不是“自动登录器”，而是：

已登录账号的本地切换器

它适合谁

• 你有 2 个或更多 Codex / ChatGPT Plus 账号
• 你经常在这些账号之间切换
• 你希望保留本地共享状态，而不是整包替换 ~/.codex

它不做什么

• 不会替你输入账号密码
• 不会绕过官方登录流程
• 不会把 A 账号的云端会话同步到 B 账号

终端预览

┌──────────────────────────────────────────────┐
│ codex-account                                │
│ 在已保存的 Codex 账号之间快速切换             │
│                                              │
│ 当前账号: [email protected]               │
│ 当前 profile: personal                       │
│ 已保存账号: 2                                │
│                                              │
│ 提示: 先添加需要的账号，再用“切换账号”一键切换 │
└──────────────────────────────────────────────┘

❯ 🔁 切换账号
  ➕ 添加账号
  🪪 查看当前状态
  🗑️ 删除已保存账号
  🩺 检查配置
  👋 退出

使用上下键选择，回车确认

安装

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

如果你已经装过，更新到最新版本：

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

也可以尝试：

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

30 秒快速开始

1. 安装包
2. 运行：

codex-account

3. 第一次先选 添加账号
4. 保存当前已经登录的账号
5. 再次进入 添加账号
6. 选择 打开 Codex，我先登录另一个账号
7. 在 Codex 里完成登录，回到终端按回车
8. 给这个账号起一个保存名，例如 work、personal
9. 以后日常只需要运行 codex-account，再用上下键进入 切换账号

第一次使用

场景 A：保存当前账号

运行：

codex-account

然后：

1. 选择 添加账号
2. 选择 保存当前已登录账号
3. 输入一个名字，例如 personal

场景 B：再添加一个账号

再次运行：

codex-account

然后：

1. 选择 添加账号
2. 选择 打开 Codex，我先登录另一个账号
3. 工具会拉起 Codex
4. 你在 Codex 中手动登录新账号
5. 登录完成后回到终端按回车
6. 给这个账号输入保存名

按同样流程可以继续添加更多账号。

日常怎么用

平时主要就是：

codex-account

然后：

1. 用上下键选中 切换账号
2. 回车进入账号列表
3. 再用上下键选中目标账号
4. 回车确认

工具会自动替换本地登录态，并按默认配置重启 Codex。

主菜单

默认运行：

codex-account

会进入一级菜单。菜单项包括：

• 切换账号
• 添加账号
• 查看当前状态
• 删除已保存账号
• 检查配置
• 退出

一级菜单和账号列表都支持上下键选择。

命令行用法

打开主菜单：

codex-account

直接进入切换：

codex-account switch

直接切到指定账号：

codex-account switch work

添加账号：

codex-account add

查看当前状态：

codex-account status

删除一个已保存账号：

codex-account remove

兼容旧命令，保存当前账号：

codex-account capture work

常见问题

它能自动登录新账号吗？

不能完全自动。

它能做的是：

• 打开 Codex
• 等你手动完成官方登录
• 登录完成后，把当前账号保存下来

所以新账号第一次接入时，还是需要你手动登录一次。

我本地有多个账号，但当前只登录了一个，怎么办？

先把当前这个保存下来，再走一次 添加账号 -> 打开 Codex，我先登录另一个账号，把剩余账号也保存下来即可。

切换后会不会把项目弄丢？

这个工具就是为了解决这个问题才做的。

它默认不会整包替换 ~/.codex，而是尽量保留共享本地状态。但实话说，Codex 官方没有公开“多账号本地状态切换协议”，所以这是保守实现，不是官方保证 API。第一次建议先试切一次，确认你的机器状态符合预期。

为什么切换后会重启 Codex？

因为只改本地认证文件，运行中的桌面应用不一定会立刻刷新状态。自动重启是为了让切换更稳定。

可以关闭自动重启吗？

可以：

codex-account switch --no-restart

如果提示 command not found 怎么办？

先检查 npm 全局目录：

npm config get prefix

把对应的 bin 目录加到 PATH，例如在 ~/.zshrc 里加入：

export PATH="$(npm config get prefix)/bin:$PATH"

然后重新加载：

source ~/.zshrc

可选参数

--no-restart
--dry-run
--json
--codex-home <path>
--state-dir <path>
--lang <zh|en|bilingual>

适用范围和限制

适合：

• 单机使用
• 2 个或更多本地已登录过的账号
• 希望保留共享本地状态的切换方式

限制：

• 不同步不同账号的云端聊天记录
• 不代替官方登录
• 目前主要按 macOS 场景实现和验证

反馈与贡献

欢迎提 issue 或 PR。

更值得继续改进的方向包括：

1. 更清晰的交互文案
2. 更好的首次安装引导
3. 更可靠的状态检测
4. 更完整的错误提示和恢复建议

许可证

MIT

开发

运行测试：

npm test

English

What this is

codex-account-switcher is a CLI for people who switch between multiple Codex accounts on one machine.

It is built for this workflow:

• you use two or more Codex / ChatGPT Plus accounts
• you do not want to log in again every time
• you do not want account switching to wipe or scramble local shared state

The tool takes a conservative approach:

• switch only auth.json
• keep shared local state in place
• restart Codex after switching

So this is not an automatic account login tool. It is:

a local switcher for accounts that have already been logged in once

Who it is for

• You have two or more Codex / ChatGPT Plus accounts
• You switch between them often
• You want to preserve shared local state instead of replacing the whole ~/.codex directory

What it does not do

• It does not type account credentials for you
• It does not bypass the official login flow
• It does not sync cloud conversations from account A into account B

Terminal preview

┌──────────────────────────────────────────────┐
│ codex-account                                │
│ Switch between saved Codex accounts          │
│                                              │
│ Current account: [email protected]        │
│ Current profile: personal                    │
│ Saved accounts: 2                            │
│                                              │
│ Tip: add the accounts you need first         │
└──────────────────────────────────────────────┘

❯ 🔁 Switch account
  ➕ Add account
  🪪 Current status
  🗑️ Delete saved account
  🩺 Check setup
  👋 Exit

Use arrow keys to choose, Enter to confirm

Install

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

To update to the latest version:

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

You can also try:

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

30-second quick start

1. Install the package
2. Run:

codex-account

3. Choose Add account
4. Save the account that is already logged in
5. Choose Add account again
6. Choose Open Codex and log into another account
7. Log into the next account in Codex, then return to the terminal and press Enter
8. Give that account a saved name such as work or personal
9. From then on, run codex-account and use arrow keys to enter Switch account

First-time setup

Case A: save the currently logged-in account

Run:

codex-account

Then:

1. Choose Add account
2. Choose Save current logged-in account
3. Enter a name such as personal

Case B: add another account

Run again:

codex-account

Then:

1. Choose Add account
2. Choose Open Codex and log into another account
3. The tool opens Codex
4. Log into the new account manually
5. Return to the terminal and press Enter
6. Enter a saved name for that account

Repeat the same flow to add more accounts.

Daily use

Most of the time you only need:

codex-account

Then:

1. Use arrow keys to highlight Switch account
2. Press Enter
3. Use arrow keys again to highlight the target account
4. Press Enter to confirm

The tool updates the local auth state and restarts Codex by default.

Main menu

Running:

codex-account

opens the first-level menu. It includes:

• Switch account
• Add account
• Current status
• Delete saved account
• Check setup
• Exit

Both the main menu and the account list use arrow-key navigation.

CLI usage

Open the main menu:

codex-account

Jump straight into account switching:

codex-account switch

Switch directly to a named profile:

codex-account switch work

Add an account:

codex-account add

Show current status:

codex-account status

Remove a saved account:

codex-account remove

Legacy save command:

codex-account capture work

FAQ

Can it automatically log into a new account?

Not fully.

What it can do is:

• open Codex
• wait for you to complete the official login flow
• save the current account after login finishes

So the first time you add a new account, you still need to log in manually once.

I already have multiple accounts locally, but only one is currently logged in. What should I do?

Save the current one first, then run Add account -> Open Codex and log into another account again for each remaining account you want to keep.

Will switching make me lose my projects?

That is exactly the problem this tool is meant to reduce.

By default it does not replace the whole ~/.codex directory. It tries to preserve shared local state. Still, this is a conservative implementation rather than an official API, because Codex does not publish a formal local multi-account switching protocol. Test it once on your machine before relying on it heavily.

Why does it restart Codex after switching?

Changing local auth files does not guarantee that a running desktop app refreshes its state immediately. Restarting makes the switch more reliable.

Can I disable automatic restart?

Yes:

codex-account switch --no-restart

What if I see command not found?

Check your npm global prefix:

npm config get prefix

Add its bin directory to your PATH, for example in ~/.zshrc:

export PATH="$(npm config get prefix)/bin:$PATH"

Reload your shell:

source ~/.zshrc

Options

--no-restart
--dry-run
--json
--codex-home <path>
--state-dir <path>
--lang <zh|en|bilingual>

Scope and limits

Good for:

• single-machine use
• two or more accounts that have already been logged in locally
• preserving shared local state during account switching

Limits:

• it does not sync cloud chats across accounts
• it does not replace the official login flow
• it is currently implemented and validated mainly for macOS

Feedback and contributions

Issues and pull requests are welcome.

Useful areas to improve next:

1. clearer interaction copy
2. better first-run guidance
3. more reliable state detection
4. stronger error recovery hints

License

MIT

Development

Run tests:

npm test