Skip to main content

codex-profile-switcher

⚠️ 本项目已改名为 codex-safe-switch。 请卸载本包并重装新包:

uv tool uninstall codex-profile-switcher
uv tool install codex-safe-switch

仓库地址: https://github.com/kadaliao/codex-safe-switch 本包不再接收更新,0.5.9 为最终迁移提示版本。

PyPI CI

中文 | English

一键切换 OpenAI Codex CLI 的 provider 配置:官方 ChatGPT 登录、第三方 relay、多组 API key,都可以放进 profile 里。提供命令行工具,并可选配 Alfred workflow。

每个 profile 只接管 ~/.codex/config.toml 里的 provider 片段(model、[model_providers.*]、认证方式)。只有确实需要自己认证文件的 profile 才保存 auth.json;使用 env_key 的 relay 可以继续依赖环境变量,不覆盖官方 ChatGPT 登录缓存。你的本地状态(trusted projects、plugins、marketplaces、MCP servers、TUI 偏好等)会在切换时保留。

安装

需要先安装 uv。

uv tool install codex-profile-switcher

安装后会把 codex-switch 放到 $PATH(默认是 ~/.local/bin/)。如果 shell 找不到命令,运行一次:

uv tool update-shell

后续升级和卸载:

uv tool upgrade codex-profile-switcher
uv tool uninstall codex-profile-switcher

免安装试用

uvx --from codex-profile-switcher codex-switch ls

uvx 会为单次调用解析并缓存临时环境,适合快速试用;如果你要频繁使用,尤其是配合 Alfred,建议用 uv tool install。

安装开发版

想在 PyPI 发版前使用 GitHub 最新提交,可以直接安装仓库版本:

uv tool install git+https://github.com/kadaliao/codex-profile-switcher.git

Alfred(可选)

执行 uv tool install 后,双击 alfred/codex-profile-switcher.alfredworkflow 导入 Alfred。触发关键词是 cx。

workflow 默认调用 $HOME/.local/bin/codex-switch。如果你的 uv tool install 把命令装到了别处,可以用 uv tool dir --bin 查看路径,然后修改 workflow plist 里的两个 script block。

命令

codex-switch              # 交互式选择器(↑/↓,回车切换,q 取消)
codex-switch ls           # 列出 profiles,★ 表示当前 active
codex-switch current      # 打印当前 active profile
codex-switch official     # 切回官方 OpenAI ChatGPT 登录
codex-switch openai       # `official` 的别名
codex-switch use [name]   # 加载 <name>;不传 name 时进入选择器
codex-switch save <name>  # 把当前 ~/.codex 状态保存成 <name>
codex-switch show <name>  # 打印 <name> 的 provider.toml 和 auth.json key 名
codex-switch state <name> # 查看/设置 profile 的 session-state 作用域
codex-switch restart-codex
                           # 终止 Codex app/server 进程,让配置立即生效
codex-switch merge-history --dry-run
                           # 预览历史 metadata 修复,不写入文件
codex-switch doctor-history
                           # 只读检查当前历史 provider/model 状态
codex-switch rm <name>    # 删除 profile(不允许删除 active profile)
codex-switch alfred-list  # 输出 Alfred Script Filter JSON

当 stdin/stdout 不是 TTY(管道、脚本等)时,选择器会自动降级成数字菜单。

首次使用

如果 ~/.codex/profiles/ 里还没有 profile,第一次运行 codex-switch、codex-switch ls 或 Alfred workflow 时,工具会自动导入当前 ~/.codex/config.toml 的 provider 状态,并按 profile 是否需要自己认证来决定是否保存 auth.json。

  • 官方 ChatGPT 登录会导入成隐藏的 official profile。
  • relay/API-key 配置会导入成普通 profile,名字来自 model_provider,例如 relay。
  • 如果 Codex 还没有配置过,CLI 会提示你先正常配置一次 Codex,或者在手动配置 provider 后运行 codex-switch save <name>。

如果需要让 Codex 桌面 app 或 app server 立刻读到新配置,可以使用:

codex-switch use <name> --restart-codex
codex-switch official --restart-codex
codex-switch restart-codex

restart-codex 会终止匹配到的 Codex app/server 进程,并避开 codex-switch 自己。

官方 OpenAI 快捷入口

codex-switch official 可以一键切回官方 OpenAI ChatGPT 登录。

  • 工具会维护隐藏快照:~/.codex/profiles/.official/。
  • 第一次从官方登录切换到其他 profile 时,会自动刷新这个官方快照。
  • 如果你更喜欢按 provider 名称输入,也可以用 codex-switch openai。

默认共享历史

每次执行 use / official 后,codex-switch 都会自动把本地 Codex 历史 metadata 对齐到当前 provider 和 model identity。

  • 正常切换 profile 时不需要再手动记 merge-history。
  • 在 relay profile 和官方 OpenAI 登录之间切换时,历史会继续可见,包括会按 model id 过滤的界面。
  • 如果 session_index.jsonl 落后于 SQLite 里的最新 thread,切换时会从 state_5.sqlite 补追加索引项,避免移动端历史列表停在旧时间点。
  • 如果本机已经开启过 Codex remote-control,切换时还会顺手检查移动端/桌面远程连接依赖的 managed app-server。遇到旧的 unmanaged unix app-server 占住 socket 时会自动结束旧进程并重试;如果 Desktop 还留着旧 SSH remote proxy,会只停止这些 proxy 进程,让下次连接回到当前 MBP;如果缺少官方 standalone 安装,会打印 curl -fsSL https://chatgpt.com/codex/install.sh | sh 这种可执行修复命令。
  • 如果你只想修复 provider,不想覆盖历史里的 model 值,可以继续用 merge-history --keep-models。
  • merge-history --dry-run 会报告将要更新的 rollout 文件数、行数、SQLite rows,以及会创建的备份路径,但不会写入文件。
  • doctor-history 是只读诊断命令,会汇总 active profile、当前 provider/model、session-state 模式、SQLite threads 分布、最近线程、计划对齐数量和漂移状态。

Profile 格式

~/.codex/profiles/
├── .active                       # 明文:当前 active profile 名
├── .official/
│   ├── auth.json                 # 切换时完整复制到 ~/.codex/auth.json
│   └── provider.toml             # 官方登录的 provider 片段
└── myrelay/
    ├── auth.json                 # 可选;只有该 profile 自带 API key 或 ChatGPT token 时需要
    └── provider.toml             # 只包含 provider 相关字段(见 examples/)

profile 会接管下列顶层 key 和 table;~/.codex/config.toml 中其他内容会保留:

  • model, model_provider, model_reasoning_effort, model_reasoning_summary, model_verbosity
  • wire_api, disable_response_storage, preferred_auth_method
  • [model_providers.*]

添加 relay profile

  1. 先按正常方式在 ~/.codex/config.toml 里配置 relay,并确认 codex 可以工作。
  2. 如果 relay 用环境变量提供 key,推荐在 provider 里写 requires_openai_auth = false 和 env_key = "..."。这种 profile 不需要 auth.json,切换时会保留当前的官方 ChatGPT 登录缓存,方便 Codex 远程连接继续使用同一个 ChatGPT 账号。
  3. 运行 codex-switch save <name>,把 provider 片段保存成新 profile。只有 provider 明确需要 OpenAI/ChatGPT auth,或没有声明 requires_openai_auth = false 的旧式 API-key 配置,才会保存 auth.json。
  4. 后续用 Alfred 的 cx 或 codex-switch use <name> 随时切换。

requires_openai_auth = false 只说明这个 relay profile 不需要接管 auth.json。移动端能不能持续同步历史,取决于本机的官方 Codex remote-control/app-server 链路是否健康;这条链路需要官方 standalone install,而不是把 token 复制进每个 profile。

也可以手写 profile 文件,参考 examples/relay-profile/。

环境变量

变量 默认值 用途
CODEX_PROFILE_ROOT ~/.codex/profiles profiles 存放位置
CODEX_HOME ~/.codex 要写入的 Codex 配置目录

发布

PyPI 包发布在 codex-profile-switcher。

当前 GitHub Actions 触发规则:

  • push 到 main 或提交 PR:运行 CI,包含 Python 单测、uv build、twine check。
  • 推送 v* tag:运行 Publish to PyPI workflow,校验 tag 版本和 pyproject.toml 版本一致后,构建并发布到 PyPI。
  • Alfred workflow:目前没有 GitHub Actions 自动构建;仓库里提交的是现成的 alfred/codex-profile-switcher.alfredworkflow。

发版步骤:

  1. 更新 pyproject.toml 里的 version。

  2. 运行 uv run python -m unittest tests.test_cli 和 uv build。

  3. 提交版本变更并推送 main。

  4. 创建并推送匹配的 tag:

    git tag vX.Y.Z
    git push origin vX.Y.Z
    

Publish to PyPI workflow 会验证 tag 版本、运行测试、构建 wheel/sdist、检查分发包并发布到 PyPI。需要手动发布时,也可以使用 uvx twine upload dist/*。

License

MIT

Metadata

Release files for codex-profile-switcher 0.5.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for codex-profile-switcher 0.5.9
File Size Uploaded Provenance Actions
codex_profile_switcher-0.5.9.tar.gz 162.5 kB Without provenance Details for codex_profile_switcher-0.5.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for codex-profile-switcher 0.5.9
File Interpreter ABI Platform Actions
codex_profile_switcher-0.5.9-py3-none-any.whl Python 3 none any Details for codex_profile_switcher-0.5.9-py3-none-any.whl

Total release size: 185.9 kB

Release files / codex_profile_switcher-0.5.9.tar.gz

Download URL codex_profile_switcher-0.5.9.tar.gz
Size 162.5 kB
Tags Source
SHA-256 checksum
How to use checksums
cb98b67153479961f5dac209721d123b681784544ee1cd05e81ef7363d81143b
BLAKE2b-256 checksum
How to use checksums
06481f113261f5d7ee050656778e43e2f56c516cd9912345aa1e63e284ad2a2d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.9

Release files / codex_profile_switcher-0.5.9-py3-none-any.whl

Download URL codex_profile_switcher-0.5.9-py3-none-any.whl
Size 23.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f4821aab5b8e1d4ddef6fc1f78b4d34dc64fe5f2e25911dc07c2174d3dd93eb8
BLAKE2b-256 checksum
How to use checksums
e7282e187caa0d3e5c97511be82aff485391c4ffecb09e0bfdef31ce8b0846c5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.9

Security for codex-profile-switcher 0.5.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page