Codex Key Manager

English

一个面向 WSL/Linux 的零依赖终端配置管理器，用来快捷管理 Codex 的 API Key 与 Base URL。

当 Windows 上的 CCSwitch 无法直接管理 WSL 内的 Codex 配置时，可以在 WSL 终端中运行 codex-key，完成新增、切换、检查与备份，无需手动反复编辑 JSON/TOML。

特性

• 终端 TUI：键盘完成新增、编辑、复制、删除、搜索与激活
• 同时切换 ~/.codex/auth.json 的 Key 与 config.toml 的 base_url
• 自动导入已有的 auth-*.json 配置
• 原子写入与失败回滚，避免只切换了 Key 或只切换了 URL
• Key 默认遮蔽，可写入 Windows/Wayland/X11 剪贴板
• 后台测试 /models 接口，不阻塞界面
• 安全回收站与 ZIP 备份
• 纯 Python 标准库，无需 pip install 依赖

一键安装

需要 Python 3.10+，支持 WSL 和常见 Linux 发行版：

curl -fsSL https://raw.githubusercontent.com/sondy-SDY/codex-key-manager/main/install.sh | bash

然后运行：

codex-key

安装器只写入 ~/.local/bin/codex-key，不会改动现有的 ~/.codex 数据。更新时再次运行同一条命令即可，旧程序会保留为 codex-key.previous。

也可以从源码安装：

git clone https://github.com/sondy-SDY/codex-key-manager.git
cd codex-key-manager
make install

使用

不带参数打开 TUI：

codex-key

常用快捷键：

按键	操作
A / E / D	新增 / 编辑 / 删除配置
Enter	激活所选配置
/	按名称、URL 或备注搜索
V / C	显示 Key / 复制 Key
T	测试 API 连接
B	创建安全备份
?	查看完整快捷键

命令行模式适合脚本和快速切换：

codex-key list
codex-key show
codex-key use work
codex-key work                  # use 的兼容简写
codex-key backup
codex-key add --name work --url https://api.example.com/v1 --key 'YOUR_API_KEY' --activate

注意：--key 会进入 shell 历史。日常新增更推荐使用 TUI，Key 输入默认隐藏。

Codex 配置要求

激活配置时，程序会更新 ~/.codex/config.toml 中以下任一 provider 段内已有的 base_url：

[model_providers.OpenAI]
base_url = "https://api.example.com/v1"

或：

[model_providers.codex_local_access]
base_url = "https://api.example.com/v1"

如果两段都存在，两处会一起更新；其他 TOML 段不会被改动。如果找不到可更新的 base_url，程序会停止激活并保留原文件。

可用 CODEX_KEY_DIR 指向测试目录或非默认 Codex 配置目录：

CODEX_KEY_DIR=/path/to/codex-config codex-key

数据与安全

• API Key 按 Codex 所需格式以明文保存在 ~/.codex/auth-*.json，文件权限为 0600
• 运行时索引是 ~/.codex/key-profiles.json，不包含 Key，只引用对应 auth 文件
• 删除的密钥文件移动到 ~/.codex/key-trash/，不会立即永久删除
• codex-key backup 生成的 ZIP 包含明文 Key，权限为 0600，请勿上传或提交到 Git
• 项目仓库不会读取、复制或上传你的配置；连接测试只向你填写的 API URL 发送 Bearer Key

开发与打包

make test     # 运行单元测试与真实 PTY 终端回归测试
make dist     # 生成 tar.gz 与 zip 发布包
make install  # 安装当前源码

卸载

./uninstall.sh

卸载只删除程序，保留 ~/.codex 中的配置、Key、回收站和备份。

License

MIT