Claude Desktop 使用内网大模型 完整配置教程（macOS）

Claude Desktop 使用内网大模型 完整配置教程（macOS）

📖 背景

Claude Desktop 默认连 Anthropic 官方 API，需要登录 Anthropic 账号才能用。

本教程教你如何让 Claude Desktop 连接公司/实验室内网的大模型 （如 vLLM、Ollama 等 Anthropic 兼容服务），无需 Anthropic 账号。

---

🧩 工作原理

Claude Desktop ──► 127.0.0.1:8800（本机端口转发）──► 内网模型服务器

三个关键点：

1. Claude Desktop 有内置 Gateway 模式，可以指向任何 Anthropic 兼容 API
2. 只能通过 macOS 配置描述文件（.mobileconfig）开启，改 JSON 文件无效
3. Claude Desktop 强制要求 HTTPS，或者 HTTP 但必须是 127.0.0.1，所以内网 IP 需要走本机转发

---

✅ 你需要准备

• macOS 13+（本教程基于 macOS 26.2）
• 已安装 Claude Desktop 应用
• 内网模型服务器地址（IP + 端口），服务端支持 Anthropic /v1/messages 接口
• Python 3（macOS 自带）

---

🔧 配置步骤

第 1 步：测试内网模型是否可用

打开终端，替换下面的 IP 和模型名，执行：

curl http://你的内网IP:端口/v1/messages \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "你的模型名",
    "max_tokens": 30,
    "messages": [{"role": "user", "content": "hi"}]
  }'

✅ 成功标志 ：返回 JSON 里有 "type":"message" 和 "role":"assistant" 字段。
❌ 失败 ：检查 IP、端口、网络连通性。如果服务端不支持 /v1/messages（只支持 OpenAI /v1/chat/completions），需要额外部署 LiteLLM 做协议转换，本教程不覆盖这种情况。

---

第 2 步：启动本机端口转发

Claude Desktop 不允许连非 HTTPS 的远程 IP，所以需要在本机起一个中转。

新建文件 ~/tcp_forward.py，内容如下（记得把 TARGET_HOST 和 TARGET_PORT 改成你的内网地址）：

import socket, threading

LISTEN_HOST = '127.0.0.1'
LISTEN_PORT = 8800              # 本机监听端口
TARGET_HOST = '22.17.85.29'  # 👈 改成你的内网 IP
TARGET_PORT = 8000              # 👈 改成你的内网端口

def forward(src, dst):
    try:
        while True:
            data = src.recv(65536)
            if not data: break
            dst.sendall(data)
    except: pass
    finally:
        try: src.close()
        except: pass
        try: dst.close()
        except: pass

def handle(client):
    try:
        target = socket.create_connection((TARGET_HOST, TARGET_PORT))
        threading.Thread(target=forward, args=(client, target), daemon=True).start()
        threading.Thread(target=forward, args=(target, client), daemon=True).start()
    except Exception as e:
        client.close()

srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
srv.bind((LISTEN_HOST, LISTEN_PORT))
srv.listen(100)
print(f"Forwarding {LISTEN_HOST}:{LISTEN_PORT} -> {TARGET_HOST}:{TARGET_PORT}")
while True:
    c, _ = srv.accept()
    threading.Thread(target=handle, args=(c,), daemon=True).start()

启动转发：

nohup python3 ~/tcp_forward.py > /tmp/tcp_forward.log 2>&1 &

验证：

curl http://127.0.0.1:8800/v1/models

能返回模型列表就说明转发通了。

💡 开机自启 ：转发进程关机会失效。永久可用请配 launchd 或放到 crontab -e 的 @reboot 里。

---

第 3 步：生成并安装配置描述文件

新建文件 ~/Downloads/claude-gateway.mobileconfig，内容如下：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadType</key>
            <string>com.anthropic.claudefordesktop</string>
            <key>PayloadIdentifier</key>
            <string>com.anthropic.claudefordesktop.gateway</string>
            <key>PayloadUUID</key>
            <string>30429B1A-961B-4BFA-8334-B1BB836A8A1F</string>
            <key>PayloadDisplayName</key>
            <string>Claude Desktop Gateway</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadEnabled</key>
            <true/>
            <key>inferenceProvider</key>
            <string>gateway</string>
            <key>inferenceGatewayBaseUrl</key>
            <string>http://127.0.0.1:8800</string>
            <key>inferenceGatewayApiKey</key>
            <string>not-needed</string>
            <key>inferenceGatewayAuthScheme</key>
            <string>bearer</string>
            <key>inferenceModels</key>
            <string>["你的模型名"]</string>
        </dict>
    </array>
    <key>PayloadDisplayName</key>
    <string>Claude Desktop Gateway</string>
    <key>PayloadIdentifier</key>
    <string>com.anthropic.claudefordesktop.profile</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>81655315-8D9A-449F-B411-1E53FA9EE1D9</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
    <key>PayloadScope</key>
    <string>User</string>
</dict>
</plist>

⚠️ 必改项：

• inferenceModels 里的 你的模型名 改成实际模型 ID
• 如果第 2 步改了端口，http://127.0.0.1:8800 也要同步改

💡 提示 ：每次修改配置重新安装，建议换两个新的 UUID（命令行 uuidgen 生成），避免与旧配置冲突。

安装描述文件：

1. 在 Finder 里双击 claude-gateway.mobileconfig
2. 系统弹出 "Profile downloaded"
3. 打开 系统设置 → 隐私与安全性 → 描述文件（或在顶部搜索 "描述文件"）
4. 找到 "Claude Desktop Gateway" ，双击 → 点击 "安装"
5. 输入 Mac 密码确认

---

第 4 步：验证 Claude Desktop

1. 完全退出 Claude Desktop（Cmd+Q，不是关窗口）
2. 重新启动 Claude Desktop
3. 应该出现 "How do you want to use Claude?" 界面，有两个选项：
   • ✅ Continue with Gateway（你要点这个）
   • Sign in to Anthropic
4. 点 Continue with Gateway，直接进入主界面
5. 左侧导航应该只有 Cowork 和 Code 两个 tab（Chat 不可用）

---

🐛 故障排查

问题 1：启动后显示 "Needs attention"

点击 "copy details"，查看错误信息。常见原因：

错误信息	原因	解决
baseUrl: must use https (or http on 127.0.0.1)	URL 不是 HTTPS 也不是 localhost	确保用了本机转发 http://127.0.0.1:8800
Model discovery: 0 found	转发不通 / 模型服务挂了	curl http://127.0.0.1:8800/v1/models 自查
其他配置解析错误	mobileconfig 格式问题	检查 XML 是否合法

问题 2：没看到 Gateway 选项，直接跳 Anthropic 登录

• 描述文件没装成功 → 系统设置里确认 "Claude Desktop Gateway" 已安装
• Claude Desktop 没完全退出 → pkill -9 -f "Claude.app" 后再启动

问题 3：Python 转发进程突然停了

# 看日志
tail /tmp/tcp_forward.log

# 重启转发
pkill -f tcp_forward.py
nohup python3 ~/tcp_forward.py > /tmp/tcp_forward.log 2>&1 &

---

🗑 卸载（改回官方 Claude）

1. 系统设置 → 通用 → 设备管理（或 隐私与安全性 → 描述文件）
2. 选中 "Claude Desktop Gateway" ，点 "−" 按钮移除
3. 停止端口转发：pkill -f tcp_forward.py
4. 重启 Claude Desktop，恢复为 Anthropic 登录界面

---

📌 已知限制

• Chat tab 不可用（Gateway 模式只支持 Cowork 和 Code）
• 模型必须支持 Anthropic /v1/messages 格式。只支持 OpenAI 格式的模型（如纯 Ollama）需要额外用 LiteLLM 做协议转换
• 端口转发进程需要一直运行，关机后需要手动重启（或配 launchd 自启）

---

🙏 参考资料

• Claude Support: Install and configure Claude Cowork with third-party platforms
• Claude Desktop 官方 MDM 配置键参考（同上文档末尾）