Trae 配置使用本地大模型曲线方案

作者

Trae + Caddy + Ollama：曲线实现 Trae 基于本地大模型的编程（Mac OS）

1. 需求背景

Trae 是一款强大的 AI 辅助编程工具，但它不支持直接配置本地大模型（如 Ollama 运行的模型）。Trae 通常只能调用 OpenAI 格式的云端 API（如 api.openai.com）。为了在 Trae 中使用本地运行的模型（例如 qwen2.5、llama3 等），我们需要通过一个本地反向代理，将 Trae 对云端 API 的请求“欺骗”并转发到本地 Ollama 服务。

本文介绍如何在 macOS 上使用 Caddy 作为反向代理，结合 Ollama 提供的本地模型，让 Trae 能够像调用 OpenAI API 一样调用本地模型，实现完全离线的 AI 编程体验。

2. 组件说明

组件 作用
Trae AI 编程工具，需要配置一个 OpenAI 兼容的 API 地址。
Ollama 本地大模型运行工具，启动后会监听 localhost:11434，并提供 OpenAI 兼容的 API 端点 /v1/chat/completions。
Caddy 轻量、自动 HTTPS 的反向代理服务器。我们将用它创建一个本地域名（如 api.x.ai），并将请求转发到 Ollama，同时处理证书和 Host 头问题。

3. 环境准备

3.1 安装 Ollama 并下载模型

如果你还没有安装 Ollama，打开终端执行：

brew install ollama

启动 Ollama 服务（默认后台运行）：

ollama serve

下载所需模型（例如 qwen2.5:7b-instruct-q4_K_M，可根据需要替换）：

ollama pull qwen2.5:7b-instruct-q4_K_M

验证 Ollama 是否正常工作：

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5:7b-instruct-q4_K_M",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

应返回正常的 JSON 响应。

3.2 安装 Caddy

使用 Homebrew 安装 Caddy：

brew install caddy

安装后，终端输入 caddy version 确认成功。

4. 配置 Caddy 反向代理

4.1 选择本地域名

我们需要一个域名指向本地（127.0.0.1），例如 api.x.ai。注意：x.ai 是真实存在的域名，但我们只会在本地 hosts 文件中解析它，不会影响公网。

4.2 修改 hosts 文件

编辑 /etc/hosts 文件，将 api.x.ai 指向本地：

sudo nano /etc/hosts

添加一行：

127.0.0.1 api.x.ai

保存退出（nano 中按 Ctrl+O 回车，Ctrl+X 退出）。

可选：刷新 DNS 缓存：

sudo dscacheutil -flushcache

4.3 创建 Caddyfile

Caddy 的配置文件通常名为 Caddyfile，无扩展名。在任意目录（例如 ~/caddy）创建该文件：

mkdir -p ~/caddy
cd ~/caddy
nano Caddyfile

写入以下内容：

api.x.ai {
    tls internal
    reverse_proxy localhost:11434 {
        header_up Host localhost:11434   # 关键：重写 Host 头，避免 Ollama 拒绝
    }
}

配置解释：

  • tls internal：让 Caddy 使用内置 CA 生成自签名证书，避免依赖 Let's Encrypt。
  • reverse_proxy localhost:11434：将请求转发到 Ollama。
  • header_up Host localhost:11434：非常重要！Ollama 可能检查 Host 头，默认 Caddy 会传递客户端原来的 Host: api.x.ai，导致 Ollama 返回 403。这里强制改为 localhost:11434，让 Ollama 认为是本地请求。

4.4 使自签名证书受系统信任（可选，但推荐）

为了让浏览器和 Trae 不报证书错误，将 Caddy 的根证书导入系统信任区：

caddy trust

此命令会将 Caddy 内部 CA 的根证书添加到 macOS 钥匙串，并标记为信任。之后访问 https://api.x.ai 将不会出现安全警告。

4.5 启动 Caddy

在 Caddyfile 所在目录运行：

caddy run

终端将显示日志，包括证书生成信息。保持此终端运行（或使用 caddy start 后台运行）。

测试代理是否正常工作：

curl -v https://api.x.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5:7b-instruct-q4_K_M",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

如果返回正常的 JSON 且状态码 200，则代理配置成功。

5. 配置 Trae 使用本地 API

  1. 打开 Trae。
  2. 进入设置（Preferences 或 Settings），找到 API 配置 或 模型提供商 相关选项。
  3. 选择 自定义 API 或 OpenAI Compatible。
  4. 填写以下信息：
    • API 地址：https://api.x.ai/v1（注意是 HTTPS，且路径末尾可加 /v1，Trae 会自动拼接 /chat/completions）
    • API Key：任意值（例如 sk-no-key-required），因为 Ollama 不验证 key，但 Trae 可能需要一个占位符。
    • 模型名称：填写你下载的模型名，例如 qwen2.5:7b-instruct-q4_K_M。
  5. 保存配置。

6. 测试验证

在 Trae 中随便提问，例如“写一个 Python 快速排序”。如果配置正确，Trae 应该能调用本地模型并返回结果。

你也可以在 Caddy 的终端日志中看到请求记录，确认流量经过代理。

7. 故障排查

7.1 无法连接到 API，报错 403

原因：Host 头未正确重写，Ollama 拒绝请求。

解决：检查 Caddyfile 中是否包含 header_up Host localhost:11434，并重启 Caddy。

7.2 证书错误（SSL 相关）

现象：通过 postman 测试提示证书不受信任。

解决：

  • 确保运行了 caddy trust。
  • 如果仍无效，可以尝试在 Trae 中关闭 SSL 验证（如果支持），或临时使用 HTTP（不推荐）。更好的办法是手动导入证书：~/Library/Application Support/Caddy/pki/authorities/local/root.crt，双击添加到钥匙串并设为始终信任。

7.3 Caddy 无法启动，提示端口占用

原因：443 端口被占用（如 macOS 的 AirPlay 接收器）。

解决：停止占用端口的服务，或修改 Caddy 监听其他端口（如 8443），并在 hosts 中相应调整。例如在 Caddyfile 中写 api.x.ai:8443，但 Trae 中也要改为 https://api.x.ai:8443/v1。

7.4 请求成功但返回空或错误响应

原因：Ollama 模型未正确加载，或请求参数不兼容。

解决：先用 curl 测试 Ollama 原生 API，确认模型正常工作。检查 Trae 发送的请求体是否符合 Ollama 的 OpenAI 兼容格式（通常兼容良好）。

8. 总结

通过 Caddy 作为本地反向代理，我们成功地将 Trae 对云端 API 的调用指向了本地 Ollama 服务，实现了基于本地大模型的 AI 编程。此方案完全离线、免费，且数据不会离开你的电脑，适合隐私敏感或网络受限的场景。

核心要点：

  • 使用本地域名 + hosts 解析
  • Caddy 自动生成自签名证书（tls internal）
  • 必须重写 Host 头，否则 Ollama 会返回 403
  • 将 Caddy 根证书加入系统信任，消除 SSL 警告

现在，尽情享受本地大模型带来的高效编程体验吧！

发表评论