用 LiteLLM 串接本地模型到 Claude Code

讓 Claude Code（或任何 Anthropic/OpenAI 格式的 client）透過 LiteLLM proxy 使用本地 Ollama 模型。 實測環境：macOS ARM64, Python 3.13, LiteLLM 1.82, Ollama + qwen2.5

架構

Claude Code / Any Client
        │
        │  Anthropic API (/v1/messages) 或 OpenAI API (/v1/chat/completions)
        ▼
   LiteLLM Proxy (localhost:4000)
        │
        │  轉換格式 → Ollama API
        ▼
   Ollama (localhost:11434)
        │
        ▼
   本地模型 (qwen2.5, llama3.2, etc.)

重點：LiteLLM 同時支援 Anthropic /v1/messages 和 OpenAI /v1/chat/completions 格式，所以 Claude Code 可以直接連。

安裝

1. 安裝 Ollama

# macOS
brew install ollama

# 或從官網下載: https://ollama.com/download

2. 下載模型

ollama pull qwen2.5:7b      # 推薦，平衡效能和品質
ollama pull qwen2.5:3b      # 輕量替代
ollama pull llama3.2:latest  # Meta 的模型

3. 安裝 LiteLLM

# 建議用 venv 隔離（Python 3.11-3.13）
python3.13 -m venv ~/litellm-env
source ~/litellm-env/bin/activate
pip install 'litellm[proxy]'

⚠️ Python 3.14 目前有 uvloop 相容性問題，用 3.11-3.13。

設定

建立 config.yaml：

model_list:
  # 本地 Ollama 模型
  - model_name: "qwen2.5-7b"
    litellm_params:
      model: "ollama_chat/qwen2.5:7b"
      api_base: "http://localhost:11434"

  - model_name: "qwen2.5-3b"
    litellm_params:
      model: "ollama_chat/qwen2.5:3b"
      api_base: "http://localhost:11434"

  - model_name: "llama3.2-3b"
    litellm_params:
      model: "ollama_chat/llama3.2:latest"
      api_base: "http://localhost:11434"

  # （選用）雲端 fallback — 本地模型掛了自動切雲端
  # - model_name: "claude-sonnet"
  #   litellm_params:
  #     model: "anthropic/claude-sonnet-4-20250514"
  #     api_key: "os.environ/ANTHROPIC_API_KEY"

general_settings:
  master_key: "sk-your-secret-key"  # 改成你自己的 key

啟動

# 確保 Ollama 在跑
ollama serve &

# 啟動 LiteLLM proxy
source ~/litellm-env/bin/activate
litellm --config config.yaml --port 4000

測試

OpenAI 格式（/v1/chat/completions）

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-secret-key" \
  -d '{
    "model": "qwen2.5-7b",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'

Anthropic 格式（/v1/messages）— Claude Code 用這個

curl http://localhost:4000/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-your-secret-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "qwen2.5-7b",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Streaming

兩種格式都支援，加 "stream": true 即可：

curl http://localhost:4000/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-your-secret-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "qwen2.5-7b",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Count 1 to 5"}],
    "stream": true
  }'

串接 Claude Code

在 Claude Code 的設定中，把 API base URL 改成 LiteLLM：

# 設定環境變數
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-your-secret-key"

# 啟動 Claude Code
claude

或在 Claude Code 設定檔中修改（視 Claude Code 版本而定）。

串接 MLX Server（替代 Ollama）

如果用 MLX Server 而非 Ollama：

model_list:
  - model_name: "local-model"
    litellm_params:
      model: "openai/your-model-name"
      api_base: "http://localhost:8080/v1"  # MLX Server 預設 port

MLX Server 本身提供 OpenAI 相容 API，所以 LiteLLM 直接當 OpenAI provider 對接。

常見問題

Python 3.14 啟動失敗

uvloop 尚未支援 Python 3.14，改用 3.11-3.13：

python3.13 -m venv ~/litellm-env

Ollama 模型不支援 function calling

部分小模型不支援 tool use。如果 Claude Code 需要 tool use，用支援的模型（如 qwen2.5:7b）或 fallback 到雲端。

想加更多 provider

model_list:
  - model_name: "gpt-4o"
    litellm_params:
      model: "gpt-4o"
      api_key: "os.environ/OPENAI_API_KEY"

  - model_name: "gemini-pro"
    litellm_params:
      model: "gemini/gemini-pro"
      api_key: "os.environ/GOOGLE_API_KEY"

LiteLLM 支援 100+ provider，全部統一為 OpenAI 格式。

實測結果

在 macOS ARM64 (M-series) 實測通過的項目：

測試	結果
/v1/models 列出模型	✅
/v1/chat/completions 非 streaming	✅
/v1/chat/completions streaming	✅
/v1/messages Anthropic 格式非 streaming	✅
/v1/messages Anthropic 格式 streaming (SSE)	✅
Health check	✅

---

LiteLLM: https://github.com/BerriAI/litellm (39K+ stars, MIT License) Ollama: https://ollama.com