使用 Ollama 和 LiteLLM 本地运行 Claude Code 教程

作者
  • avatar
    姓名
    Nino
    职业
    Senior Tech Editor

随着 AI Agent（智能体）技术的爆发，开发者工具正经历着一场前所未有的变革。Anthropic 最近推出的 Claude Code 是一款高性能的命令行界面（CLI）工具，它允许开发者直接在终端中通过 Claude 3.5 Sonnet 模型对代码库进行深度操作。虽然 Claude Code 功能极其强大，但其对付费 API 的依赖也带来了高昂的 Token 成本，特别是在进行大规模重构或持续的代码库索引时。为了追求隐私保护和成本优化，将这些 Agent 工作流本地化已成为开发者的必然选择。通过利用 Ollama 和 LiteLLM 代理层，你可以将 Claude Code 的强大功能重定向到 DeepSeek-V3 或 Llama 3.1 等顶级开源模型上。

本地 Agent 工作流的挑战

Claude Code 在设计之初是专门为 Anthropic 官方 API 优化的。它利用了先进的工具调用（Tool-calling）能力和模型上下文协议（MCP），能够自主执行目录导航、读取文件、运行终端命令等任务。要在本地实现这一过程，我们需要解决两个核心问题：首先，Claude Code CLI 默认只识别 Anthropic 的 API 格式；其次，本地模型必须具备极强的逻辑推理能力，以确保在处理复杂的代码变更时不会产生幻觉。

虽然本地模型在不断进步，但在某些极端复杂的场景下，你可能仍然需要云端顶级模型的精准度。在这种情况下，使用 n1n.ai 这样的一站式 API 聚合平台，可以为你提供比直接调用官方更低延迟、更具性价比的 Claude 3.5 Sonnet 或 DeepSeek-V3 接口，作为本地算力的强力补充。

架构方案：构建兼容桥梁

为了让 Claude Code 能够与本地模型通信，我们需要构建以下技术栈：

  1. Claude Code CLI：作为前端 Agent，负责管理编程任务。
  2. LiteLLM：作为代理服务器，将 Anthropic API 请求转换为本地模型能够理解的格式。
  3. Ollama：作为本地推理引擎，负责运行具体的模型权重（如 DeepSeek-V3）。

第一步：安装本地推理引擎

首先，确保你的系统中已安装 Ollama。Ollama 支持 macOS、Linux 和 Windows，极大地简化了本地运行大模型的过程。安装完成后，我们需要拉取一个支持复杂工具调用的模型。DeepSeek-V3 是目前的最佳选择，因为它在代码生成和逻辑推理方面表现卓越。

# 拉取 DeepSeek-V3 模型（请确保显存充足）
ollama pull deepseek-v3

如果你的硬件配置较低，可以选择 qwen2.5-coder:7b 或 llama3.1:8b，这些模型在 8GB 到 12GB 显存的消费级显卡上即可流畅运行。

第二步：配置 LiteLLM 代理

由于 Claude Code 强制要求连接 Anthropic 的 API，我们可以通过设置 ANTHROPIC_BASE_URL 环境变量，将请求重定向到本地的 LiteLLM 实例。LiteLLM 在这里充当了“翻译官”的角色。

使用 pip 安装 LiteLLM：

pip install 'litellm[proxy]'

创建一个名为 config.yaml 的配置文件，将 Anthropic 的模型名称映射到你的本地 Ollama 模型：

model_list:
  - model_name: claude-3-5-sonnet-20241022
    litellm_params:
      model: ollama/deepseek-v3
      api_base: 'http://localhost:11434'

启动代理服务：

litellm --config config.yaml --port 4000

第三步：在本地启动 Claude Code

现在，你的本地服务器已经可以模拟 Anthropic API 了。接下来，需要配置环境变量，让 Claude Code CLI 将请求发送到 LiteLLM 而不是云端。

# 将基础 URL 指向本地 LiteLLM 代理
export ANTHROPIC_BASE_URL="http://localhost:4000"

# 提供一个虚拟 API Key（LiteLLM 验证逻辑需要）
export ANTHROPIC_API_KEY="sk-local-key"

# 运行 Claude Code
claude

进入 Claude Code 界面后，你可以尝试输入指令，例如：“重构 auth.ts 中的身份验证逻辑”或“为工具函数编写单元测试”。此时，Agent 将会通过 Ollama 调用你本地的 DeepSeek 模型进行处理。

深度分析：为什么选择 DeepSeek-V3？

在当前的开源模型中，DeepSeek-V3 已成为 Claude 3.5 Sonnet 的有力竞争者。在针对代码生成和代码库理解的基准测试中，DeepSeek-V3 展现出了极高的工具调用成功率。这对于 Claude Code 至关重要，因为 Agent 必须准确判断何时使用 ls、cat 或 grep 来探索项目。如果模型无法正确格式化工具调用指令，整个 Agent 循环就会中断。

然而，本地运行的性能高度依赖于硬件。如果你发现本地推理速度 < 1 token/s，这会极大地影响开发效率。在这种情况下，切换回云端 API 是更明智的选择。n1n.ai 提供的企业级基础设施可以确保你以极快的速度访问 DeepSeek-V3 或 Claude 3.5，避免因本地显卡性能不足而产生的等待焦虑。

上下文窗口与成本管理

本地运行方案最大的优势在于消除了按 Token 计费的压力。Claude Code 经常需要将整个文件的内容或大量的目录结构发送给模型，在云端环境下，这可能导致每小时产生数美元的费用。而在本地，你唯一的成本就是电费。

但需要注意的是，你必须手动管理上下文窗口。Ollama 默认的上下文长度通常为 4096 tokens。为了处理复杂的代码库，你应该在 LiteLLM 或 Ollama 的配置中增加这一数值：

# 在 Ollama Modelfile 或 LiteLLM 配置中
# 将上下文增加到 32k 以获得更好的代码理解能力
num_ctx: 32768

专家建议：本地 Agent 开发技巧

  1. 量化策略：如果你使用的是 24GB 显存的显卡（如 RTX 3090/4090），建议使用 DeepSeek-V3 的 Q4_K_M 或 Q5_K_M 量化版本，这在智能水平和推理速度之间达到了完美平衡。
  2. MCP 协议集成：Claude Code 支持模型上下文协议。你可以运行本地的 MCP 服务器（例如数据库检查工具或 Google 搜索工具），并将其连接到本地 Agent，从而扩展其功能边界。
  3. 混合模式：对于编写样板代码或文档等常规任务，使用本地模型；当遇到需要深度推理的复杂 Bug 时，可以将 ANTHROPIC_BASE_URL 切换回 n1n.ai，利用云端 Claude 3.5 Sonnet 的全量性能解决问题。

总结

通过 Ollama 和 LiteLLM 本地运行 Claude Code，为注重隐私和成本的开发者提供了一条极具吸引力的路径。虽然初始配置需要一定的时间，但能够在一个完全由自己掌控的环境中运行自主编程助手，无疑是通往去中心化软件开发未来的重要一步。

对于那些追求极致稳定性和响应速度，且不想维护复杂硬件环境的用户，n1n.ai 提供了全球领先模型的可靠 API 接入，是生产环境的最佳伙伴。

Get a free API key at n1n.ai

参考来源：https://dev.to/proflead/stop-paying-for-tokens-run-claude-code-locally-with-ollama-3o82