cdxs/README.md

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 账号的 Codex 使用配额，并缓存到本地。
• Home 管理：创建命名的 CODEX_HOME，并绑定到指定账号。
• 命令运行：用指定账号或 home 启动子进程，只为该进程设置 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 list：列出账号，并自动刷新过期配额缓存。
• cdxs show：列出账号，但不请求配额接口。
• cdxs switch：不带参数时自动选择可用配额最优的账号。
• cdxs switch <账号>：切换到指定账号。
• cdxs login api --key <key> --base-url <url> --switch：保存 API Key 账号并可选切换；base-url 为空时使用 OpenAI 默认 API。
• cdxs remove <账号>：删除账号，等价于 cdxs account remove <账号>。
• cdxs pull：从同步服务拉取账号状态，等价于 cdxs sync pull。
• cdxs push：推送账号状态到同步服务，等价于 cdxs sync push。

同步服务

内置同步服务只保存每个用户的账号状态，并提供登录、拉取、推送接口。它同步的是可迁移的 cdxs 账号状态，不同步整个 Codex home。

项目包含 Dockerfile 和 compose.yml。默认容器监听 8765，数据目录为 /data。