codex-switch-account

Codex CLI account switcher for multiple ChatGPT accounts. The installed command is codex-gpt.

codex-switch-account 是一个 Codex CLI 本地账号切换工具。它可以保存多个 ChatGPT 登录态，让这些账号共享同一套独立的 Codex 会话、历史、配置和 resume 状态，并在交互式 Codex TUI 额度用尽时自动切到下一个账号继续会话。

默认情况下，它不会修改你原来的 ~/.codex 目录。项目自己的数据会放在 ~/.codex-gpt，通过隔离的共享 Codex home 启动 Codex。

本项目只适合管理你自己拥有或被授权使用的账号。它不修改 Codex 本身，也不绕过 任何账号限制。

English documentation is available below: English.

适合检索的关键词：Codex CLI account switcher、OpenAI Codex multiple accounts、ChatGPT multi-account、Codex account manager、Codex usage fallback、 Codex auto resume。

版本变化见 CHANGELOG，GitHub 描述和 topics 建议见 GitHub Discovery Settings。

功能

• 多账号保存：把多个 ChatGPT 登录态保存为 gpt1、gpt2、gpt3 等账号槽。
• 快速切换：使用 codex-gpt 2 这类短命令切换当前账号。
• 共享会话：所有托管账号共用 ~/.codex-gpt/shared/.codex，方便继续同一个 Codex 会话、历史、配置、记忆和 resume 状态。
• 独立登录：添加新账号时不会登出当前共享账号。
• 额度查看：codex-gpt list 显示账号邮箱、5 小时额度、周额度和重置时间。
• 自动切号：watch 默认开启，交互式 Codex TUI 额度用尽时，会确认账号额度状态， 并切到下一个仍有额度的已保存账号。
• 自动续答：自动切号后会恢复当前会话，并可自动发送继续任务的 follow-up prompt。
• 可配置续答：通过 CODEX_GPT_AUTO_CONTINUE 和 CODEX_GPT_AUTO_CONTINUE_PROMPT 控制自动续答行为。
• 原生 TUI 显示：默认使用 Codex 自身的全屏 TUI；需要保留终端滚动记录时，可以用 CODEX_GPT_NO_ALT_SCREEN=on 开启内联模式。
• 原目录保护：默认不改动你的原始 ~/.codex 登录态、会话和历史。

项目优势

• 面向真实 Codex TUI 工作流：不是只复制 auth.json，而是围绕会话恢复、额度查看、 自动切号和继续任务做完整包装。
• 不污染原始 Codex 环境：项目数据默认集中在 ~/.codex-gpt，删除这个目录即可清理 工具数据。
• 多账号共享同一条工作上下文：不同账号可以接续同一个 Codex 会话，而不是每个账号 一套割裂的历史。
• 任务接续更顺手：自动切号后可以继续刚才的会话，减少手动找会话、复制问题和重新 描述上下文的成本。
• 脚本部署简单：核心是 Bash + Python 3，不需要后台服务或数据库迁移。
• 对开源使用友好：命令、数据目录、环境变量和安全边界都在 README 中明确说明。

设计边界

• 这是 Codex CLI 包装器，不修改 Codex 程序，也不绕过账号额度。
• 只影响通过 codex-gpt 启动的 Codex。
• 已经运行中的普通 codex 进程不会原地切换账号；需要通过 codex-gpt 启动。
• 默认不控制读取原始 ~/.codex 的 Codex 桌面 App 或其他集成。
• watch 依赖 Codex CLI 对额度状态的正常反馈。如果 Codex 调整相关提示，后续版本 可能需要适配。
• 原生 Windows PowerShell/CMD 不作为目标环境；推荐 WSL，Git Bash 为尽力支持。

依赖

• 已安装 Codex CLI，并且可以通过 codex 命令运行
• Bash
• Python 3
• 支持 PTY 的类 Unix 终端

支持环境：

• macOS
• Linux
• Windows WSL
• Windows Git Bash，尽力支持

安装

git clone https://github.com/yunkai93/codex-switch-account.git
cd codex-switch-account
./install.sh

如果 ~/.local/bin 不在 PATH 里，添加：

export PATH="$HOME/.local/bin:$PATH"

也可以不安装，直接在项目目录运行：

./bin/codex-gpt help

快速开始

添加账号：

codex-gpt add 1
codex-gpt add 2

查看账号和额度：

codex-gpt list

示例输出：

accounts left/reset (5h|week):
  gpt1   user1@example.com             82%@06-04 20:39|96%@06-11 20:39
* gpt2   user2@example.com             40%@06-04 20:59|75%@06-11 20:59
watch: on

启动 Codex：

codex-gpt

切换账号：

codex-gpt 1

通过共享目录运行 Codex 参数：

codex-gpt resume --last
codex-gpt exec "summarize this repo"

命令

codex-gpt              # 使用当前账号启动 Codex
codex-gpt help         # 显示帮助
codex-gpt list         # 查看账号、邮箱、额度、重置时间和 watch 状态
codex-gpt 1            # 切换到账号 1
codex-gpt add 1        # 登录新账号并保存为账号 1
codex-gpt save 1       # 保存当前共享登录态为账号 1
codex-gpt watch        # 查看自动切号状态
codex-gpt watch on     # 开启自动切号
codex-gpt watch off    # 关闭自动切号

数据目录

默认数据目录：

~/.codex-gpt/
├── accounts/
│   ├── gpt1.auth.json
│   └── gpt2.auth.json
├── shared/
│   └── .codex/
└── tmp/

共享 Codex 目录：

~/.codex-gpt/shared/.codex

自定义数据目录：

CODEX_GPT_HOME=/path/to/codex-gpt codex-gpt list

自定义 Codex 命令路径：

CODEX_BIN=/path/to/codex codex-gpt list

Watch 模式

watch 默认开启。

在交互式 TUI 中，codex-gpt 会关注额度用尽状态。确认当前账号已无可用额度后， 它会跳过同样无额度的账号，切到下一个可用账号，并恢复当前会话继续任务。

为了不干扰 Codex 全屏 TUI，watch 诊断信息默认静默。需要调试时可以使用 CODEX_GPT_WATCH_VERBOSE=on。

自动续答默认开启，可以调整：

CODEX_GPT_AUTO_CONTINUE=off
CODEX_GPT_AUTO_CONTINUE_PROMPT="继续刚才的任务"
CODEX_GPT_NO_ALT_SCREEN=on  # 可选：以内联模式运行并保留终端滚动记录
CODEX_GPT_RESUME_NO_ALT_SCREEN=on  # 可选：resume 也使用内联模式

25%、10%、5% 这类剩余额度预警不会触发自动切号。

直接运行 codex-gpt resume ... 时也会启用 watch。

关闭：

codex-gpt watch off

开启：

codex-gpt watch on

安全说明

不要提交或分享数据目录和登录文件。它们包含有效登录凭据。

不要提交：

• ~/.codex-gpt/accounts/*.auth.json
• ~/.codex-gpt/shared/.codex/auth.json
• 复制出来的 .codex 目录
• 可能包含账号信息的终端日志

请只把这个工具用于你自己拥有或被授权使用的账号，并遵守对应的 OpenAI 和 Codex 使用条款。

---

English

codex-switch-account is a local Codex CLI account switcher. It stores multiple ChatGPT login states, lets them share one isolated Codex home, and can switch to another saved account during an interactive Codex TUI session when usage is exhausted.

The installed command is codex-gpt.

By default, it does not modify your existing ~/.codex directory. It stores its own data under ~/.codex-gpt and runs Codex with that isolated shared home.

This project is intended only for accounts you own or are authorized to use. It does not modify Codex itself and does not bypass account limits.

Search terms this project is meant to match: Codex CLI account switcher, OpenAI Codex multiple accounts, ChatGPT multi-account, Codex account manager, Codex usage fallback, and Codex auto resume.

For release notes, see CHANGELOG. For GitHub repository description and topic suggestions, see GitHub Discovery Settings.

Features

• Save multiple ChatGPT login states as slots such as gpt1, gpt2, and gpt3.
• Switch the active account with short commands such as codex-gpt 2.
• Share one isolated Codex home across managed accounts for sessions, history, configuration, memory state, and resume state.
• Add new accounts without logging out the active shared account.
• Show email, remaining 5-hour usage, weekly usage, and reset times in list.
• Watch interactive Codex TUI sessions and switch to another saved account with available quota when usage is exhausted.
• Resume the interrupted conversation with an optional follow-up prompt.
• Customize automatic continuation with CODEX_GPT_AUTO_CONTINUE and CODEX_GPT_AUTO_CONTINUE_PROMPT.
• Use Codex's native full-screen TUI by default. Set CODEX_GPT_NO_ALT_SCREEN=on only when you prefer inline mode that preserves terminal scrollback.
• Keep the user's original ~/.codex untouched by default.

Advantages

• Built for the real Codex TUI workflow: account switching, shared sessions, usage inspection, automatic fallback, and continuation are handled together.
• Isolated by default: managed data lives under ~/.codex-gpt, so the original Codex home remains untouched.
• Shared work context across accounts: saved accounts can continue the same Codex conversation instead of splitting work across separate histories.
• Smoother continuation: after an automatic switch, the tool can continue the current conversation without making you manually find and reopen the session.
• Simple deployment: Bash and Python 3, with no background service.
• Clear open-source boundaries: commands, data paths, environment variables, and security notes are documented.

Design Boundaries

• This is a Codex CLI wrapper. It does not modify Codex itself or bypass account limits.
• It only affects Codex commands started through codex-gpt.
• Existing plain codex processes do not switch accounts in place.
• Codex desktop/app integrations that read the original ~/.codex directory are not controlled by default.
• watch relies on Codex CLI's normal usage-limit feedback. If Codex changes those messages, a future version may need to adapt.
• Native Windows PowerShell/CMD is not supported by this Bash implementation. Use WSL when possible.

Requirements

• Codex CLI installed and available as codex
• Bash
• Python 3
• A Unix-like terminal with PTY support

Supported targets:

• macOS
• Linux
• Windows via WSL
• Windows via Git Bash, best effort

Install

git clone https://github.com/yunkai93/codex-switch-account.git
cd codex-switch-account
./install.sh

If ~/.local/bin is not on your PATH, add:

export PATH="$HOME/.local/bin:$PATH"

You can also run it directly from the repo:

./bin/codex-gpt help

Quick Start

codex-gpt add 1
codex-gpt add 2
codex-gpt list
codex-gpt
codex-gpt 1
codex-gpt resume --last

Commands

codex-gpt              # start Codex with the active account
codex-gpt help         # show help
codex-gpt list         # list accounts, emails, limits, reset times, and watch state
codex-gpt 1            # switch to account slot 1
codex-gpt add 1        # log in a new account and save it as slot 1
codex-gpt save 1       # save current shared login as slot 1
codex-gpt watch        # show auto-switch state
codex-gpt watch on     # enable auto-switch
codex-gpt watch off    # disable auto-switch

Data Directory

Default data directory:

~/.codex-gpt/
├── accounts/
│   ├── gpt1.auth.json
│   └── gpt2.auth.json
├── shared/
│   └── .codex/
└── tmp/

Shared Codex home:

~/.codex-gpt/shared/.codex

Override the data directory:

CODEX_GPT_HOME=/path/to/codex-gpt codex-gpt list

Override the Codex binary:

CODEX_BIN=/path/to/codex codex-gpt list

Watch Mode

watch is enabled by default.

In an interactive TUI session, codex-gpt watches for exhausted usage. After the running account has no available quota, it skips other exhausted accounts, switches to the next available account, and resumes the current conversation.

Watch diagnostics are quiet by default so they do not interfere with Codex's full-screen TUI. Set CODEX_GPT_WATCH_VERBOSE=on when debugging.

Automatic follow-up prompting is enabled by default and can be adjusted:

CODEX_GPT_AUTO_CONTINUE=off
CODEX_GPT_AUTO_CONTINUE_PROMPT="continue the previous task"
CODEX_GPT_NO_ALT_SCREEN=on  # optional: inline mode that preserves scrollback
CODEX_GPT_RESUME_NO_ALT_SCREEN=on  # optional: inline mode for resume too

Remaining-limit warnings such as 25%, 10%, or 5% left are ignored.

Explicit codex-gpt resume ... invocations are watched too.

Security Notes

Never commit or share your data directory or auth files. They contain active login credentials.

Do not commit:

• ~/.codex-gpt/accounts/*.auth.json
• ~/.codex-gpt/shared/.codex/auth.json
• copied .codex directories
• terminal logs that may contain account metadata

Use this tool only with accounts you own or are authorized to use, and follow the OpenAI and Codex terms for your account.