使用 Docker 安装 LiteLLM 并配置 Claude Code 连接本地 oMLX 模型

,

本文档指导你通过 Docker 运行 LiteLLM 代理服务，将 Claude Code 的请求转发到本地的 oMLX 模型（或任何 OpenAI 兼容的本地服务）。

准备工作：创建项目目录

1
mkdir -p ~/litellm-docker && cd ~/litellm-docker

⚙️ 步骤一：创建配置文件

1. 创建 docker-compose.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    container_name: litellm
    ports:
      - "4000:4000"
    volumes:
      - ./litellm_config.yaml:/app/config.yaml
    command:
      - "--config"
      - "/app/config.yaml"
      - "--port"
      - "4000"

2. 创建 litellm_config.yaml

1
2
3
4
5
6
model_list:
  - model_name: claude-3-haiku-20240307       # Claude Code 调用的模型名称
    litellm_params:
      model: openai/你的oMLX中的模型名          # 替换为你的实际模型名，例如 openai/Qwen2.5-7B
      api_base: http://host.docker.internal:8050/v1   # oMLX 服务地址，端口根据实际情况修改
      api_key: dummy-key-for-omlx              # 任意占位符

重要说明：

  • model_name：可自定义，后续 Claude Code 通过 ANTHROPIC_MODEL 指定这个名字。
  • model：格式 openai/模型名，填写你在 oMLX 界面中看到的模型名称。
  • api_base：host.docker.internal 是 Docker 访问宿主机的专用域名，端口需与 oMLX 设置一致（默认 8050）。
  • api_key：任意字符串，本地服务不校验。

🚀 步骤二：启动 LiteLLM 服务

1
docker-compose up -d

查看日志确认启动成功：

1
docker-compose logs litellm

看到 Application startup complete. 即表示正常。

⚡ 步骤三：配置 Claude Code

方式一：临时环境变量（适合快速测试）

在要运行 Claude Code 的终端中执行

1
2
3
4
5
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-any-dummy-value"
export ANTHROPIC_MODEL="claude-3-haiku-20240307"   # 必须与 litellm_config.yaml 中的 model_name 一致
export API_TIMEOUT_MS="600000"

方式二：写入 Claude Code 全局配置文件（一劳永逸）

1
2
3
4
5
6
7
8
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-any-dummy-value",
    "ANTHROPIC_MODEL": "claude-3-haiku-20240307",
    "API_TIMEOUT_MS": "600000"
  }
}

🐛 步骤四：验证与测试

1.测试LiteLLM 服务

1
curl http://localhost:4000/health

2. 测试模型路由

1
2
3
4
5
6
curl http://localhost:4000/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-haiku-20240307",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

如果收到你本地模型的回复，说明配置正确。

## 🔁 日常维护

  • 修改配置后重启：docker-compose restart
  • 查看实时日志：docker-compose logs -f litellm
  • 停止服务：docker-compose down
  • 启动服务：docker-compose up -d