1. 项目概述:统一AI开发环境的工程实践
最近完成了一个技术整合项目,目标是将Codex CLI和Claude Code两套AI开发工具通过LiteLLM代理层进行统一接入。这个方案不仅实现了多客户端共享同一模型后端,更重要的是保留了Claude Code的核心工程能力。经过实践验证,最终形成了一套可复用的工程方案,显著提升了AI开发环境的统一性和可维护性。
2. 技术架构设计
2.1 整体架构方案
项目采用三层架构设计:
- 客户端层:Codex CLI和Claude Code作为前端交互界面
- 代理层:LiteLLM作为统一代理,同时暴露OpenAI和Anthropic兼容接口
- 模型层:Azure GPT-5.4作为统一推理后端
mermaid复制graph LR
A[Codex CLI] --> B[LiteLLM Proxy]
C[Claude Code] --> B
B --> D[Azure GPT-5.4]
2.2 协议兼容性处理
LiteLLM的关键价值在于其多协议兼容能力:
- 对Codex CLI提供
/v1兼容OpenAI API - 对Claude Code提供
/v1/messages兼容Anthropic API - 统一模型别名
gpt54屏蔽后端差异
3. 核心实现细节
3.1 LiteLLM配置管理
配置文件~/litellm_config.yaml的核心参数:
yaml复制general_settings:
master_key: sk-proxy
drop_params: true # 过滤不支持的参数
model_list:
- model_name: gpt54
litellm_params:
model: openai/gpt-5.4
api_base: https://your-azure-resource.openai.azure.com/openai/v1
api_key: your_azure_key
关键配置说明:
drop_params: true确保不同客户端的额外参数不会导致请求失败- 模型别名机制实现客户端配置与具体模型解耦
3.2 客户端接入方案
Codex CLI接入:
bash复制export OPENAI_API_BASE="http://localhost:4000/v1"
export OPENAI_API_KEY="sk-proxy"
codex -m gpt54
Claude Code接入:
bash复制export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_MODEL="gpt54"
claude
4. 工具链兼容性治理
4.1 工具兼容性分析
Claude Code的工具分为两类:
- 内置工具:Bash、Edit、Read等基础功能
- MCP工具:通过本地服务扩展的功能
测试发现:
- 所有内置工具均可正常使用
- 约70%的MCP工具可直接兼容
- 部分MCP工具因schema差异需要适配
4.2 白名单治理策略
采用渐进式兼容方案:
- 首先确保核心内置工具可用
- 对MCP工具进行逐个验证
- 将兼容工具加入白名单
- 对不兼容工具单独处理
白名单配置示例(.claude/mcp-gpt54.json):
json复制{
"allowed_mcps": ["playwright"],
"blocked_mcps": ["pencil"]
}
5. 工程化实践
5.1 统一启动脚本
创建标准化启动命令:
bash复制# LiteLLM代理
alias llm='scripts/start-litellm.sh'
# Codex客户端
alias codex_new='OPENAI_API_BASE="http://localhost:4000/v1" codex -m gpt54'
# Claude客户端
alias claude_new='ANTHROPIC_BASE_URL="http://localhost:4000" claude'
5.2 环境迁移方案
将配置抽象为ai-cli-kit工具包:
code复制ai-cli-kit/
├── bin/ # 可执行脚本
├── templates/ # 配置模板
├── docs/ # 文档
└── init.sh # 环境初始化脚本
迁移时只需:
- 克隆仓库
- 运行
./init.sh - 输入各平台API Key
- 自动生成完整环境
6. 实践经验总结
6.1 关键收获
- 协议兼容比模型兼容更重要:实际阻碍是工具schema而非模型能力
- 渐进式兼容更可行:全量兼容成本过高,白名单策略更实用
- 统一配置带来长期收益:虽然初期投入较大,但显著降低维护成本
6.2 典型问题解决方案
问题1:Claude Code返回"Invalid schema for function"
解决:
- 检查具体工具定义
- 对比原生Anthropic和OpenAI的schema差异
- 必要时将该工具加入隔离名单
问题2:SSE流中断
解决:
- 确保LiteLLM的
stream: true配置正确 - 检查代理层是否完整转发SSE事件
- 测试直接curl请求验证基础功能
7. 后续优化方向
- MCP工具适配器:为高价值不兼容工具开发schema转换层
- 自动化测试套件:建立工具兼容性自动化验证流程
- 性能监控:增加请求延迟和成功率监控
- 多模型支持:扩展对Gemini等其他模型的支持
这个方案的价值不仅在于技术实现,更在于建立了一套可持续演进的AI开发环境治理模式。通过将碎片化的配置和协议统一收敛,显著提升了开发体验和维护效率。
