66 lines
3.8 KiB
Markdown
66 lines
3.8 KiB
Markdown
# cdxs
|
||
|
||
`cdxs` 是一个面向 Codex 的账号、home、会话和账号状态同步管理工具。
|
||
|
||
它把多个 Codex OAuth / API Key 账号保存在本地，再按需写回 Codex 使用的 `auth.json`。同时，它可以管理多个独立 `CODEX_HOME`，避免手动搬运认证文件和会话状态。
|
||
|
||
## 简介
|
||
|
||
Codex 的认证和会话状态都来自 `CODEX_HOME`。`cdxs` 做的是在这个目录外面加一层可操作的管理能力：
|
||
|
||
- 账号管理：导入已有 `auth.json`，通过 OAuth 或 API Key 登录，切换当前账号，并在需要时刷新 OAuth token。
|
||
- 配额缓存：列出账号时自动刷新过期的 OAuth 配额缓存。
|
||
- Home 管理：创建命名的 `CODEX_HOME`，并绑定到指定账号。
|
||
- 命令运行：用指定账号或 home 运行 `codex exec`，只为该进程设置 `CODEX_HOME`。
|
||
- 会话管理：查看会话、统计 token 和文件信息、移入可恢复垃圾箱、恢复会话、修复缺失的会话索引。
|
||
- 线程同步：在多个受管理 home 之间补齐缺失的会话线程。
|
||
- 状态同步：运行轻量 HTTP 服务，在多台机器之间推送或拉取账号状态。
|
||
|
||
管理 Codex 登录信息本地文件。
|
||
|
||
## 存储
|
||
|
||
Codex home 的解析顺序：
|
||
|
||
1. `--codex-home`
|
||
2. `CODEX_HOME`
|
||
3. `~/.codex`
|
||
|
||
主要文件：
|
||
|
||
- `auth.json`：Codex 认证文件，由账号切换或运行命令时写入。
|
||
- `cdxs.toml`：`cdxs` 的本地状态，保存账号、home、同步配置和元数据。
|
||
- `state_5.sqlite`：Codex 会话数据库。
|
||
- `session_index.jsonl`：Codex 会话列表索引。
|
||
- `sessions/`：Codex rollout JSONL 文件。
|
||
- `cdxs-trash/`：会话垃圾箱，用于可恢复删除。
|
||
|
||
会话修复、隐藏、恢复和同步可能修改 Codex 会话状态；写入前会备份相关状态文件。
|
||
|
||
## 常用快捷命令
|
||
|
||
- `cdxs`：列出账号，并自动刷新过期配额缓存。
|
||
- `cdxs -f`：强制刷新账号配额后再列出。
|
||
- `cdxs show <账号>`：显示单个账号详情，等价于 `cdxs account show <账号>`。
|
||
- `cdxs alias set <别名> <账号>`：给任意 OAuth 或 API Key 账号设置别名。
|
||
- `cdxs alias list`：列出所有账号别名。
|
||
- `cdxs alias remove <别名或账号>`：删除指定账号的别名。
|
||
- `cdxs switch`：不带参数时自动选择可用配额最优的账号。
|
||
- `cdxs switch <账号或别名>`：切换到指定账号，OAuth 和 API Key 账号都可通过 alias 切换。
|
||
- `cdxs switch A --model <model> --effort <effort> --name OpenAI`：切换时更新该账号默认模型、思考程度；`--name` 仅用于 API 模式的 provider name。
|
||
- `cdxs exec <账号> -- --model gpt-5 "hello"`：用指定账号运行 `codex exec`。
|
||
- `cdxs exec <home> --home --temp -- --model gpt-5 "hello"`：基于指定受管 home 建立一次性临时 `CODEX_HOME` 后运行 `codex exec`。
|
||
- `cdxs login --api <key> --base-url <url> --alias A --model <model> --name OpenAI --switch`：保存 API Key 账号并可选切换；`base-url` 为空时使用 OpenAI 默认 API。
|
||
- `cdxs login api --key <key> --base-url <url> --alias A --model <model> --name OpenAI --switch`：同上，保留旧的子命令形式。
|
||
- `cdxs remove <账号>`：删除账号，等价于 `cdxs account remove <账号>`。
|
||
- `cdxs pull`：从同步服务拉取账号状态，等价于 `cdxs sync pull`。
|
||
- `cdxs push`：推送账号状态到同步服务，等价于 `cdxs sync push`。
|
||
|
||
账号 alias 保存在账号记录里，因此会随 `cdxs push` 推送到同步服务，并随 `cdxs pull` 从同步服务拉取回来。
|
||
|
||
## 同步服务
|
||
|
||
内置同步服务只保存每个用户的账号状态，并提供登录、拉取、推送接口。它同步的是可迁移的 `cdxs` 账号状态，不同步整个 Codex home。
|
||
|
||
项目包含 `Dockerfile` 和 `compose.yml`。默认容器监听 `8765`，数据目录为 `/data`。
|