配置方案是 a4agent 的核心管理单元:一张卡片对应一套完整的「服务商 + API Key + 模型 + 应用目标」组合,点击卡片即可把这套组合写入目标工具的配置文件,几秒完成换服务商、换模型。自 0.5.1 起,应用目标只保留 Claude Code 与 Codex 两端——其余端的应用都自带完整的供应商配置界面,由用户自行配置更快也更准。本文章介绍配置方案的字段构成、卡片化管理、应用目标的组合规则、一键切换的完整流程,以及切换前的自动备份与切换后的生效方式。

1. 配置方案是什么

每个配置方案由以下字段组成,全部保存在本地 SQLite 数据库中:

字段 说明
名称 卡片显示名,自定义,如「DeepSeek 主力」「智谱备用」
服务商 关联一条服务商记录(含 API 地址与协议类型),见服务商管理与预置模板
API Key 使用 Windows DPAPI 加密后存入数据库,任何接口都不回显明文
模型 切换时写入目标配置文件的模型名,如 deepseek-v4-flash
应用目标 claude / codex 二选一或全选,逗号组合,决定这次切换写哪些工具的配置
生效状态 同一时刻至多一个方案处于「使用中」,界面上绿色高亮标识

两个历史字段的说明:

历史字段 现状
max_tokens 原为 dsh 单次输出上限。0.5.1 移除 dsh 目标后已无实际作用,字段与库中的数据保留不做破坏性迁移,但界面不再暴露、切换时不再使用
dsh / zcode / pi 目标值 0.5.1 起读入时静默丢弃,卡片上的目标勾选只剩 Claude Code 与 Codex

API Key 的加密存储与密钥不回显机制详见安全设计;数据落盘位置见数据目录与日志说明。

2. 配置方案的卡片化管理

2.1 界面布局

主界面共八个页签(0.7.0 起新增「设备」页),首个即为「配置方案」;0.6.6 起「当前生效」状态与「新增配置」按钮从全局顶栏归位到本页页头。方案以自适应卡片网格展示,当前生效的方案以主题色描边加柔和光晕突出显示,右上角带「使用中」徽章,一眼即可确认当前用的是哪套配置。

2.2 增改删与一键切换

操作 入口 说明
新增方案 配置方案页「新增配置」 选择服务商(支持按名称关键字实时搜索)、填入 API Key 与模型名、勾选应用目标
编辑方案 卡片上的「编辑」按钮 修改名称、Key、模型或目标组合
删除方案 卡片上的「删除」按钮 仅删除这张卡片,不影响服务商与其他方案
一键切换 卡片上的「切换」按钮 把该方案写入所选目标的配置文件,详见第 4 节

2.3 关联服务商被删除的保护

若某个方案关联的服务商已被删除,切换该方案时会得到明确报错「该配置关联的服务商已被删除,请先编辑或删除此配置方案」,不会产生任何半写入状态。此时编辑该方案换一个服务商,或直接删除该方案即可。

3. 应用目标多选

每个配置方案可以同时勾选两个应用目标,切换时按目标逐一写入:

应用目标 写入的配置文件 生效方式
Claude Code ~/.claude/settings.json 重启 Claude Code 后生效,界面可一键重启
Codex ~/.codex/config.toml(另维护 models.json 模型目录) 重启 Codex 后生效

组合规则上有一条硬约束:Codex 目标必须搭配 OpenAI 兼容类型的服务商。Codex 使用 OpenAI Responses 接口,无法消费 Anthropic 协议端点。若选择了 Anthropic 类型服务商又勾选了 Codex 目标,切换会在写任何文件之前直接失败并提示,例如:

Codex 需要 OpenAI 兼容接口,请为「智谱主力」选择 OpenAI 兼容的服务商
graph LR A[点击切换] --> B{读取目标
targets} B -->|仅 claude| C[Anthropic 或
OpenAI 兼容均可] B -->|含 codex| 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 配置已写入但整体报错的半生效状态。

3.1 为什么只有这两个目标

判定标准只有一条:目标应用是否自带完整的供应商配置界面。自带的就不代管——外部写配置文件既不省事(用户点几下更快),又有额外风险(界面上的能力开关、上下文窗口、启用状态外部写入时无从得知,只能填保守默认值)。

端 应用内配置能力 a4agent 的立场
Claude Code 无(纯 CLI) 代管(唯一可行路径)
Codex CLI 无(纯 CLI) 代管(唯一可行路径)
dsh Settings → Models,可选三种 API 协议 + 自动拉取模型清单 移交用户自配
ZCode 设置 → 模型供应商,双接口地址 + 按模型声明能力 移交用户自配
pi /model 直接选,models.json 热重载 移交用户自配
Qoder 9 个预置供应商 + 自定义端点 + 连通性校验 移交用户自配
OpenCode 应用内配置自己的模型与凭据 移交用户自配

需要注意,判定依据是「用户自己能配」,不是「我们读不懂它的配置」——Qoder 的模型目录虽经专有加密、外部无法写明文,但用户自己在界面里配得好好的,技术障碍不构成产品理由。

技能管理、MCP 管理、无头任务下发与通知提醒不受这条边界影响:它们不写 API 配置,只读写各自的技能目录、MCP 配置、调用 CLI 与挂载会话 hook。覆盖面自 0.7.2 起为——技能管理九端全覆盖,MCP 管理九端发现(TRAE 因配置存于加密内部库仅只读),无头任务下发为七端(WorkBuddy 与 TRAE 未接入引擎列表),会话通知按各端协议适配。

4. 一键切换流程

4.1 完整流程

graph LR A[点击切换] --> B[DPAPI 解密
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 分步说明

  1. 解密 Key:从数据库读出加密密文,经 Windows DPAPI 解密;解密失败立即中止并在日志中记录错误。
  2. 兼容性校验:检查目标组合与服务商协议是否匹配(见第 3 节),不通过则零写入返回。
  3. 先标记生效:在数据库中把该方案置为 active 后才执行写入。这一顺序是刻意的——独立运行的本地翻译代理进程需要从数据库读取「当前生效配置」来更新上游地址与密钥。
  4. 逐端写入:对每个目标依次执行「备份原配置、基于现有内容合并生成新配置、原子写覆盖」,两端各自的生成规则见本地翻译代理、ClaudeCode目标切换与Codex目标切换。
  5. 记日志:无论成功失败都写入 switch_logs 表,包含时间、状态与详情,便于追溯。
  6. 可选重启:目标含 Claude Code 且勾选重启时,自动探测并重启进程;Codex 由用户手动重启。

4.3 合并式写入示例

写入采用合并式更新,只覆盖 a4agent 托管的字段,用户手工维护的其他配置原样保留。以 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 的写入同理,详见Codex目标切换。

自 0.3.0 起,「本地模型」页支持一键创建指向本地推理服务的配置方案(「接入配置方案」按钮),创建后与云端方案同样出现在本页卡片列表,切换即用本地模型,详见本地模型推理控制台。

5. 自动备份与回滚

每次修改目标配置文件之前,a4agent 都会把原文件完整复制到数据目录的 backups/ 下,各类文件独立滚动保留最近 5 份:

备份文件名 对应原文件
settings.时间戳.json.bak ~/.claude/settings.json
codex.config.时间戳.toml.bak ~/.codex/config.toml

此外还有一处永不滚动清理的特殊备份:0.5.1 移除 dsh / ZCode / pi 代管时,清理动作前会把相关配置永久快照到 backups/pre-switch-removal/,这是那次变更唯一的兜底,详见dsh目标切换。

即使配置文件在此期间被其他程序改动过,改动前的版本也会先入备份再写入,不丢失任何历史状态。需要手动回滚时,把对应的 .bak 文件复制回原路径即可。

备份目录的实际位置随运行方式不同:安装版在 %APPDATA%\a4agent\backups\,开发模式在项目的 backend/database/backups/,详见数据目录与日志说明。

所有写入均为原子操作:先写临时文件并强制刷盘,再用操作系统级替换覆盖目标文件,写入中途断电或崩溃也不会损坏原配置。

6. 切换后的生效方式

两个工具读取配置的时机不同,切换后的生效方式也不同:

应用目标 生效条件 a4agent 提供的辅助
Claude Code 进程启动时读取一次 切换时可勾选「一键重启」:用 CIM 精确匹配命令行包含 claude 的进程,结束后在新终端重新拉起,最多等待 10 秒验证新进程出现
Codex 启动时读取 界面明确提示「重启 Codex 后生效」

一键重启只精确匹配命令行中包含 claude 的进程,不会误杀无关的 Node.js 进程;若本机未检测到运行中的 Claude Code,会如实提示而不会盲目拉起。

7. 常见问题

问:切换中途失败,会不会留下写了一半的配置文件?

答:不会,有两层保护。其一,兼容性校验放在所有写入之前,不通过就零写入返回;其二,每一端的写入都是「临时文件 + 原子替换」,不存在半截文件。失败详情会记录到切换日志与日志文件中,便于排查。

问:为什么切换时先把方案标记为生效,再写配置文件?

答:因为本地翻译代理是独立于主程序的常驻进程,它靠轮询数据库中的「当前生效配置」来获知上游地址与密钥。先标记生效,代理进程才能在配置写入的同时拿到最新上游信息,两端保持一致。

问:可以两个方案同时生效吗?

答:不能。配置激活操作使用进程内互斥锁串行化,「使用中」状态全局唯一;并发点击多张卡片的切换也只会按顺序生效,最终以最后一次为准,不会出现两套配置交叉写入。

问:为什么 dsh / ZCode / pi / Qoder 不能勾选为切换目标了?

答:0.5.1 起 a4agent 只为没有图形配置界面的 CLI(Claude Code、Codex)代管 API 配置,其余端一律由用户在应用内自配:它们都自带完整的供应商界面,用户点几下更快,也避免外部写文件时无从得知能力开关与上下文窗口而只能填保守默认值。此前由 a4agent 写入的托管条目会在升级后自动清理(清理前先做永久快照),你自己配的内容一概不动,详见dsh目标切换。

问:不切 API,还能用 a4agent 管这些端吗?

答:能,而且覆盖面更广:技能管理自 0.7.2 起覆盖九端,无头任务下发覆盖七端引擎(WorkBuddy 与 TRAE 未接入),会话通知覆盖 Claude Code / Codex / ZCode / Qoder / WorkBuddy / dsh 六端 hook 加 OpenCode 服务监听。这些能力都直接使用你在应用内配好的配置,不需要 a4agent 代写。

问:max_tokens 字段去哪了?

答:它原本只为 dsh 目标服务(规避 dsh 默认 256000 超出上游上限)。dsh 目标移交后该字段已无作用,界面不再暴露;库里的旧数据原样保留,不做破坏性迁移。