{"id":50148633,"url":"https://github.com/tytsxai/codex-app-account-switcher","last_synced_at":"2026-05-24T07:02:28.804Z","repository":{"id":359254809,"uuid":"1245207070","full_name":"tytsxai/codex-app-account-switcher","owner":"tytsxai","description":"macOS Codex.app account switcher for local auth snapshot pools, dry-run validation, and safe relaunch workflows","archived":false,"fork":false,"pushed_at":"2026-05-21T06:22:25.000Z","size":66,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-21T09:42:14.074Z","etag":null,"topics":["account-switcher","auth-management","automation","cli","codex","codex-app","desktop-helper","local-first","macos","shell"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tytsxai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T02:32:37.000Z","updated_at":"2026-05-21T06:22:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tytsxai/codex-app-account-switcher","commit_stats":null,"previous_names":["tytsxai/codex-app-account-switcher"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tytsxai/codex-app-account-switcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Fcodex-app-account-switcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Fcodex-app-account-switcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Fcodex-app-account-switcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Fcodex-app-account-switcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tytsxai","download_url":"https://codeload.github.com/tytsxai/codex-app-account-switcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Fcodex-app-account-switcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33424573,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["account-switcher","auth-management","automation","cli","codex","codex-app","desktop-helper","local-first","macos","shell"],"created_at":"2026-05-24T07:02:24.291Z","updated_at":"2026-05-24T07:02:28.794Z","avatar_url":"https://github.com/tytsxai.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Codex.app Account Switcher / Codex 桌面端账号切换器\n\nCodex.app Account Switcher 是一个面向 macOS 的本地账号池切换工具。它帮助已经使用 `codex-auth` 或本地 ChatGPT/Codex 登录快照的用户，按实时可用额度选择账号，写入 `~/.codex/auth.json`，并可自动重启 Codex.app 让桌面端读取新的登录状态。\n\n\u003e Unofficial local helper for Codex.app account pool switching. This project is not an OpenAI product and only works with user-owned local auth snapshots.\n\n## 项目定位 / Overview\n\n- **项目是什么**：一个 Bash + Node.js 编写的 macOS 本地 CLI/启动器，用于管理 Codex.app 的本地登录快照和账号切换流程。\n- **解决什么问题**：当用户自己维护多个 Codex / ChatGPT 登录快照时，手动判断哪个账号还有 Codex 额度、复制 `auth.json`、重启 App 容易出错；本项目把实时校验、切换、重启和自检串成一个可重复流程。\n- **适合谁使用**：已经理解 `~/.codex` 本地认证文件、拥有多个自有账号快照、希望在个人 Mac 上更稳妥切换 Codex.app 登录状态的开发者或重度 Codex 用户。\n- **不适合谁使用**：没有本地 auth 快照、不了解令牌风险、希望绕过服务限制、希望托管账号或共享账号的人。\n- **技术栈 / Tech stack**：Bash, Node.js ESM, `jq`, `curl`, macOS `open` / `osascript`, GitHub raw/codeload updater.\n\n## 核心功能 / Key Features\n\n- 实时读取 ChatGPT/Codex usage API，只选择当前可读且额度达标的账号。\n- 默认优先 Free 账号的 5h/Codex 可用额度，Plus/Pro/Team/Business 可作为后备。\n- 写入前后校验 `~/.codex/auth.json`，降低“registry 显示已切换但实际文件未变”的风险。\n- 支持导入 `codex-auth`、`codex-sub2api` 或扁平 token JSON，并只写入实时验证成功的账号。\n- 支持 `--dry-run` 预演、`--switch-only` 只切换、`--relaunch` 切换后重启 Codex.app。\n- 提供本地安装器、桌面 `.command` 启动器、更新检查、自更新和发版前自检。\n- 清理不可用账号时保留归档，不直接删除无法确定的网络失败或临时 usage 失败账号。\n\n## 快速开始 / Quick Start\n\n### 1. 安装依赖\n\n本项目只面向 macOS。运行前需要：\n\n- `/Applications/Codex.app`\n- `jq`\n- `node`\n- `curl`\n- `tar`\n- 可选：`codex-auth`，用于生成或维护本地登录快照\n\n可用 Homebrew 安装基础依赖：\n\n```bash\nbrew install jq node\n```\n\n### 2. 安装本工具\n\n```bash\nrepo=\"tytsxai/codex-app-account-switcher\" \\\n  \u0026\u0026 sha=\"$(curl -fsSL \"https://api.github.com/repos/$repo/commits/main\" | jq -r '.sha')\" \\\n  \u0026\u0026 tmp=\"$(mktemp -d)\" \\\n  \u0026\u0026 curl -fsSL \"https://codeload.github.com/$repo/tar.gz/$sha\" \\\n  | tar -xz -C \"$tmp\" --strip-components 1 \\\n  \u0026\u0026 SOURCE_REVISION=\"$sha\" bash \"$tmp/scripts/install.sh\"\n```\n\n安装器会部署到：\n\n- App files: `~/.local/share/codex-app-account-switcher`\n- CLI: `~/.local/bin/codex-account-switch`\n- Desktop launcher: `~/Desktop/启动Codex换号.command`\n\n如果 `~/.local/bin` 不在 `PATH` 中，把下面这行加入 shell 配置：\n\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n### 3. 首次配置账号池\n\n1. 使用你自己的账号完成至少一次 `codex-auth` 登录，或准备已有的本地 auth JSON 快照。\n2. 把额外来源文件放在私有目录，例如 `~/.codex/account-sources`。\n3. 先用 dry run 导入候选账号：\n\n```bash\nmkdir -p \"$HOME/.codex/account-sources\"\nAPP_DIR=\"$HOME/.local/share/codex-app-account-switcher\"\n\"$APP_DIR/codex-auth-import-json.mjs\" --dry-run \"$HOME/.codex/account-sources/source.json\"\n```\n\n从源码仓库直接运行时使用：\n\n```bash\n./codex-auth-import-json.mjs --dry-run \"$HOME/.codex/account-sources/source.json\"\n./codex-auth-import-json.mjs --yes \"$HOME/.codex/account-sources/source.json\"\n```\n\n安装后脚本位于：\n\n```bash\n\"$HOME/.local/share/codex-app-account-switcher/codex-auth-import-json.mjs\" --dry-run \"$HOME/.codex/account-sources/source.json\"\n\"$HOME/.local/share/codex-app-account-switcher/codex-auth-import-json.mjs\" --yes \"$HOME/.codex/account-sources/source.json\"\n```\n\n### 4. 预演并切换\n\n```bash\ncodex-account-switch --dry-run\ncodex-account-switch --relaunch\n```\n\n`--dry-run` 只查看将要选择的账号和账号池状态，不改写文件；`--relaunch` 会切换 `~/.codex/auth.json` 并重启 Codex.app。\n\n## 常用命令 / Common Commands\n\n```bash\n# 交互启动器\ncodex-account-switch\n\n# 只预演，不写入账号文件\ncodex-account-switch --dry-run\n\n# 切换账号并重启 Codex.app\ncodex-account-switch --relaunch\n\n# 只切换 auth，不重启 App\ncodex-account-switch --switch-only\n\n# 指定账号或排除套餐\ncodex-account-switch --force-email you@example.com --switch-only\ncodex-account-switch --exclude-plan plus --dry-run\n\n# 检查更新、自更新、查看版本\ncodex-account-switch --check-updates\ncodex-account-switch --self-update\ncodex-account-switch --version\n```\n\n源码仓库中的维护命令：\n\n```bash\n./codex-auth-smart-switch.sh --cleanup-unusable --dry-run\n./codex-auth-smart-switch.sh --cleanup-unusable --yes\n./codex-auth-import-json.mjs --dry-run ./path/to/source.json\n./codex-auth-load-free.mjs --dry-run\n./codex-auth-load-free.mjs --yes\n```\n\n## 使用场景 / Use Cases\n\n- 个人 Mac 上维护多个自有 Codex / ChatGPT 登录快照，希望减少手动复制 `auth.json` 的风险。\n- 在 Codex.app 出现额度不足或账号不可用时，快速预览账号池并切到仍有可用额度的账号。\n- 导入新的 auth JSON 来源前，先做实时 usage 校验，避免把无效、过期或身份信息不完整的账号写入 registry。\n- 定期清理确定不可用的本地账号快照，同时保留删除前归档用于追溯。\n- 在开源仓库中保留一个不含凭证的、可复现的本地账号切换流程。\n\n## 配置 / Configuration\n\n常用环境变量：\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `CODEX_HOME` | `~/.codex` | 账号池和活动 auth 文件根目录 |\n| `MIN_5H_REMAIN` | `10` | 5h 窗口最低剩余百分比 |\n| `MIN_WEEKLY_REMAIN` | `5` | 存在 weekly 窗口时的最低剩余百分比 |\n| `USABLE_PLANS` | `free,plus,pro,team,business` | 允许自动选择或导入的套餐 |\n| `POOL_PREVIEW_LIMIT` | `0` | 账号池预览数量，`0` 表示不限 |\n| `MAX_PARALLEL_REFRESH` | `4` | 并发刷新账号 usage 的数量 |\n| `CODEX_APP_BUNDLE_ID` | `com.openai.codex` | Codex.app bundle id |\n\n示例：\n\n```bash\nMIN_5H_REMAIN=20 USABLE_PLANS=free,plus codex-account-switch --dry-run\nCODEX_HOME=\"$HOME/.codex-test\" codex-account-switch --dry-run\n```\n\n## 项目边界与注意事项 / Limitations\n\n- 本项目不会提供、生成或托管任何账号；所有凭证都必须来自你自己的本地文件。\n- 本项目不会绕过 OpenAI、ChatGPT 或 Codex 的服务限制，只会在你本地已有账号快照中选择实时可用账号。\n- usage、refresh 和 Codex.app 行为依赖非官方本地流程和相关 Web 端点，未来可能因上游变化而失效。\n- 运行 `--relaunch` 会尝试关闭并重新打开 Codex.app；如果脚本检测到自己运行在 Codex.app 内部，会拒绝自动关闭当前会话。\n- 清理命令只删除确定性不可用状态，例如 auth 失败、缺少快照、缺少 refresh token 或套餐不在 `USABLE_PLANS`；网络失败不会自动删除。\n- 不要把 `~/.codex/auth.json`、`~/.codex/accounts/`、`*.auth.json`、来源 JSON 或归档文件提交到公开仓库。\n\n## 文档 / Documentation\n\n- [docs/README.md](docs/README.md): documentation index\n- [docs/operations.md](docs/operations.md): daily operations, import, cleanup, update, troubleshooting\n- [docs/security.md](docs/security.md): credential boundaries and public-repo safety\n- [docs/usage-examples.md](docs/usage-examples.md): practical command examples\n- [docs/faq.md](docs/faq.md): common questions and project limitations\n- [llms.txt](llms.txt): AI-search-friendly project summary\n\n## 开发与自检 / Development\n\n```bash\n./check.sh\nscripts/install.sh --dry-run\nscripts/check-updates.sh --json\n```\n\n`./check.sh` 会验证 shell 语法、Node.js 语法、可选 shellcheck、依赖工具、更新链路和常见密钥泄露模式。\n\n## 卸载 / Uninstall\n\n```bash\nrm -rf \"$HOME/.local/share/codex-app-account-switcher\"\nrm -f \"$HOME/.local/bin/codex-account-switch\"\nrm -f \"$HOME/Desktop/启动Codex换号.command\"\n```\n\n这不会删除 `~/.codex/accounts` 或 `~/.codex/auth.json`。\n\n## 更新 / Keeping It Updated\n\n```bash\ncodex-account-switch --check-updates\ncodex-account-switch --self-update\n```\n\n自更新会替换安装目录中的脚本和文档，不会主动删除你的 `~/.codex` 账号池。更新检查会同时报告本仓库 revision、raw installer、codeload archive、本地 `codex-auth`、npm 最新 `codex-auth` 和本地 Codex.app 版本。\n\n## 推荐 GitHub Topics\n\n`codex`, `codex-app`, `chatgpt`, `account-switcher`, `macos`, `cli`, `bash`, `nodejs`, `jq`, `developer-tools`, `local-first`, `auth-management`\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=tytsxai/codex-app-account-switcher\u0026type=Date)](https://star-history.com/#tytsxai/codex-app-account-switcher\u0026Date)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftytsxai%2Fcodex-app-account-switcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftytsxai%2Fcodex-app-account-switcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftytsxai%2Fcodex-app-account-switcher/lists"}