配置方案是 a4api 的核心管理单元：一张卡片对应一套完整的「服务商 + API Key + 模型 + 应用目标」组合，点击卡片即可把这套组合写入 Claude Code、Codex 与 dsh（DeepSeek Harness）的目标配置文件，几秒完成换服务商、换模型。本文章介绍配置方案的字段构成、卡片化管理、应用目标的组合规则、一键切换的完整流程，以及切换前的自动备份与切换后的生效方式。
1. 配置方案是什么
每个配置方案由以下字段组成，全部保存在本地 SQLite 数据库中：
| 字段 | 说明 |
|---|---|
| 名称 | 卡片显示名，自定义，如「DeepSeek 主力」「智谱备用」 |
| 服务商 | 关联一条服务商记录（含 API 地址与协议类型），见服务商管理与预置模板 |
| API Key | 使用 Windows DPAPI 加密后存入数据库，任何接口都不回显明文 |
| 模型 | 切换时写入目标配置文件的模型名，如 deepseek-v4-flash |
| 应用目标 | claude / codex / dsh 三选N，逗号组合，决定这次切换写哪些工具的配置 |
| max_tokens | dsh 单次输出上限（可选）。留空时自动兜底为 131072，避免 dsh 默认值超出上游上限被打回 |
| 生效状态 | 同一时刻至多一个方案处于「使用中」，界面上绿色高亮标识 |
2. 配置方案的卡片化管理
2.1 界面布局
主界面顶部有两个页签：「配置方案」与「供应商管理」。配置方案以自适应卡片网格展示，当前生效的方案以主题色描边加柔和光晕突出显示，右上角带「使用中」徽章，一眼即可确认当前用的是哪套配置。
2.2 增改删与一键切换
| 操作 | 入口 | 说明 |
|---|---|---|
| 新增方案 | 配置方案页「新增配置」 | 选择服务商（支持按名称关键字实时搜索）、填入 API Key 与模型名、勾选应用目标 |
| 编辑方案 | 卡片上的「编辑」按钮 | 修改名称、Key、模型、目标组合或 max_tokens |
| 删除方案 | 卡片上的「删除」按钮 | 仅删除这张卡片，不影响服务商与其他方案 |
| 一键切换 | 卡片上的「切换」按钮 | 把该方案写入所选目标的配置文件，详见第 4 节 |
2.3 关联服务商被删除的保护
若某个方案关联的服务商已被删除，切换该方案时会得到明确报错「该配置关联的服务商已被删除，请先编辑或删除此配置方案」，不会产生任何半写入状态。此时编辑该方案换一个服务商，或直接删除该方案即可。
3. 应用目标多选
每个配置方案可以同时勾选多个应用目标，切换时按目标逐一写入：
| 应用目标 | 写入的配置文件 | 生效方式 |
|---|---|---|
| Claude Code | ~/.claude/settings.json |
重启 Claude Code 后生效，界面可一键重启 |
| Codex | ~/.codex/config.toml（另维护 models.json 模型目录） |
重启 Codex 后生效 |
| dsh | ~/.dsh/settings.yaml + ~/.dsh/.credentials.yaml |
watcher 热加载，新会话即生效 |
组合规则上有一条硬约束：Codex 与 dsh 目标必须搭配 OpenAI 兼容类型的服务商。Codex 使用 OpenAI Responses 接口、dsh 使用 OpenAI Chat Completions 接口，两者都无法消费 Anthropic 协议端点。若选择了 Anthropic 类型服务商又勾选了这两个目标，切换会在写任何文件之前直接失败并提示，例如：
Codex 需要 OpenAI 兼容接口，请为「智谱主力」选择 OpenAI 兼容的服务商
targets} B -->|仅 claude| C[Anthropic 或
OpenAI 兼容均可] B -->|含 codex 或 dsh| D{服务商是否
OpenAI 兼容} D -->|是| E[继续切换流程] D -->|否| F[直接报错
不写任何文件] C --> E style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style C fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style D fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style E fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style F fill:#fadbd8,stroke:#c0392b,stroke-width:2px
这一校验发生在解密 Key 之后、标记生效之前，属于「干净失败」：不会出现 Claude 配置已写入但整体报错的半生效状态。
4. 一键切换流程
4.1 完整流程
API Key] B --> C{目标与协议
兼容校验} C -->|不通过| D[报错返回
零写入] C -->|通过| E[数据库标记
该方案生效] E --> F[逐端处理：
先备份再合并生成再原子写] F --> G[写入切换日志
switch_logs] G --> H{目标含
claude?} H -->|勾选重启| I[CIM 探测并
重启 Claude Code] H -->|未勾选| J[完成
按端提示生效方式] I --> J style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ffecd6,stroke:#e67e22,stroke-width:2px style C fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style D fill:#fadbd8,stroke:#c0392b,stroke-width:2px style E fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style F fill:#fdebd0,stroke:#b7950b,stroke-width:2px style G fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style H fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style I fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style J fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
4.2 分步说明
- 解密 Key：从数据库读出加密密文，经 Windows DPAPI 解密；解密失败立即中止并在日志中记录错误。
- 兼容性校验：检查目标组合与服务商协议是否匹配（见第 3 节），不通过则零写入返回。
- 先标记生效：在数据库中把该方案置为 active 后才执行写入。这一顺序是刻意的——独立运行的本地翻译代理进程需要从数据库读取「当前生效配置」来更新上游地址与密钥。
- 逐端写入：对每个目标依次执行「备份原配置、基于现有内容合并生成新配置、原子写覆盖」，三端各自的生成规则见本地翻译代理与三篇目标文档。
- 记日志：无论成功失败都写入
switch_logs表，包含时间、状态与详情，便于追溯。 - 可选重启：目标含 Claude Code 且勾选重启时，自动探测并重启进程；Codex 由用户手动重启；dsh 无需任何操作。
4.3 合并式写入示例
写入采用合并式更新，只覆盖 a4api 托管的字段，用户手工维护的其他配置原样保留。以 Claude Code 为例，假设现有 ~/.claude/settings.json 为：
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "旧 Key",
"ANTHROPIC_BASE_URL": "https://old.example.com",
"MY_CUSTOM_VAR": "keep-me"
},
"model": "old-model",
"permissions": { "allow": ["Bash(git*)"] },
"hooks": { "Stop": [] }
}
切换到新的 Anthropic 类型服务商后：
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "新 Key",
"ANTHROPIC_BASE_URL": "https://api.newprovider.com",
"MY_CUSTOM_VAR": "keep-me"
},
"model": "new-model",
"alwaysThinkingEnabled": false,
"permissions": { "allow": ["Bash(git*)"] },
"hooks": { "Stop": [] }
}
env.MY_CUSTOM_VAR、permissions、hooks 全部保留，只有托管字段被更新。Codex 与 dsh 的写入同理，详见ClaudeCode目标切换、Codex目标切换与dsh目标切换。
5. 自动备份与回滚
每次修改目标配置文件之前，a4api 都会把原文件完整复制到数据目录的 backups/ 下，各类文件独立滚动保留最近 5 份：
| 备份文件名 | 对应原文件 |
|---|---|
settings.时间戳.json.bak |
~/.claude/settings.json |
codex.config.时间戳.toml.bak |
~/.codex/config.toml |
dsh.settings.时间戳.yaml.bak |
~/.dsh/settings.yaml |
dsh.credentials.时间戳.yaml.bak |
~/.dsh/.credentials.yaml |
即使配置文件在此期间被其他程序改动过，改动前的版本也会先入备份再写入，不丢失任何历史状态。需要手动回滚时，把对应的 .bak 文件复制回原路径即可。
备份目录的实际位置随运行方式不同：安装版在
%APPDATA%\a4api\backups\，开发模式在项目的backend/database/backups/，详见数据目录与日志说明。
所有写入均为原子操作：先写临时文件并强制刷盘，再用操作系统级替换覆盖目标文件，写入中途断电或崩溃也不会损坏原配置。
6. 切换后的生效方式
三个工具读取配置的时机不同，切换后的生效方式也不同：
| 应用目标 | 生效条件 | a4api 提供的辅助 |
|---|---|---|
| Claude Code | 进程启动时读取一次 | 切换时可勾选「一键重启」：用 CIM 精确匹配命令行包含 claude 的进程，结束后在新终端重新拉起，最多等待 10 秒验证新进程出现 |
| Codex | 启动时读取 | 界面明确提示「重启 Codex 后生效」 |
| dsh | 文件 watcher 热加载 | 无需任何操作，切换后新会话即生效 |
一键重启只精确匹配命令行中包含
claude的进程，不会误杀无关的 Node.js 进程；若本机未检测到运行中的 Claude Code，会如实提示而不会盲目拉起。
7. 常见问题
问：切换中途失败，会不会留下写了一半的配置文件？
答：不会，有两层保护。其一，兼容性校验放在所有写入之前，不通过就零写入返回；其二，每一端的写入都是「临时文件 + 原子替换」，不存在半截文件。失败详情会记录到切换日志与日志文件中，便于排查。
问：为什么切换时先把方案标记为生效，再写配置文件？
答：因为本地翻译代理是独立于主程序的常驻进程，它靠轮询数据库中的「当前生效配置」来获知上游地址与密钥。先标记生效，代理进程才能在配置写入的同时拿到最新上游信息，两端保持一致。
问：可以两个方案同时生效吗？
答：不能。配置激活操作使用进程内互斥锁串行化，「使用中」状态全局唯一；并发点击多张卡片的切换也只会按顺序生效，最终以最后一次为准，不会出现两套配置交叉写入。
问：max_tokens 留空会发生什么？
答：仅对 dsh 目标有意义。留空时写入安全兜底值 131072——dsh 适配器默认的 256000 超出多数上游（如智谱）131072 的输出上限，请求会被直接打回，因此没有显式值时绝不能放行默认值。显式填写的值优先级最高。
举手提问