a4api 是一个开箱即用的 Agent LLM 服务商切换工具：通过可视化界面管理「服务商 + API Key + 模型 + 应用目标」组合，一键写入 ~/.claude/settings.json、~/.codex/config.toml 与 ~/.dsh/settings.yaml，让 Claude Code、Codex 与 dsh（DeepSeek Harness）在不同服务商之间秒级切换；内置的本地翻译代理把 Anthropic 与 OpenAI Responses 协议实时翻译为 Chat Completions，让三个工具都能使用任意 OpenAI 兼容上游。本文章为文档库入口，概述项目定位、功能全景、安装与快速开始，并给出全部功能文档的导航。

源码仓库

1. 项目简介

1.1 项目定位

维度 说明
项目名称 a4api
产品形态 Windows 桌面应用（pywebview 窗口，本地渲染，可离线使用）
适用对象 Claude Code、Codex、dsh（DeepSeek Harness），可任意组合多目标
核心能力 服务商一键切换、协议翻译代理、配置安全写入、应用自更新
技术栈 Python FastAPI + SQLAlchemy/SQLite + LayUI 前端 + PyInstaller/Inno Setup 分发
运行环境 Windows 10 / 11，64 位；每用户安装，免管理员权限
开源协议 MIT
当前版本 0.1.5（详见版本更新说明）
源码地址 GitHub、Gitee、GitCode

1.2 功能全景

功能 一句话说明 详细文档
配置方案与一键切换 卡片化管理「服务商+Key+模型+目标」组合，点击即切换 配置方案与一键切换
服务商管理与预置模板 7 个预置模板开箱即用，支持自定义端点与搜索 服务商管理与预置模板
本地翻译代理 Anthropic / Responses 到 Chat Completions 的实时翻译与透传 本地翻译代理
Claude Code 目标 合并式写入 settings.json，支持进程探测与一键重启 ClaudeCode目标切换
Codex 目标 写 config.toml 与模型目录，原生直连或代理转发 Codex目标切换
dsh 目标 写 settings.yaml 与凭证文件，热加载新会话生效 dsh目标切换
安全设计 DPAPI 加密、备份原子写、CORS 白名单、日志隐私 安全设计
自动更新 签名清单验签、双源下载、防降级的一键升级 自动更新
安装升级与卸载 每用户安装包、覆盖升级保留数据 安装升级与卸载
数据目录与日志 数据库、备份、状态文件与环境变量覆盖全清单 数据目录与日志说明
版本更新说明 0.1.0 至 0.1.5 流水线式演进记录 版本更新说明

安装与使用的图文教程可参考一键切换DeepSeek Harness等Agent模型服务API 教程，本文档库侧重功能机制与参考查询。

2. 安装

2.1 下载安装

从 Release 页面下载最新 a4api-setup-<版本>.exe，双击按向导完成：每用户安装、全程无需管理员权限，自动创建开始菜单与桌面快捷方式。首次运行如遇 SmartScreen 提示，点「更多信息 → 仍要运行」即可（未做商业代码签名属正常现象）。细节与常见拦路虎见安装升级与卸载。

2.2 使用前置条件

条件 说明
Windows 10 / 11 64 位 唯一支持的桌面平台
目标工具按需安装 要切 Claude Code 就装 Claude Code，Codex 与 dsh 同理；三者互不影响
各家 API Key 在对应服务商控制台申请；本地 LLM Studio 等本地推理不需要

3. 快速开始

以「给 Claude Code 换上 DeepSeek 官方接口」为例，三步完成：

graph LR A[供应商管理页
确认预置模板] --> B[新增配置方案
选服务商填 Key 定模型] B --> C[卡片上点切换
勾选目标 claude] C --> D{需要立即生效?} D -->|是| E[一键重启
Claude Code] D -->|否| F[下次启动自然生效] 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:#ebdef0,stroke:#8e44ad,stroke-width:2px style E fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style F fill:#fdebd0,stroke:#b7950b,stroke-width:2px
  1. 选模板建方案：「供应商管理」页签里预置了 DeepSeek、智谱、OpenRouter、OpenCodeGo、本地 LLM Studio 七个模板；回到「配置方案」页新增一个方案，选服务商、粘贴 API Key、填写模型名（如 deepseek-chat）、勾选应用目标；
  2. 一键切换：在卡片上点「切换」，工具自动备份原配置并把新组合写入目标文件；当前生效的卡片会高亮标识；
  3. 重启目标工具：Claude Code 可勾选一键重启，Codex 手动重开，dsh 无需任何操作。

想同时管 Codex 和 dsh？同一个方案里把目标一起勾上即可——记得这两端要选 OpenAI 兼容类型的服务商。

4. 工作原理

4.1 架构分层

graph LR A[pywebview 桌面窗口] --> B[LayUI 前端
配置卡片/供应商管理] B --> C[FastAPI 后端
REST /api/v1] C --> D[(SQLite
a4api.db)] C --> E[config_manager
合并式读写三端配置] C --> F[proxy_standalone
独立翻译代理进程] E --> G[Claude settings.json] E --> H[Codex config.toml] E --> I[dsh settings.yaml] F --> J[OpenAI 兼容上游] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style C fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style D fill:#fdebd0,stroke:#b7950b,stroke-width:2px style E fill:#ffecd6,stroke:#e67e22,stroke-width:2px style F fill:#fadbd8,stroke:#c0392b,stroke-width:2px style G fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style H fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style I fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style J fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px
  • 前端：LayUI 构建的本地页面，随包内置、离线可用，由后端统一托管；
  • 后端：FastAPI 提供 /api/v1 的 providers / configs / switch / update 四组 REST 接口，Pydantic 强校验输入，CORS 仅放行本机；
  • 存储：单文件 SQLite，密钥经 DPAPI 加密入库，外键约束防孤儿数据；
  • 代理：需要协议翻译时拉起独立进程，仅监听 127.0.0.1 并以随机 token 鉴权。

4.2 一次切换发生了什么

点击切换后，后端解密 Key、校验目标与服务商协议匹配、先把方案标记为生效（独立代理据此获知最新上游），随后逐端执行「备份原文件、基于现有内容合并生成、原子写覆盖」，最后记录切换日志并提示各端的生效方式。全流程分步拆解见配置方案与一键切换第 4 节。

5. 源码结构

路径 内容
backend/app/main.py FastAPI 入口：CORS、路由注册、静态资源托管
backend/app/models.py / crud.py / schemas.py ORM 模型、数据库操作、请求响应校验
backend/app/config_manager.py 三端配置文件的读取、合并式生成、备份与原子写
backend/app/crypto.py Windows DPAPI 加解密
backend/app/openai_proxy.py 协议翻译核心（messages / responses / 透传三类端点）
backend/app/proxy_standalone.py 独立代理进程的生命周期管理
backend/app/updater.py 自更新：签名验签、双源下载、校验与应用
backend/app/api/v1/ providers / configs / switch / update 四组接口
backend/app/tests/ 加解密、配置生成、协议翻译、更新器等回归测试
frontend/ LayUI 前端页面与样式
desktop.py pywebview 桌面入口（含单实例互斥）
build.py / installer.iss PyInstaller 打包与 Inno Setup 安装包脚本

6. 文档导航

文档 说明
项目总览与快速开始 本文档，项目简介与快速上手
配置方案与一键切换 配置方案字段、目标多选与切换全流程
服务商管理与预置模板 预置模板清单、自定义服务商与搭配规则
本地翻译代理 三条协议链路、鉴权与进程生命周期
ClaudeCode目标切换 settings.json 托管字段与一键重启
Codex目标切换 config.toml、models.json 与直连策略
dsh目标切换 settings.yaml、max_tokens 与热加载
安全设计 全部安全机制的索引与设计意图
自动更新 签名、双源、校验与防降级
安装升级与卸载 下载安装、覆盖升级、源码运行与打包
数据目录与日志说明 数据落盘位置与路径覆盖环境变量
版本更新说明 0.1.0 至 0.1.5 流水线式演进