CodexSwitch 架构说明

更新时间：2026-04-01 作用：明确 CodexSwitch 的长期目标架构，避免再次把它做成单一 Codex 小工具

先说结论

CodexSwitch 更接近一类成熟的“配置切换器”，类似本地 hosts 切换工具。

它的核心不应该是：

一堆运行时魔法
临时拼接命令
只会改某一段配置

它更合理的目标应该是：

一个本地优先的多客户端 AI 配置文件切换器。

也就是说：

官网 也是一套配置
中转 / Relay 也是一套配置
第三方兼容端 也是一套配置
工具负责保存这些配置、预览差异、备份、切换、回滚

正确心智模型

以后不要把一个 profile 理解成“几项表单字段”。

更稳的理解是：

一个 profile = 一组目标配置文件的模板 + 元数据。

例如 Codex / OpenAI 官方 可以是：

config.toml
auth.json

Codex / 某个中转 也是：

config.toml
auth.json

差别只是：

base_url
wire_api
model
auth key

所以工具的本质应该是：

保存多套 profile 文件模板
激活前预览“哪些目标文件会被替换”
激活时先备份当前文件
再把目标 profile 渲染后的文件写入本机
记录当前激活的是哪一套
允许一键回滚

这里有一个边界必须写清楚：

auth.json 这类纯认证文件，适合整文件替换
config.toml 这类混合了用户状态的文件，不一定适合整文件替换

例如当前 ~/.codex/config.toml 里还包含：

[projects.*]
[notice]
[features]

这些内容不应该因为切换官网或中转就被抹掉。

核心分层

text

CodexSwitch
├── Profile Store
│   ├── Profile Metadata
│   ├── Managed File Templates
│   └── Presets / Placeholders
├── Activation Engine
│   ├── Render
│   ├── Diff Preview
│   ├── Backup
│   ├── Apply
│   └── Rollback
├── Client Adapters
│   ├── Codex Adapter
│   └── Claude Adapter
└── Interaction Adapters
    ├── CLI
    └── Desktop GUI

1. Profile Store

这一层不负责“怎么启动客户端”，而负责“这套配置长什么样”。

每个 profile 至少包含：

name
client
provider_mode
provider_name
target_platform
managed_files
render_vars
notes

其中最关键的是：

managed_files
- 表示这个 profile 会管理哪些目标文件
render_vars
- 表示模板里的变量，比如 base_url、api_key_env、model

也就是说，GUI 里的表单只是 profile 的编辑入口，真正要被保存的是：

元数据
文件模板
模板变量

2. Activation Engine

这是整个产品真正的核心。

它负责：

根据 profile 渲染出目标文件
计算激活前 diff
备份当前目标文件
写入新文件
记录当前激活状态
支持回滚

一个稳妥的激活流程应该是：

text

选择 profile
→ 预览将修改的文件
→ 预览关键差异
→ 创建备份快照
→ 写入目标文件
→ 记录激活状态

这也是为什么它更像 SwitchHosts 一类工具，而不是传统“设置页”。

但在实现上要再细分两类策略：

full replace
- 适合 auth.json 这类纯配置文件
managed patch
- 适合 config.toml 这类混合文件
- 只替换受工具管理的字段和区块
- 保留 projects、notice、features 等本机状态

3. Client Adapters

Codex Adapter

当前已知目标文件：

~/.codex/config.toml
~/.codex/auth.json

这类客户端很适合做成：

官方模板
中转模板
第三方兼容模板

然后激活时整套切换。

更准确地说：

auth.json 可以整文件替换
config.toml 更适合“受控 patch + 保留用户区块”

Claude Adapter

目标文件要先厘清：

~/.claude.json
~/.claude/ 下是否还有稳定可管理文件

对 Claude 来说，当前更稳的做法是：

先明确能被稳定管理的文件集合
再进入“文件模板切换”体系

如果某些客户端没有稳定文件模型，再退到运行时覆盖。

也就是说：

文件切换 应该是主路径
运行时覆盖 是兼容路径，不该反过来变成产品核心

4. 官网 / 中转 / 第三方到底是什么

从产品角度，不应该把它们理解成三套完全不同的技术路线。

更准确地说：

官网
- 是一套默认 profile
中转
- 是一套以官网模板为基础修改后的 profile
第三方兼容
- 是一套带预填规则和说明的 profile

例如你当前机器上的 Codex 配置，实际就是：

provider = OpenAI
base_url = 某个中转地址
auth.json = OPENAI_API_KEY

这就说明很多“中转站配置”，本质上只是：

沿用同一套目标文件
替换几个关键字段

所以从产品建模上：

官网不是特殊逻辑
中转也不是特殊逻辑
它们都只是 profile

5. 为什么不能走“随便改几项字段”的半抽象模型

如果只把 profile 存成：

base_url
api_key
model

这种纯字段模型，长期会碰到几个问题：

用户不知道切换到底改了哪些真实文件
某些客户端的配置不止一个文件
某些第三方兼容端会有额外字段
GUI 看起来像表单，但产品本质其实是文件切换

所以更稳的模型应该是：

表单用于编辑
文件模板才是最终激活对象

6. 平台差异

平台差异不是产品的主模型，但必须进入适配层。

至少要区分：

macOS
Linux
Windows

同一个 profile 在不同平台下，可能是：

模板相同
目标路径不同

具体矩阵见：

PLATFORM_PATH_MATRIX.md

7. 当前产品方向修正

当前已经做过一版偏“运行时覆盖”的抽象，这不是完全错，但不是主方向。

从现在开始，更稳的产品方向应该是：

主路径
- 文件模板管理
- 预览
- 备份
- 激活
- 回滚
辅路径
- 运行时覆盖
- 只用于没有稳定文件结构的客户端

8. 下一步正确顺序

先把 Codex 收成完整的“文件模板切换器”
明确 官网 profile、中转 profile、第三方 profile 的模板结构
在 GUI 里把“会改哪些文件”做成一等能力
再梳理 Claude 的稳定文件模型
最后才考虑更复杂的运行时启动器集成

CodexSwitch 架构说明 ​

先说结论 ​

正确心智模型 ​

核心分层 ​

1. Profile Store ​

2. Activation Engine ​

3. Client Adapters ​

Codex Adapter ​

Claude Adapter ​

4. 官网 / 中转 / 第三方到底是什么 ​

5. 为什么不能走“随便改几项字段”的半抽象模型 ​

6. 平台差异 ​

7. 当前产品方向修正 ​

8. 下一步正确顺序 ​