【vibo经验记录】Mac 配置 Claude Code + 远程 Ollama 完全指南
·
文章目录
Mac 配置 Claude Code + 远程 Ollama 完全指南
本文详细介绍如何在 Mac 本地运行 Claude Code，连接远程服务器上的 Ollama 服务，实现私有 AI 编程助手。包含完整的架构图、配置步骤和故障排除。
一、架构设计
1.1 整体架构图
┌─────────────────────────────────────────────────────────────────────────┐
│ 整体架构 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ SSH 隧道 ┌──────────────────────┐ │
│ │ │ ═══════════════════════► │ │ │
│ │ Mac 本地 │ 端口: 11434 ◄────► │ 远程服务器 │ │
│ │ │ 加密通道 │ 1.1.1.1 │ │
│ │ ┌────────┐ │ │ │ │
│ │ │ Claude │ │ │ ┌──────────────┐ │ │
│ │ │ Code │──┼──► API 请求 │ │ Ollama │ │ │
│ │ │ 客户端 │ │ │ │ 服务 │ │ │
│ │ └────────┘ │ │ │ ┌────────┐ │ │ │
│ │ │ │ │ │ │qwen3.5 │ │ │ │
│ │ ▼ │ │ │ │ :9b │ │ │ │
│ │ ┌────────┐ │ │ │ └────────┘ │ │ │
│ │ │ 代理层 │ │ │ │ (9.7B) │ │ │
│ │ │:11435 │ │ │ └──────────────┘ │ │
│ │ └────────┘ │ │ │ │
│ │ │ │ 模型文件: 6.6GB │ │
│ └──────────────┘ └──────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
1.2 数据流向图
┌────────────────────────────────────────────────────────────────┐
│ 数据流向 │
├────────────────────────────────────────────────────────────────┤
│ │
│ 用户输入 │
│ │ │
│ ▼ │
│ ┌─────────────┐ Anthropic API ┌─────────────┐ │
│ │ Claude Code │ ─────────────────► │ Ollama │ │
│ │ 客户端 │ /v1/messages │ 代理层 │ │
│ └─────────────┘ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ 协议转换 │ │
│ │ Anthropic ↔ OpenAI │ │
│ └───────────┬────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ OpenAI API ┌─────────────┐ │
│ │ Ollama │ ◄─────────────────│ SSH 隧道 │ │
│ │ 服务器 │ /v1/chat/completions │ :11434 │ │
│ └─────────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ qwen3.5:9b │ 推理生成 │
│ │ 模型 │ │
│ └─────────────┘ │
│ │ │
│ ▼ │
│ 返回响应 ◄───────────────────────────────────────────────────┘
│ │
└────────────────────────────────────────────────────────────────┘
二、环境准备
2.1 硬件环境
┌────────────────────┐ 网络 ┌────────────────────┐
│ Mac 本地 │ ═══════════════► │ 远程服务器 │
│ │ 内网/公网 │ │
│ ┌──────────────┐ │ │ ┌──────────────┐ │
│ │ macOS 12+ │ │ │ │ Linux │ │
│ │ 16GB+ 内存 │ │ │ │ Ubuntu 22.04 │ │
│ │ Homebrew │ │ │ │ 32GB+ 内存 │ │
│ └──────────────┘ │ │ │ GPU (可选) │ │
│ │ │ └──────────────┘ │
└────────────────────┘ └────────────────────┘
具体配置：
- 本地: MacBook (已安装 Homebrew)
- 服务器: Linux 服务器 (IP: 1.1.1.1, 用户名: root, 密码: 0)
2.2 软件需求清单
┌─────────────────────────────────────────────────────────────┐
│ 软件依赖清单 │
├─────────────────┬───────────────┬───────────────────────────┤
│ 软件 │ 版本 │ 用途 │
├─────────────────┼───────────────┼───────────────────────────┤
│ Claude Code │ 1.0.108+ │ AI 编程助手客户端 │
│ Ollama │ 0.1.0+ │ 大模型推理服务 │
│ sshpass │ 1.06+ │ 自动 SSH 密码输入 │
│ Python │ 3.9+ │ 代理服务运行环境 │
│ Flask │ 2.0+ │ API 代理框架 │
└─────────────────┴───────────────┴───────────────────────────┘
三、服务端部署 Ollama
3.1 SSH 连接服务器
┌────────────────────────────────────────┐
│ SSH 连接流程 │
├────────────────────────────────────────┤
│ │
│ Mac 终端 │
│ │ │
│ ▼ │
│ sshpass -p 'xxx' ssh root@1.1.1.1 │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ 身份验证 │ │
│ │ 密码: 0 │ │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ 连接成功！进入服务器 shell │
│ │
└────────────────────────────────────────┘
安装 sshpass：
# macOS 安装 sshpass
brew install sshpass
# 连接服务器
sshpass -p 'xxx' ssh -o StrictHostKeyChecking=no root@1.1.1.1
3.2 安装 Ollama
┌─────────────────────────────────────────────┐
│ Ollama 安装过程 │
├─────────────────────────────────────────────┤
│ │
│ 执行命令 │
│ │ │
│ ▼ │
│ curl -fsSL https://ollama.com/install.sh │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ 下载安装包 │ │
│ │ ~500MB │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ 安装二进制 │ │
│ │ /usr/local │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ 启动服务 │ │
│ │ ollama serve│ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ 安装完成！监听端口 11434 │
│ │
└─────────────────────────────────────────────┘
安装命令：
# 一键安装
curl -fsSL https://ollama.com/install.sh | sh
# 验证安装
ollama --version
3.3 配置远程访问
┌─────────────────────────────────────────────────────┐
│ Ollama 网络配置 │
├─────────────────────────────────────────────────────┤
│ │
│ 默认配置 (仅本地) │
│ ┌─────────────┐ │
│ │ OLLAMA_HOST│ = 127.0.0.1:11434 │
│ └─────────────┘ │
│ │ │
│ ▼ │
│ 仅允许 localhost 访问 │
│ │
│ ═══════════════════════════════════════════════ │
│ │
│ 修改后配置 (允许远程) │
│ ┌─────────────┐ │
│ │ OLLAMA_HOST│ = 0.0.0.0:11434 │
│ └─────────────┘ │
│ │ │
│ ▼ │
│ 允许所有网络接口访问 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 本地 │ │ 内网 │ │ SSH隧道 │ │
│ │ 127.0.0.1│ │ 192.168.x.x│ │ 转发 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
└─────────────────────────────────────────────────────┘
修改配置：
# 编辑服务文件
vim /etc/systemd/system/ollama.service
# 在 [Service] 部分添加
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
# 重启服务
systemctl daemon-reload
systemctl restart ollama
3.4 下载模型
┌───────────────────────────────────────────────────────────┐
│ 模型下载过程 │
├───────────────────────────────────────────────────────────┤
│ │
│ ollama pull qwen3.5:9b │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ 检查模型清单 │ │
│ │ manifest │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ 下载模型文件 │ │
│ │ 6.6 GB │ ◄────── 进度条显示 │
│ │ qwen3.5:9b │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ 验证完整性 │ │
│ │ sha256 │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ 下载完成！存储在 /usr/share/ollama/.ollama/models │
│ │
└───────────────────────────────────────────────────────────┘
下载命令：
# 拉取 9B 模型
ollama pull qwen3.5:9b
# 查看已安装模型
ollama list
输出示例：
NAME ID SIZE MODIFIED
qwen3.5:9b 6488c96fa5fa 6.6 GB 5 days ago
qwen3.5:35b 3460ffeede54 23 GB 4 days ago
四、建立 SSH 隧道
4.1 隧道原理
┌────────────────────────────────────────────────────────────────────┐
│ SSH 端口转发原理 │
├────────────────────────────────────────────────────────────────────┤
│ │
│ Mac 本地 远程服务器 │
│ ───────── ─────────── │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 应用 │ │ Ollama │ │
│ │ 访问 │ │ 服务 │ │
│ │ localhost│ │ 0.0.0.0 │ │
│ │ :11434 │ │ :11434 │ │
│ └────┬─────┘ └────┬─────┘ │
│ │ │ │
│ │ ╔═══════════════════════════╗│ │
│ └───►║ SSH 加密隧道 ║├────────────────────────►│
│ ║ localhost:11434 ║ localhost:11434 │
│ ║ ◄──────► ║ │
│ ╚═══════════════════════════╝ │
│ │
│ 命令: ssh -L 11434:localhost:11434 root@1.1.1.1 │
│ │
└────────────────────────────────────────────────────────────────────┘
4.2 建立隧道
# 使用 sshpass 自动输入密码建立隧道
sshpass -p 'xxx' ssh -o StrictHostKeyChecking=no \
-N -L 11434:localhost:11434 root@1.1.1.1 &
# 参数说明:
# -N: 不执行远程命令，仅做端口转发
# -L: 本地端口转发 [本地端口]:[远程主机]:[远程端口]
# &: 后台运行
4.3 验证连接
┌──────────────────────────────────────────┐
│ 连接验证测试 │
├──────────────────────────────────────────┤
│ │
│ 测试命令 │
│ │ │
│ ▼ │
│ curl http://localhost:11434/api/tags │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ 返回 JSON │ │
│ │ 模型列表 │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ 连接成功！ │
│ │
└──────────────────────────────────────────┘
验证命令：
# 测试 API
curl http://localhost:11434/api/tags
# 预期输出
{"models":[{"name":"qwen3.5:9b","model":"qwen3.5:9b",...}]}
五、API 代理层（关键步骤）
5.1 为什么需要代理层
┌─────────────────────────────────────────────────────────────────┐
│ API 兼容性说明 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Claude Code Ollama │
│ ─────────── ─────── │
│ │
│ 使用 Anthropic API 格式 使用 OpenAI API 格式 │
│ │
│ POST /v1/messages POST /v1/chat/completions │
│ { { │
│ "messages": [...], "messages": [...], │
│ "model": "claude-3" "model": "qwen3.5:9b" │
│ } } │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ 格式不兼容！直接连接会返回 404 │
│ │
│ 解决方案：添加代理层进行协议转换 │
│ │
│ Claude Code ──► 代理层 ──► Ollama │
│ Anthropic 转换 OpenAI │
│ API 格式 API │
│ │
└─────────────────────────────────────────────────────────────────┘
5.2 代理服务架构
┌─────────────────────────────────────────────────────────────────┐
│ 代理服务架构 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Flask 代理服务 │ │
│ │ 端口: 11435 │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ 接收请求 │─────►│ 协议转换 │ │ │
│ │ │ /v1/messages │ │ Anthropic │ │ │
│ │ │ (Claude格式) │ │ → OpenAI │ │ │
│ │ └──────────────┘ └──────┬───────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────┐ │ │
│ │ │ 转发到 Ollama│ │ │
│ │ │ :11434 │ │ │
│ │ └──────┬───────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────┐ │ │
│ │ │ 返回响应 │ │ │
│ │ │ 转换回 │ │ │
│ │ │ Anthropic │ │ │
│ │ │ 格式 │ │ │
│ │ └──────────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
5.3 代理代码
创建代理文件 ollama_proxy.py：
#!/usr/bin/env python3
"""
Ollama Proxy - 为 Claude Code 提供兼容的 API 接口
支持 Anthropic API 格式转换为 OpenAI API 格式
"""
import json
import time
import requests
from flask import Flask, request, Response
from flask_cors import CORS
app = Flask(__name__)
CORS(app)
OLLAMA_HOST = "http://localhost:11434"
@app.route('/v1/messages', methods=['POST'])
@app.route('/v1/v1/messages', methods=['POST'])
def anthropic_messages():
"""Anthropic Messages API - Claude Code 使用此接口"""
data = request.get_json()
# 转换 Anthropic 格式到 OpenAI 格式
messages = data.get('messages', [])
system = data.get('system', '')
openai_messages = []
if system:
openai_messages.append({"role": "system", "content": system})
openai_messages.extend(messages)
# 构建 OpenAI 请求
openai_data = {
"model": data.get('model', 'qwen3.5:9b'),
"messages": openai_messages,
"stream": data.get('stream', False),
"temperature": data.get('temperature', 0.7)
}
# 发送到 Ollama
resp = requests.post(
f"{OLLAMA_HOST}/v1/chat/completions",
json=openai_data,
stream=data.get('stream', False)
)
if resp.status_code != 200:
return Response(resp.content, resp.status_code)
result = resp.json()
# 转换回 Anthropic 格式
anthropic_response = {
"id": "msg_" + str(int(time.time())),
"type": "message",
"role": "assistant",
"model": data.get('model', 'qwen3.5:9b'),
"content": [
{
"type": "text",
"text": result['choices'][0]['message']['content']
}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": result['usage']['prompt_tokens'],
"output_tokens": result['usage']['completion_tokens']
}
}
return Response(json.dumps(anthropic_response),
content_type='application/json')
if __name__ == '__main__':
print("Ollama Proxy 启动在 http://localhost:11435")
app.run(host='0.0.0.0', port=11435, debug=False)
5.4 启动代理
# 安装依赖
pip3 install flask flask-cors requests
# 启动代理
python3 ollama_proxy.py
六、配置 Claude Code
6.1 配置文件结构
┌─────────────────────────────────────────────┐
│ Claude Code 配置 │
├─────────────────────────────────────────────┤
│ │
│ ~/.claude/settings.json │
│ ───────────────────────── │
│ { │
│ "env": { │
│ "ANTHROPIC_BASE_URL": "http://...", │
│ "ANTHROPIC_AUTH_TOKEN": "ollama", │
│ "ANTHROPIC_MODEL": "qwen3.5:9b" │
│ } │
│ } │
│ │
└─────────────────────────────────────────────┘
6.2 创建配置
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
"env": {
"DISABLE_PROMPT_CACHING": 0,
"ANTHROPIC_BASE_URL": "http://localhost:11435",
"ANTHROPIC_AUTH_TOKEN": "ollama",
"ANTHROPIC_MODEL": "qwen3.5:9b",
"ANTHROPIC_SMALL_FAST_MODEL": "qwen3.5:9b"
}
}
EOF
6.3 完整启动脚本
#!/bin/bash
# Claude Code + Ollama 启动脚本
echo "=========================================="
echo " Claude Code + Ollama 启动器"
echo "=========================================="
echo ""
# 1. 检查 SSH 隧道
if ! lsof -i :11434 > /dev/null 2>&1; then
echo "[*] 建立 SSH 隧道到服务器..."
sshpass -p 'xxx' ssh -o StrictHostKeyChecking=no \
-N -L 11434:localhost:11434 root@1.1.1.1 &
sleep 2
echo "[✓] SSH 隧道已建立"
else
echo "[✓] SSH 隧道已存在"
fi
# 2. 检查代理服务
if ! lsof -i :11435 > /dev/null 2>&1; then
echo "[*] 启动 Ollama 代理..."
python3 ollama_proxy.py > /tmp/ollama_proxy.log 2>&1 &
sleep 2
echo "[✓] 代理已启动 (端口 11435)"
else
echo "[✓] 代理已运行"
fi
echo ""
echo "配置信息:"
echo " 模型: qwen3.5:9b (9.7B 参数)"
echo " 服务器: 1.1.1.1"
echo " 代理: http://localhost:11435"
echo ""
# 3. 启动 Claude Code
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_BASE_URL=http://localhost:11435
export ANTHROPIC_MODEL=qwen3.5:9b
export ANTHROPIC_SMALL_FAST_MODEL=qwen3.5:9b
claude "$@"
七、验证测试
7.1 分层验证
┌─────────────────────────────────────────────────────────────┐
│ 分层验证流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Layer 1: SSH 隧道 │
│ ───────────────── │
│ $ lsof -i :11434 │
│ ssh ... -L 11434:localhost:11434 │
│ [✓] 隧道正常 │
│ │
│ │ │
│ ▼ │
│ │
│ Layer 2: Ollama 服务 │
│ ─────────────────── │
│ $ curl localhost:11434/api/tags │
│ {"models":[{"name":"qwen3.5:9b"...}]} │
│ [✓] Ollama 响应正常 │
│ │
│ │ │
│ ▼ │
│ │
│ Layer 3: API 代理 │
│ ─────────────── │
│ $ curl localhost:11435/v1/messages -d '{...}' │
│ {"content":[{"text":"Hello"...}]} │
│ [✓] 代理转换正常 │
│ │
│ │ │
│ ▼ │
│ │
│ Layer 4: Claude Code │
│ ────────────────── │
│ $ echo "test" | claude --print │
│ 我是 Qwen3.5，由阿里巴巴开发... │
│ [✓] 端到端正常 │
│ │
└─────────────────────────────────────────────────────────────┘
7.2 测试命令
# 测试 1: SSH 隧道
curl http://localhost:11434/api/tags
# 测试 2: 代理层
curl -s http://localhost:11435/v1/messages \
-H "Content-Type: application/json" \
-d '{"model":"qwen3.5:9b","messages":[{"role":"user","content":"hello"}]}'
# 测试 3: Claude Code
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_BASE_URL=http://localhost:11435
export ANTHROPIC_MODEL=qwen3.5:9b
echo "你是什么模型？" | claude --print
八、故障排除
8.1 问题诊断流程
┌─────────────────────────────────────────────────────────────┐
│ 故障诊断流程图 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 开始 │
│ │ │
│ ▼ │
│ ┌───────────────────┐ │
│ │ Claude Code 报错 │ │
│ │ 404 / 连接失败 │ │
│ └─────────┬─────────┘ │
│ │ │
│ ┌─────────┴─────────┐ │
│ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ │
│ │检查代理 │ │检查隧道 │ │
│ │:11435 │ │:11434 │ │
│ └────┬────┘ └────┬────┘ │
│ │ │ │
│ ▼ ▼ │
│ lsof -i :11435 lsof -i :11434 │
│ │ │ │
│ ▼ ▼ │
│ 未运行？ 未运行？ │
│ 启动代理 重建隧道 │
│ │ │ │
│ └──────────┬───────┘ │
│ ▼ │
│ ┌───────────────────┐ │
│ │ 测试 Ollama 直连 │ │
│ │ curl :11434 │ │
│ └─────────┬─────────┘ │
│ │ │
│ ▼ │
│ 正常？失败？ │
│ │ │ │
│ ▼ ▼ │
│ 完成 检查服务器 │
│ Ollama 状态 │
│ │
└─────────────────────────────────────────────────────────────┘
8.2 常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 404 错误 | API 路径不匹配 | 检查代理层是否运行 |
| 连接超时 | SSH 隧道断开 | 重新建立隧道 |
| 空响应 | max_tokens 问题 | 更新代理代码 |
| 模型未找到 | 模型未下载 | 执行 ollama pull |
九、性能优化
9.1 响应时间对比
┌─────────────────────────────────────────────────────────────┐
│ 模型性能对比 │
├─────────────────┬───────────────┬───────────────────────────┤
│ 模型 │ 响应时间 │ 显存需求 │
├─────────────────┼───────────────┼───────────────────────────┤
│ qwen3.5:9b │ ~13秒 │ ~8GB │
│ qwen3.5:35b │ ~30秒 │ ~24GB │
├─────────────────┴───────────────┴───────────────────────────┤
│ 测试环境: CPU 推理 / 32GB 内存 │
└─────────────────────────────────────────────────────────────┘
9.2 优化建议
- 使用 GPU 加速: 安装 CUDA 驱动，Ollama 自动检测 GPU
- 增加内存: 35B 模型需要 24GB+ 内存
- 调整温度参数: 降低 temperature 获得更快响应
十、总结
10.1 完成的功能
┌─────────────────────────────────────────────────────────────┐
│ 功能清单 │
├─────────────────────────────────────────────────────────────┤
│ │
│ [✓] Mac 本地运行 Claude Code │
│ [✓] 远程服务器部署 Ollama │
│ [✓] SSH 隧道安全连接 │
│ [✓] API 协议转换代理 │
│ [✓] 使用 qwen3.5:9b 模型 │
│ [✓] 完全私有的 AI 编程助手 │
│ │
└─────────────────────────────────────────────────────────────┘
10.2 方案优势
- 代码隐私: 所有代码不会上传到第三方
- 完全控制: 可更换任意本地模型
- 成本可控: 使用自有服务器资源
- 安全可靠: SSH 加密隧道传输
效果
但是本地服务器会很咆哮
参考链接
版权声明: 本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议。
本文链接: https://blog.csdn.net/your_username/article/details/xxxx
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
1
0- 0
已为社区贡献1条内容
所有评论(0)