1. 项目概述：为什么我们需要一个统一的AI编程助手接口

如果你同时用过OpenAI的Codex（比如通过GitHub Copilot）和Anthropic的Claude Code，大概率会有一种“分裂感”。Codex在代码补全和生成上快如闪电，Claude则在代码解释、重构和复杂逻辑推理上更胜一筹。但问题是，它们分属不同的平台、不同的API、不同的调用方式。开发时，你不得不在两个终端窗口、两套环境变量、两种计费方式之间来回切换，效率大打折扣。

这个项目的核心，就是解决这种“分裂”。它利用一个名为LiteLLM的开源库，构建一个统一的命令行接口（CLI），让你能用同一种方式、同一个命令，去调用背后不同的AI编程模型。你只需要准备好各自的API Key，就能在Codex和Claude Code之间无缝切换，甚至未来可以轻松接入其他模型，实现真正的“编程自由”——根据任务类型，选择最合适的AI助手，而无需改变你的操作习惯。

我花了几天时间折腾这个方案，不是为了炫技，而是实在受不了在多个工具间疲于奔命。最终实现的效果是：在终端里，一条简单的命令，比如aicode --model claude-3-opus --prompt "优化这个Python函数"或者aicode --model gpt-4 --prompt "为这个API写个FastAPI端点"，就能得到想要的结果。整个过程透明、统一，且完全可控。

2. 核心工具选型：为什么是LiteLLM？

市面上能做模型路由和统一接口的工具不止一个，为什么我最终选择了LiteLLM？这背后有几个关键的考量点。

2.1 LiteLLM的核心优势：标准化与可扩展性

LiteLLM的本质是一个“翻译器”和“路由器”。它定义了一套统一的输入输出格式，然后将你的请求“翻译”成对应AI提供商（如OpenAI、Anthropic、Cohere等）API能理解的形式，再将返回的结果“翻译”回统一的格式给你。这样做的好处是：

• 对开发者透明：你只需要学习LiteLLM一套API，就能操作几十个模型，学习成本骤降。
• 快速切换与降级：如果某个模型（如GPT-4）额度用尽或响应慢，你可以在代码或配置中瞬间切换到另一个（如Claude 3 Sonnet），而业务逻辑代码几乎不用改。
• 成本监控统一：LiteLLM可以代理所有请求，并提供一个统一的仪表板来查看各个模型的调用量和花费，这对于管理多个API Key的团队来说至关重要。

相比之下，直接写原生API调用代码，你会被各种不同的参数名（max_tokensvsmax_tokens_to_sample）、身份验证方式（Bearer Token vsx-api-key头）和响应结构体折磨。

2.2 与其他方案的对比

在决定使用LiteLLM之前，我也评估过其他路径：

• 手动封装脚本：自己写一个Python脚本，用if-else判断模型类型，然后分别调用openai库和anthropic库。这是最直接的方法，但问题在于扩展性极差。每增加一个模型，就要修改核心逻辑，代码会迅速变得臃肿且难以维护。
• 使用LangChain：LangChain的LLM组件也提供了类似的多模型支持。但它是一个更庞大的框架，专注于构建复杂的AI应用链。对于“统一CLI调用”这个相对单一的目标来说，LangChain显得过于重型，引入了不必要的复杂性和依赖。
• 商业聚合平台：有些平台直接提供聚合API。但它们通常是黑盒，有额外的费用，并且你无法控制请求的具体细节和路由逻辑。

LiteLLM正好卡在了一个甜点区：它足够轻量（核心就是一个Python库），功能又恰好满足需求（统一调用、路由、鉴权、计费），并且是开源、可自部署的，保证了可控性。

注意：LiteLLM本身是一个库，它提供了编程接口。我们的项目目标是将它封装成一个易用的命令行工具（CLI），这才是提升日常开发效率的关键。

3. 环境准备与核心依赖安装

任何项目的第一步都是搭好舞台。这里不需要复杂的云服务，只需要一个你熟悉的开发环境。

3.1 基础Python环境配置

我强烈建议使用虚拟环境，以避免包依赖冲突。这里以venv为例，conda同理。

# 1. 创建项目目录并进入 mkdir ai-code-cli && cd ai-code-cli # 2. 创建Python虚拟环境（假设你已安装Python 3.8+） python3 -m venv venv # 3. 激活虚拟环境 # 在 macOS/Linux 上： source venv/bin/activate # 在 Windows 上： .\venv\Scripts\activate # 激活后，命令行提示符前通常会显示 (venv)

3.2 安装LiteLLM及其必要依赖

LiteLLM是核心，但我们还需要argparse或click来处理命令行参数，以及python-dotenv来安全地管理API密钥。

# 安装核心库 pip install litellm # 安装命令行工具开发辅助库，这里选用更强大的click pip install click # 安装环境变量管理库 pip install python-dotenv

安装完成后，可以通过pip list | grep litellm确认版本。我写作时使用的是litellm==1.34.2，它是一个活跃更新的项目，基本API保持稳定。

3.3 安全存储API密钥：.env文件的最佳实践

永远不要将API密钥硬编码在脚本里或上传到GitHub。标准做法是使用环境变量，而python-dotenv让这变得简单。

1. 在项目根目录创建一个名为.env的文件。
2. 将你的API密钥以键值对形式存入：

   # .env 文件内容示例 OPENAI_API_KEY=sk-your-openai-key-here ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here # 未来你可以轻松添加其他密钥，如： # GROQ_API_KEY=gsk-your-groq-key-here # TOGETHER_API_KEY=your-together-ai-key-here

3. 非常重要的一步：将.env添加到.gitignore文件中，确保它不会被意外提交。

   echo ".env" >> .gitignore

这样，我们的代码就可以安全地读取这些密钥，而你的敏感信息始终留在本地。

4. CLI工具设计与核心代码实现

有了基础环境，我们来搭建这个CLI工具的骨架和核心逻辑。我们的目标是创建一个叫aicode的命令，它至少接受两个参数：指定使用的模型（--model）和你的问题或指令（--prompt）。

4.1 项目结构规划

一个清晰的结构有助于后期维护。我的项目结构如下：

ai-code-cli/ ├── .env # 存储API密钥（本地，不上传） ├── .gitignore # 忽略.env等文件 ├── requirements.txt # 项目依赖声明 ├── aicode/ # 主包目录 │ ├── __init__.py │ ├── cli.py # CLI命令入口点 │ └── core.py # 核心的AI调用逻辑 └── setup.py # 打包安装配置（可选，用于发布为全局工具）

4.2 核心调用逻辑封装（core.py）

这是大脑所在，负责与LiteLLM交互。我们在这里处理密钥加载和统一调用。

# aicode/core.py import os from dotenv import load_dotenv import litellm from litellm import completion # 加载.env文件中的环境变量 load_dotenv() # 配置LiteLLM的详细日志，便于调试，生产环境可关闭 litellm.set_verbose = False def query_ai(model: str, prompt: str, **kwargs) -> str: """ 统一查询AI模型的函数。 参数: model: 模型标识符，如 "gpt-4", "claude-3-opus-20240229" prompt: 用户输入的提示词 **kwargs: 其他传递给litellm的参数，如 temperature, max_tokens 返回: AI生成的文本内容 """ # 构建消息。LiteLLM统一使用OpenAI的messages格式。 messages = [{"role": "user", "content": prompt}] try: # 关键调用：litellm.completion 是统一入口 # 它会自动根据model参数识别提供商，并调用对应的API response = completion( model=model, messages=messages, **kwargs # 传递额外的参数 ) # 从响应中提取内容。LiteLLM统一了响应结构。 content = response.choices[0].message.content return content.strip() except Exception as e: # 异常处理：网络错误、额度不足、模型不存在等 error_msg = f"调用模型 {model} 时出错: {str(e)}" # 这里可以更精细地处理不同异常，比如认证错误提示检查API Key if "authentication" in str(e).lower(): error_msg += "\n请检查对应的API密钥是否正确设置。" return f"[错误] {error_msg}"

4.3 命令行接口构建（cli.py）

使用click库可以快速构建出功能强大、帮助信息完善的CLI。

# aicode/cli.py import click from .core import query_ai # 定义一些常用模型的预设，方便用户输入短名 MODEL_ALIASES = { "gpt4": "gpt-4", "gpt4-turbo": "gpt-4-turbo-preview", "gpt35": "gpt-3.5-turbo", "claude-opus": "claude-3-opus-20240229", "claude-sonnet": "claude-3-sonnet-20240229", "claude-haiku": "claude-3-haiku-20240307", } @click.command() @click.option( "--model", "-m", required=True, help="指定AI模型。例如：gpt-4, claude-3-opus-20240229。也支持短名：gpt4, claude-opus等。", ) @click.option( "--prompt", "-p", required=True, help="给AI的提示词或问题。", ) @click.option( "--temperature", "-t", default=0.7, type=float, help="生成文本的随机性（0.0-1.0）。值越低输出越确定，越高越有创意。", ) @click.option( "--max-tokens", "-n", default=1024, type=int, help="生成回复的最大token数量。", ) @click.option( "--stream", "-s", is_flag=True, help="是否使用流式输出（逐字显示）。", ) def main(model, prompt, temperature, max_tokens, stream): """一个统一的命令行工具，用于通过LiteLLM调用不同的AI编程助手（如Codex, Claude Code）。""" # 处理模型别名：如果用户输入的是短名，则映射为完整的模型ID model = MODEL_ALIASES.get(model, model) click.echo(f"正在使用模型 [{model}] 处理您的请求...\n") # 准备额外参数 extra_params = { "temperature": temperature, "max_tokens": max_tokens, "stream": stream, } if stream: # 流式输出处理（需要稍微不同的调用方式） click.echo("流式输出开始：") try: import litellm from litellm import completion response = completion( model=model, messages=[{"role": "user", "content": prompt}], stream=True, **{k: v for k, v in extra_params.items() if k != 'stream'} ) for chunk in response: if hasattr(chunk.choices[0].delta, 'content') and chunk.choices[0].delta.content: click.echo(chunk.choices[0].delta.content, nl=False) click.echo() # 输出换行 except Exception as e: click.echo(f"\n[流式输出错误] {e}", err=True) else: # 普通阻塞式调用 result = query_ai(model, prompt, **extra_params) click.echo("生成结果：") click.echo("=" * 50) click.echo(result) click.echo("=" * 50) if __name__ == "__main__": main()

4.4 让工具全局可用（setup.py）

为了让aicode命令能在系统的任何地方运行，我们需要创建一个setup.py文件来打包安装。

# setup.py from setuptools import setup, find_packages setup( name="ai-code-cli", version="0.1.0", packages=find_packages(), install_requires=[ "litellm", "click", "python-dotenv", ], entry_points={ "console_scripts": [ "aicode=aicode.cli:main", # 关键！将 `aicode` 命令映射到我们的主函数 ], }, description="A unified CLI to call Codex, Claude Code, and other AI models via LiteLLM.", author="Your Name", )

完成以上步骤后，在项目根目录下执行安装命令：

pip install -e .

-e参数代表“可编辑模式”，这样你对代码的修改会立刻生效，无需重新安装。安装成功后，在任何新的终端窗口，只要虚拟环境已激活，你都可以直接使用aicode命令了。

5. 实战应用：从代码生成到问题排查

工具建好了，关键看疗效。我们来模拟几个真实的开发者场景，看看如何用这个统一的CLI提升效率。

5.1 场景一：快速生成工具函数

假设我需要一个Python函数，用来递归地列出一个目录下所有特定后缀的文件。

# 使用 Claude 3 Haiku（快速且便宜） aicode -m claude-haiku -p "写一个Python函数 find_files(directory, extension)，递归查找目录下所有指定后缀的文件，返回完整路径的列表。" # 使用 GPT-4（可能更精准，但更贵更慢） aicode -m gpt4 -p "同上，但要求函数包含详细的文档字符串（docstring），并处理可能的权限错误。"

实操心得：对于这种逻辑相对直接、但需要准确性的任务，我会先让快速的Haiku生成一个草稿，如果结果不尽人意，再换Opus或GPT-4进行优化或重写。这样既能节省成本，又能保证质量。

5.2 场景二：解释和重构复杂代码

同事留下了一段晦涩难懂的SQL查询，我需要理解它。

# 将复杂SQL复制到提示词中 aicode -m claude-sonnet -p "请解释下面这段SQL查询是做什么的，并逐行添加注释：\n```sql\nWITH ranked_orders AS (... 你的复杂SQL ...)\nSELECT ... FROM ranked_orders WHERE ...;\n```" # 如果我想让代码更可读，可以要求重构 aicode -m claude-opus -p "重构下面的Python代码，使其符合PEP 8规范，并将复杂的列表推导式拆解为更易读的for循环：\n```python\nresult = [[x*y for y in range(10) if y%2==0] for x in range(5) if x>1]\n```"

注意事项：在向AI发送公司内部或包含敏感信息的代码时，务必谨慎。对于公开或开源代码，这是一个强大的理解工具。Claude系列模型在代码解释和重构方面表现尤为出色。

5.3 场景三：跨模型对比与决策

有时不确定哪个模型更适合当前任务，可以用同一个提示词快速测试。

# 写一个简单的FastAPI端点，对比不同模型的输出风格和完整性 echo "创建一个FastAPI的GET端点 /items，它从数据库（假设使用SQLAlchemy）查询一个Item列表并返回JSON。" > prompt.txt aicode -m gpt4 -p "$(cat prompt.txt)" > result_gpt4.txt aicode -m claude-sonnet -p "$(cat prompt.txt)" > result_claude.txt # 然后使用diff工具或直接打开文件对比 diff result_gpt4.txt result_claude.txt

通过对比，你可能会发现GPT-4生成的代码更模板化、注释更全，而Claude生成的代码可能更简洁，并附带了更多关于错误处理和依赖安装的实用建议。这有助于你建立对不同模型“性格”的直觉。

6. 高级配置与优化技巧

基础功能跑通后，我们可以让它更强大、更顺手。

6.1 配置默认模型和参数

每次都输入-m claude-sonnet -t 0.3很麻烦。可以在项目内创建一个简单的配置文件（如config.yaml）或直接通过环境变量设置默认值。 修改core.py中的query_ai函数，或修改cli.py，让它可以读取一个配置文件。更简单的方法是，在你的Shell配置文件（如~/.bashrc或~/.zshrc）中设置别名：

# 在 ~/.zshrc 中添加 alias aicode-claude="aicode -m claude-sonnet -t 0.3" alias aicode-gpt="aicode -m gpt-4-turbo-preview -t 0.7"

这样，日常使用只需要aicode-claude -p "你的问题"即可。

6.2 实现上下文对话（Session）

当前的工具是单次问答。要实现多轮对话，需要维护一个会话历史。我们可以修改核心逻辑，将对话历史保存在一个简单的文件或内存对象中。 一个简化的思路是，在core.py中维护一个全局的conversation_history字典，键为会话ID，值为消息列表。CLI命令增加一个--session-id参数。每次调用时，如果不是新会话，就将历史消息一并发送给AI。这需要更复杂的状态管理，但对于调试一个复杂问题非常有用。

6.3 集成到IDE或编辑器

真正的“编程自由”是让AI助手触手可及。我们可以将CLI工具与VS Code等编辑器结合。

1. VS Code Tasks：在.vscode/tasks.json中定义一个任务，绑定快捷键，将当前选中的文本作为提示词发送给CLI，并将输出插入编辑器。
2. Shell Command插件：使用如Shell Command这类插件，直接绑定自定义命令。
3. 最直接的方式：在VS Code的集成终端（Integrated Terminal）里直接运行aicode命令。因为我们的CLI是纯文本交互，在终端里使用非常自然，复制粘贴代码也方便。

6.4 成本控制与监控

使用多个API Key，成本管理变得重要。LiteLLM提供了一个很棒的功能：litellm --help你会看到一个--track-cost相关的选项。更正式的做法是启用LiteLLM的日志功能，将请求记录到文件或数据库，然后定期分析。对于个人开发者，最简单有效的方法是定期查看各AI提供商后台的用量统计页面，并为自己设置用量警报。

7. 常见问题与故障排除实录

在实际搭建和使用过程中，我踩过不少坑。这里把典型问题和解决方案记录下来，希望能帮你节省时间。

7.1 认证失败（Authentication Error）

这是最常见的问题，错误信息通常包含401、Invalid API Key或authentication等字样。

• 检查项1：.env文件是否正确加载？
  • 在Python交互环境中运行import os; print(os.getenv(‘OPENAI_API_KEY’))，看是否能打印出密钥（部分内容）。如果为None，说明.env文件未生效。确保文件在项目根目录，且名称是.env（开头有点）。
• 检查项2：API密钥是否正确？
  • 确保密钥没有多余的空格或换行。最好直接从提供商后台复制后，在文本编辑器里检查一遍再粘贴到.env文件。
  • OpenAI的密钥以sk-开头，Anthropic的密钥以sk-ant-开头。
• 检查项3：环境变量名是否正确？
  • LiteLLM默认寻找OPENAI_API_KEY和ANTHROPIC_API_KEY。确保你的.env文件中的变量名与之一致。你也可以在代码中通过os.environ[‘YOUR_KEY_NAME’] = ‘your_key’手动设置。

7.2 模型名称错误（Model Not Found）

错误信息可能类似Model ‘claude-2’ not found。

• 原因：LiteLLM的模型标识符必须精确。不同提供商的格式不同，且会随时间更新。
• 解决方案：
  1. 查阅LiteLLM官方文档的Model List章节。这是最权威的参考。
  2. 对于OpenAI，常用gpt-4,gpt-3.5-turbo。
  3. 对于Anthropic，格式为claude-3-opus-20240229，必须包含完整的版本日期。使用claude-3-opus这样的短名可能不行，除非LiteLLM做了映射。这也是为什么我在CLI里自己实现了一套别名系统。
  4. 运行litellm --list-models命令（如果LiteLLM CLI已安装）可以查看当前支持的部分模型。

7.3 网络超时或代理问题

在中国大陆或其他网络受限地区，直接调用API可能会超时。

• 现象：请求长时间无响应，最终抛出Timeout或连接错误。
• 解决方案：
  • 全局代理：确保你的命令行终端处于可访问国际互联网的网络环境中。这通常需要在系统或终端中配置正确的代理设置。
  • LiteLLM代理设置：LiteLLM本身不支持在库级别配置网络代理。你需要通过设置系统的HTTP_PROXY和HTTPS_PROXY环境变量来实现。

    # 在终端中临时设置（或加入你的shell配置文件） export HTTP_PROXY=http://your-proxy-address:port export HTTPS_PROXY=http://your-proxy-address:port # 然后再运行你的aicode命令 aicode -m gpt-4 -p "hello"

  • 重要提醒：请务必遵守当地法律法规，使用合规的互联网服务。

7.4 流式输出不工作或显示异常

当你使用-s参数时，输出可能卡住或显示乱码。

• 检查：确保你的终端支持实时输出。一些旧的终端模拟器可能有缓冲问题。
• 调试：可以先关闭流式输出（去掉-s），看普通请求是否正常，以排除网络和认证问题。
• 代码层面：我提供的CLI代码中的流式处理部分是一个简化版本。在生产环境中，可能需要更完善的错误处理和连接管理。LiteLLM的流式响应是一个生成器，确保循环逻辑正确，能处理中途断开的情况。

7.5 响应内容被截断

感觉AI的回答没说完就结束了。

• 原因：max_tokens参数设置得太小。这个参数限制了AI生成内容的最大长度。
• 解决方案：根据模型和任务类型增加-n参数的值。例如，对于代码生成或长文档解释，可以设置为2048或4096。但要注意，更大的max_tokens会消耗更多的API额度，并且可能增加响应时间。
• 估算：一个粗略的估计是，英文中1个token约等于0.75个单词，中文/代码可能更复杂。如果你发现经常被截断，就逐步调高这个值。

这个由LiteLLM驱动的统一CLI工具，已经成了我开发工作流中不可或缺的一环。它带来的最大改变不是某个任务快了那么几秒，而是消除了我在不同AI工具间切换的“摩擦”。当思考不被打断，效率的提升是线性的。更重要的是，它给了我一种“掌控感”——我知道请求发向了哪里，成本是多少，并且可以随时根据需求切换“引擎”。