a4apiClaudeCode目标切换

Claude Code 是 a4api 的默认应用目标：配置方案勾选 claude 目标后，切换动作会把服务商、API Key 与模型写入 ~/.claude/settings.json。官方 Claude Code 原生只认 Anthropic 协议，因此 Anthropic 类型服务商直连上游、OpenAI 兼容服务商经本地翻译代理中转，两种形态对 Claude Code 完全透明。本文章介绍该目标的托管字段、合并式写入保护、一键重启的进程探测逻辑与常见问题。

1. 写入哪个文件、写哪些字段

目标文件固定为用户主目录下的 ~/.claude/settings.json（可用环境变量 A4API_SETTINGS_PATH 覆盖，主要用于测试）。切换时只更新以下托管字段：

托管字段	写入内容
`env.ANTHROPIC_AUTH_TOKEN`	Anthropic 服务商写真实 API Key；OpenAI 兼容服务商写本地代理鉴权 token
`env.ANTHROPIC_BASE_URL`	Anthropic 服务商写上游地址；OpenAI 兼容服务商写本地代理地址
`model`	配置方案中的模型名
`alwaysThinkingEnabled`	固定写入 `false`

1.1 Anthropic 类型：直连上游

选择 Anthropic 协议服务商（如 DeepSeek-anthropic）时，配置直接指向上游：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxx",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic"
  },
  "model": "deepseek-v4-flash",
  "alwaysThinkingEnabled": false
}

1.2 OpenAI 兼容类型：经本地代理

官方 Claude Code 不识别 OpenAI 格式配置，因此 OpenAI 兼容服务商的流量必须经本地翻译代理转成 Chat Completions 后发往上游：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "本地代理鉴权 token",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:17890"
  },
  "model": "deepseek-chat",
  "alwaysThinkingEnabled": false
}

注意 ANTHROPIC_BASE_URL 指向本地代理时不带 /v1 后缀，Claude Code 会自动追加路径。代理的翻译机制见本地翻译代理。

2. 合并式写入保护

写入是「基于现有文件做合并」而非整文件重写，只覆盖第 1 节列出的托管字段；hooks、permissions、mcpServers 以及 env 中其他自定义变量全部原样保留。完整示例与前后对照见配置方案与一键切换第 4.3 节。

配合两项兜底机制：

机制	行为
自动备份	写入前把整个 settings.json 复制到数据目录 `backups/`，命名 `settings.时间戳.json.bak`，滚动保留最近 5 份
原子写入	先写临时文件并强制刷盘，再以操作系统级替换覆盖目标，杜绝半截文件

读取阶段同样有容错：文件不存在时按全新配置生成（首次使用场景）；读取支持带 BOM 的 UTF-8；若 JSON 已损坏则按空配置处理——此时更要依赖切换前的备份找回历史版本。

3. 切换后的生效与一键重启

Claude Code 在进程启动时读取一次配置，切换后需要重启才能生效。a4api 在切换完成提示里提供「一键重启」选项，流程如下：

graph LR A[配置写入完成
勾选重启] --> B[CIM 查询进程
名含 node.exe/claude.exe
且命令行含 claude] B --> C[逐个 taskkill
强制结束旧进程] C --> D[新终端窗口
重新启动 claude] D --> E{10 秒内探测到
新进程?} E -->|是| F[重启成功] E -->|否| G[提示启动超时
请检查是否已安装] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style C fill:#fadbd8,stroke:#c0392b,stroke-width:2px style D fill:#ffecd6,stroke:#e67e22,stroke-width:2px style E fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style F fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style G fill:#fdebd0,stroke:#b7950b,stroke-width:2px

设计上有两点保证安全：

精确匹配：用 CIM 查询使命令行包含 claude 的进程，而不是按映像名粗放匹配，避免误杀无关的 Node.js 进程。
不盲目拉起：若本机没有检测到运行中的 Claude Code，会如实提示「未发现运行中的 Claude Code 进程」，下次手动启动即用新配置。

不勾选重启也完全没问题：手动关闭并重新打开 Claude Code，效果一致。

4. 常见问题

问：一键重启会不会丢正在进行的对话？

答：重启采用强制结束进程的方式，正在进行中的回合会被中断；已完成的对话记录保存在 Claude Code 的会话存储里不受影响，重开后可继续或恢复会话。建议在没有任务跑的时候执行重启。

问：切换后立刻用了，为什么还是旧服务商？

答：Claude Code 只在启动时读一次配置。请重启 Claude Code（界面一键重启或手动重开）后再使用；判断是否生效最直接的办法是在 Claude Code 里发起一次请求，看模型响应方与日志。

问：我手工改过 settings.json 里的 hooks 和 permissions，切换会冲掉吗？

答：不会。合并式写入只动四个托管字段，其余键原样保留；万一出现意外，切换前的自动备份随时可以恢复。

问：为什么每次切换后 alwaysThinkingEnabled 都变成 false？

答：它是 a4api 的托管字段之一，切换时统一写入 false 以保证行为可预期。若你依赖扩展思考开关，可在切换后手工打开；后续版本的托管策略如有调整会在版本更新说明中说明。