# 手把手教程：让 Claude Code 使用自建 OpenAI 兼容代理

> 从零开始，解决国内无法直连 Anthropic 的问题，并为你的自建代理添加 Claude Code 支持。

## 背景

Claude Code 是 Anthropic 推出的强大 AI 编程助手，但在国内网络环境下，直接运行 `claude` 命令会遇到：

```
Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST
```

这是因为 Claude Code 启动时需要连接官方 API 进行验证。好在 Claude Code 支持通过环境变量配置第三方 API，我们可以让它在本地或自建代理上运行。

> 🚀 **配套开源项目**：本教程使用的自建代理正是 [LLM-Proxy-Gateway](https://github.com/yhyh0000/LLM-Proxy-Gateway)  
> 一个高性能、多 Key 池、支持优先级与自动故障转移的 LLM 智能代理网关，已内置 Claude Code 适配。



本教程将带你：
1. 跳过官方引导，进入 Claude Code
2. 配置第三方 API（包括自建代理）
3. 为 OpenAI 兼容的代理添加 Anthropic 协议适配（`/v1/messages` 端点）
4. 解决流式转换、模型选择等常见问题

最终效果：Claude Code 愉快地跑在你的代理上，就像在使用官方 Claude 一样。

---

## 第一步：跳过官方引导

Claude Code 首次启动时会尝试连接 Anthropic 服务器，我们需要让它“误以为”已经完成过引导。

找到配置文件（Windows 路径）：  
`C:\Users\<你的用户名>\.claude.json`

用文本编辑器打开，添加或修改：

```json
{
  "hasCompletedOnboarding": true
}
```

如果没有该文件，可以手动创建。保存后，重新运行 `claude`，应该会直接进入主题选择界面，而不再报网络错误。

---

## 第二步：配置第三方 API（直接使用现有代理）

如果你已经有第三方 OpenAI 兼容的 API（例如 DeepSeek、自建 vLLM 等），只需配置 Claude Code 指向它。

编辑配置文件 `~/.claude/settings.json`（Windows 路径 `%USERPROFILE%\.claude\settings.json`）：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的真实密钥",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-chat"
  },
  "theme": "dark"
}
```

- `ANTHROPIC_BASE_URL`：你的 API 地址，**不要加 `/v1` 后缀**。
- `ANTHROPIC_AUTH_TOKEN`：API 密钥（Bearer token）。
- `ANTHROPIC_DEFAULT_SONNET_MODEL`：覆盖 Claude Code 默认的 Sonnet 模型，填入你代理中实际可用的模型名。

配置完成后，重启 Claude Code，应该可以直接对话。

---

## 第三步：自建代理 – 搭建 OpenAI 兼容网关

有时我们需要完全自托管代理，比如集成多个 API 源、负载均衡、Token 统计等。本教程使用我开源的 [LLM-Proxy-Gateway](https://github.com/yhyh0000/LLM-Proxy-Gateway)（项目内 `proxy.py`），它提供：

- `/v1/chat/completions` 标准 OpenAI 端点
- 多 Key 池、优先级（P0 公益 / P1 免费 / P2 付费）
- 社区 Key 自动抓取、冷却与删除策略
- Token 使用统计

该代理默认监听 `http://127.0.0.1:8800`，返回的模型列表中有一个名为 `auto` 的模型（代表智能选择）。

### 测试代理是否正常

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

返回示例：
```json
{"object":"list","data":[{"id":"auto","object":"model","created":1779947583,"owned_by":"proxy"}]}
```

说明代理已运行。

---

## 第四步：为代理添加 Anthropic `/v1/messages` 适配

Claude Code 使用的是 Anthropic 协议（端点 `/v1/messages`），而我们的代理仅支持 OpenAI 格式。需要增加一个适配层，做请求/响应的双向转换。

### 4.1 添加转换函数

在 `proxy.py` 中（`handle_chat_request` 函数之前）添加以下代码：

```python
import json
import time

def anthropic_to_openai(anthropic_body: dict) -> dict:
    """将 Anthropic 请求转换为 OpenAI 格式"""
    openai_messages = []
    system_prompt = None

    # 处理 system 字段
    if "system" in anthropic_body:
        sys_content = anthropic_body["system"]
        if isinstance(sys_content, list):
            texts = [item.get("text", "") for item in sys_content if item.get("type") == "text"]
            system_prompt = "\n".join(texts)
        else:
            system_prompt = sys_content

    # 处理 messages
    for msg in anthropic_body.get("messages", []):
        role = msg["role"]
        content = msg["content"]
        if isinstance(content, list):
            # 提取纯文本
            text_parts = [block.get("text", "") for block in content if block.get("type") == "text"]
            content = " ".join(text_parts) if text_parts else ""
        openai_messages.append({"role": role, "content": content})

    # 构建 OpenAI payload
    openai_payload = {
        "model": anthropic_body.get("model", "auto"),
        "messages": openai_messages,
        "max_tokens": anthropic_body.get("max_tokens", 1024),
        "temperature": anthropic_body.get("temperature", 1.0),
        "stream": anthropic_body.get("stream", False),
    }
    if system_prompt:
        openai_payload["system"] = system_prompt

    # 处理工具调用（可选）
    if "tools" in anthropic_body:
        openai_tools = []
        for tool in anthropic_body["tools"]:
            openai_tools.append({
                "type": "function",
                "function": {
                    "name": tool["name"],
                    "description": tool.get("description", ""),
                    "parameters": tool.get("input_schema", {})
                }
            })
        openai_payload["tools"] = openai_tools
        if anthropic_body.get("tool_choice"):
            openai_payload["tool_choice"] = anthropic_body["tool_choice"]

    return openai_payload


def openai_to_anthropic(openai_response: dict, original_model: str) -> dict:
    """将 OpenAI 响应转换为 Anthropic 格式"""
    choice = openai_response.get("choices", [{}])[0]
    message = choice.get("message", {})
    content = message.get("content", "")
    finish_reason = choice.get("finish_reason", "")

    stop_reason_map = {
        "stop": "end_turn",
        "length": "max_tokens",
        "tool_calls": "tool_use",
        "content_filter": "content_filter"
    }
    stop_reason = stop_reason_map.get(finish_reason, "end_turn")

    # 构建 content 块
    content_blocks = []
    if "tool_calls" in message and message["tool_calls"]:
        for tc in message["tool_calls"]:
            content_blocks.append({
                "type": "tool_use",
                "id": tc.get("id", f"toolu_{hash(tc['function']['name'])}"),
                "name": tc["function"]["name"],
                "input": json.loads(tc["function"]["arguments"])
            })
    if content:
        content_blocks.append({"type": "text", "text": content})
    if not content_blocks:
        content_blocks = [{"type": "text", "text": ""}]

    usage = openai_response.get("usage", {})
    return {
        "id": openai_response.get("id", f"msg_{int(time.time())}"),
        "type": "message",
        "role": "assistant",
        "model": original_model,
        "content": content_blocks,
        "stop_reason": stop_reason,
        "stop_sequence": None,
        "usage": {
            "input_tokens": usage.get("prompt_tokens", 0),
            "output_tokens": usage.get("completion_tokens", 0)
        }
    }


def openai_to_anthropic_stream_chunk(openai_chunk: dict, model: str):
    """将 OpenAI 流式 chunk 转换为 Anthropic SSE 事件"""
    choices = openai_chunk.get("choices")
    if not choices or not isinstance(choices, list) or len(choices) == 0:
        return None
    choice = choices[0]
    delta = choice.get("delta", {})
    content = delta.get("content", "")
    finish_reason = choice.get("finish_reason", None)
    index = choice.get("index", 0)

    if content:
        return {
            "type": "content_block_delta",
            "index": index,
            "delta": {"type": "text_delta", "text": content}
        }
    if finish_reason:
        return {"type": "message_stop"}
    return None
```

### 4.2 添加 `/v1/messages` 路由

在 `app.route` 定义区域（例如 `/v1/chat/completions` 之后）添加：

```python
@app.route('/v1/messages', methods=['POST'])
def anthropic_messages():
    if not check_api_token():
        return jsonify({"error": "Unauthorized"}), 401

    try:
        anthropic_body = request.get_json()
        if not anthropic_body:
            return jsonify({"error": "Invalid JSON body"}), 400
    except:
        return jsonify({"error": "Invalid JSON body"}), 400

    openai_payload = anthropic_to_openai(anthropic_body)
    is_stream = anthropic_body.get("stream", False)

    headers = {"Content-Type": "application/json"}
    auth_header = request.headers.get("Authorization")
    if auth_header:
        headers["Authorization"] = auth_header

    local_url = f"http://127.0.0.1:{PROXY_PORT}/v1/chat/completions"

    try:
        upstream_resp = requests.post(
            local_url,
            headers=headers,
            json=openai_payload,
            timeout=REQUEST_TIMEOUT,
            stream=is_stream
        )

        if upstream_resp.status_code != 200:
            return Response(upstream_resp.text, status=upstream_resp.status_code, content_type="application/json")

        if is_stream:
            def generate():
                for line in upstream_resp.iter_lines():
                    if not line:
                        continue
                    line = line.decode('utf-8')
                    if line.startswith('data: '):
                        data_str = line[6:]
                        if data_str == '[DONE]':
                            yield 'data: {"type": "message_stop"}\n\n'
                            break
                        try:
                            openai_chunk = json.loads(data_str)
                            anth_chunk = openai_to_anthropic_stream_chunk(openai_chunk, anthropic_body.get("model", "auto"))
                            if anth_chunk:
                                yield f'data: {json.dumps(anth_chunk)}\n\n'
                        except Exception as e:
                            add_log(logging.ERROR, f"Stream conversion error: {e}")
                            continue
            response = Response(generate(), status=200)
            response.headers['Content-Type'] = 'text/event-stream'
            response.headers['Cache-Control'] = 'no-cache'
            return response
        else:
            openai_response = upstream_resp.json()
            anthropic_response = openai_to_anthropic(openai_response, anthropic_body.get("model", "auto"))
            return jsonify(anthropic_response)

    except Exception as e:
        add_log(logging.ERROR, f"/v1/messages error: {e}")
        return jsonify({"error": str(e)}), 500
```

注意：`PROXY_PORT` 需与你的监听端口一致（本例为 8800）。

### 4.3 重启代理

```bash
python proxy.py
```

现在代理同时支持：
- `POST /v1/chat/completions`（OpenAI 格式）
- `POST /v1/messages`（Anthropic 格式）

---

## 第五步：配置 Claude Code 使用自建代理

编辑 `~/.claude/settings.json`：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8800",
    "ANTHROPIC_AUTH_TOKEN": "123"
  },
  "theme": "dark"
}
```

> 如果你的代理启用了 API 鉴权（`ENABLE_API_AUTH=true`），则需要将 `ANTHROPIC_AUTH_TOKEN` 设置为 `API_ACCESS_TOKEN` 的值。

启动 Claude Code：

```bash
claude
```

进入后，运行 `/model` 选择 `auto` 模型（或你代理中实际支持的模型名），然后随便问一句话。

---

## 常见问题与解决

### 1. 报错 `selected model (auto) may not exist`

- 确保你的代理 `/v1/models` 返回的 `id` 与 `ANTHROPIC_DEFAULT_SONNET_MODEL` 设置一致。
- 在 Claude Code 中手动 `/model` 选择正确的模型。

### 2. 流式请求时报 `list index out of range`

- 某些后端（如 `mimo-v2-omni`）返回的流式 chunk 可能不标准，更新 `openai_to_anthropic_stream_chunk` 函数增加防御性判断（上面已提供完整版本）。

### 3. 一句话触发多次 API 请求

- Claude Code 默认会进行工具调用探测，如果模型不支持 tool use，可能产生额外请求。可以在 `anthropic_to_openai` 中注释掉 `tools` 相关代码，强制禁用工具调用。

### 4. Token 统计异常高

- 检查 Claude Code 是否在每次对话中重复发送了长 system prompt，或代理没有正确裁剪上下文。可以添加日志打印请求体内容来分析。

### 5. Windows 路径注意事项

- 配置文件位置：`C:\Users\<用户名>\.claude\settings.json`
- 跳过引导文件：`C:\Users\<用户名>\.claude.json`

---

## 💡 获取完整项目

本教程的代理代码已全部开源，欢迎使用、反馈和贡献：

👉 **GitHub 仓库**：[https://github.com/yhyh0000/LLM-Proxy-Gateway](https://github.com/yhyh0000/LLM-Proxy-Gateway)

如果觉得有用，别忘了点亮 ⭐ Star 支持一下！

---

## 最终效果

成功运行后，你会看到类似这样的界面：

```
❯ 你好
● 你好！有什么我可以帮你的吗？
```

同时代理日志会显示：

```
INFO:proxy:流式请求成功 供应商: 小米mimo 模型: mimo-v2-omni
```

恭喜！你现在已经让 Claude Code 愉快地运行在自建代理上了。

---

## 总结

本教程涵盖了：

1. 解决 Claude Code 国内无法连接的初始问题
2. 配置第三方 API 的方法（直接或通过自建代理）
3. 为 OpenAI 兼容代理添加 Anthropic 协议适配层
4. 处理流式转换、模型选择等实战坑点

通过这种方式，你可以灵活地将 Claude Code 对接任何 OpenAI 兼容的后端（包括本地 vLLM、Ollama、DeepSeek 等），享受 AI 编程助手的便利，同时保持对数据和费用的完全控制。

如果你有其他自建代理或特殊需求，修改适配函数即可。Happy coding!

手把手教程：让 Claude Code 使用自建 OpenAI 兼容代理

# 搭建一个零成本、永不失联的大模型 API 网关（附完整代码）

你是否曾为调用大模型 API 时的高昂费用而心疼？是否因为网上找来的免费 Key 经常失效、频繁手动切换而烦恼？如果有一个工具，能自动抓取免费的 API Key，并在背后悄无声息地帮你调度、切换，让聊天机器人永远不中断，而且完全免费，你想不想要？

今天我们就来手把手搭建一个开源、轻量、智能的 LLM API 代理网关。它像一个贴心的管家，帮你收集所有可用的免费 Key，按优先级使用，并在 Key 失效时瞬间切换到下一个，对你的聊天机器人（AstrBot、OpenClaw 等）完全透明。



## 痛点与解决思路

### 我们面临的困境

- **API 调用太贵**：个人开发者和小团队很难承担每月高昂的 Token 费用。
- **免费 Key 寿命短**：社区分享、中转站赠送的 Key 通常几分钟到几小时就会失效或限流。
- **手动更换太麻烦**：机器人正在运行，突然报错，你得登录服务器，手动更换配置中的 Key，服务就中断了。

### 这套方案如何应对？

这个项目是一个多层防御的智能网关：

- **P0 层（最高优先）**：薅羊毛专用。爬虫定时从社区中转站抓取大量临时免费 Key，先用这些“快消品”，不用白不用。
- **P1 层（稳定后备）**：官方免费资源。你自己申请的 Google Gemini、硅基流动、Groq 等每日有免费额度的官方 Key。当所有 P0 都挂了，系统无缝降级到这里。
- **P2 层（最终保障）**：付费兜底。你自己的 OpenAI 或 DeepSeek 付费 Key，平时一分钱不花，仅在极端情况（所有免费渠道全断）下救急。

核心理念：优先烧完不稳定但免费的羊毛，官方稳定免费资源作为第二梯队，自己的付费 Key 当作保险丝。系统会自动在它们之间切换，而你只需在聊天框里正常说话。

## 技术架构一览

项目采用 Python + Flask + Waitress，单文件设计，极简部署。所有 Key 存储在内存中，无磁盘 I/O 延迟，响应飞快。

```
┌──────────────────────────────────────────────┐
│                   proxy.py (单文件)           │
│                                              │
│  ┌──────────┐      ┌─────────────────────┐  │
│  │  爬虫线程 │─────▶│   内存 KeyPool       │  │
│  │(定时抓取) │      │  P0: 中转 / P1: 免费 │  │
│  └──────────┘      │  P2: 付费            │  │
│                    └─────────────────────┘  │
│                         │                   │
│                    ┌────▼────┐              │
│                    │ 热备用调度器 │              │
│                    └────┬────┘              │
│                         │                   │
│                    ┌────▼────┐              │
│                    │ 格式适配 & 请求转发 │              │
│                    └────┬────┘              │
│                         │                   │
│                    ┌────▼────┐              │
│                    │Flask+Waitress│              │
│                    │ 对外开放 API │              │
│                    └─────────┘              │
└──────────────────────────────────────────────┘
```

核心模块：

- **爬虫线程**：每 5 分钟抓取指定的 Key 数据源，并合并到内存池。
- **热备用调度器**：维护一个 `active_key` 和 `backup_key`，当主 Key 失效时零延迟切换。
- **格式适配**：自动识别 OpenAI 格式和 Google Gemini 原生格式，无需额外转换服务。
- **Web 管理面板**：增删供应商、数据源，查看日志和系统状态，全部在浏览器完成。

## 杀手级特性详解

### 1. 多源动态数据源，告别“写完即弃”

在 Web 面板上可以随时添加新的免费 Key 来源（URL），爬虫会自动遍历所有源抓取 Key。你不再需要修改代码，今天发现一个好用的中转站，粘贴 URL 就能立刻开始薅羊毛。数据源支持两种格式：

- **标准 groups 格式**：`{"groups": [{"keys": [{"api_key": "...", "model": "..."}]}]}`
- **简化数组格式**：`[{"key": "...", "models": ["..."], "provider": "..."}]`

社区中转站普遍采用这种格式，非常适合批量抓取。

### 2. 多供应商支持：不止于中转，更拥抱免费生态

网关已经不再局限于社区中转 Key，而是将更多稳定、有官方免费额度的供应商纳入体系。

- **NVIDIA NIM**：每天免费调用 **40 次/分钟**，无需绑定信用卡。Endpoint 填 `https://integrate.api.nvidia.com/v1`，模型名使用 `nvidia/nemotron-3-super-120b-a12b` 等。
- **GitHub Models**：拥有众多模型，适合代码开发。Endpoint 填 `https://models.github.ai/inference`，模型名使用 `openai/gpt-4o-mini` 等。
- **Cloudflare Workers AI**：每日 **10,000 个 Neurons** 免费额度。Endpoint 填 `https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1`，模型名使用 `@cf/meta/llama-3.1-8b-instruct` 等。
- **Google Gemini**：适用对话和内容生成。Endpoint 填 `https://generativelanguage.googleapis.com/v1beta`，模型名使用 `gemini-2.5-flash` 等。
- **魔搭社区 (ModelScope)**：国内直连体验好，每日 **2000 次** 免费调用。Endpoint 填 `https://api-inference.modelscope.cn/v1`，模型名使用 `deepseek-ai/DeepSeek-V4-Pro` 等。
- **Cerebras & OpenRouter**：支持通过 /models 接口探测和 OpenAI 兼容调用。

通过将这些官方免费额度资源加入 P1 层，网关实现了更高的稳定性和可用性，确保在社区 Key 失效时，仍有充裕的免费资源可供调度。

### 3. 智能调度：热备用+粘性+优先级

网关在设计上力求对上游友好，避免因频繁轮询导致 API 被限流：

- **优先级调度**：严格按 **P0（社区中转）> P1（官方免费）> P2（付费兜底）** 的顺序使用 Key。
- **粘度保护**：P0 Key 失败后先冷却 60 秒，连续失败 3 次才删除；P1/P2 Key 失败仅冷却不删除。
- **热备用切换**：维护一个备用 Key，当当前 Key 失效时无缝切换。
- **`model: "auto"` 智能路由**：根据提示词内容（语言、是否包含代码等）自动选择最合适的模型。

通过引入冷却（Cooldown）与成功重置（Success Reset）的机制，网关避免了因一次临时错误就删除 Key 的情况，极大地保护了有限且宝贵的免费资源。

### 4. 自动无感切换

当请求中 `model` 为 `"auto"` 时，网关按优先级循环尝试所有可用 Key，直到成功或全部失败。每次尝试使用该 Key 的第一个支持模型（`verified_models[0]` 或 `selected_models[0]`）。切换过程对前端完全透明，只返回最终成功响应或全部失败错误。

### 5. 极简请求处理：完全透传

网关的设计原则是尽可能不修改请求体，而是原样透传给上游。为了兼容不支持多模态的社区 Key，网关会**自动移除 `messages` 中的 `image_url` 字段**，只保留文本内容，避免上游 400 错误。同时，网关会根据供应商类型（OpenAI 兼容或 Google Gemini）自动构建请求 URL 和认证头。

### 6. 社区 Key 采集与粘度管理

爬虫线程从 `sources.json` 配置的数据源抓取社区 Key，**每 5 分钟**更新一次。社区 Key 失败时先冷却 60 秒，连续失败 3 次才删除。成功请求重置失败计数，实现“粘度延续”。爬虫更新时，保留现有社区 Key 的冷却时间和失败计数，避免因短暂故障而被误删。

### 7. Web 端可视化模型管理

告别修改配置文件的繁琐操作！在 Web 管理面板的供应商编辑页面，现在可以：

- **直接添加/删除模型**：通过输入框手动添加模型，支持任意文本（如 `openai/gpt-4o-mini`、`@cf/meta/llama-3-8b-instruct`）。
- **一键探测模型**：点击“探测可用模型”按钮，后端自动调用上游 API，返回该供应商支持的模型列表。
- **智能过滤**：根据供应商类型自动过滤无效模型（例如 NVIDIA 只显示 `nvidia/` 开头的模型）。
- **多选追加**：探测到的模型会弹出模态框供用户勾选，点击“添加选中模型”即可追加到当前列表，不会覆盖已有模型。
- **实时保存**：所有修改即时保存到 `providers.json`，无需重启网关。


### 8. 供应商手动测试

每个稳定供应商都配有“测试”按钮，点击后网关会发送一条简单的测试消息（例如“Say 'OK' if you are working.”）到上游 API，并显示状态码、延迟和响应内容。测试成功后，网关会自动更新该供应商的平均延迟（指数加权移动平均），并在表格中刷新显示。测试失败不会删除或冷却 Key，仅展示错误信息。

### 9. 零依赖部署与异步上报

- **单文件设计**：整个项目仅依赖 `proxy.py` 和 `templates/admin.html`，无需复杂配置。
- **内置 Web 服务器**：使用 `waitress` 作为 WSGI 服务器，支持多线程并发。
- **异步更新机制**：爬虫更新 Key 池、供应商探测、测试等操作均采用异步线程，不影响主请求处理。
- **日志与监控**：所有请求日志写入 `proxy.log`，管理面板提供分页日志查看和健康状态卡片。

## Web 管理面板

访问 `http://127.0.0.1:8800/admin`（默认账号密码 `admin/admin`），你可以：

- **添加/编辑供应商**：配置名称、Endpoint、API Key、优先级、供应商类型，并手动管理模型列表。
- **探测模型**：点击按钮自动获取上游支持的模型列表，勾选后追加到当前模型池。
- **测试供应商**：一键测试连通性，显示状态码、延迟和响应预览。
- **管理数据源**：添加/删除社区 Key 采集源（URL），支持自定义目标模型和 API 端点。
- **查看实时日志**：分页浏览最近 200 条日志，支持自动刷新（3 秒间隔）。
- **系统健康监控**：查看 Key 池统计（P0/P1/P2 数量、活跃 Key 数）、运行时间、爬虫状态、请求成功率等。

![image.png](/static/img/d53fce8acadb84b7106ead0cae6d2563.image.webp)
## 部署指南

1.  **下载代码**：将 `proxy.py` 和 `templates/admin.html` 保存到同一目录。
2.  **安装依赖**：`pip install flask waitress requests cryptography`
3.  **运行**：`python proxy.py`
4.  **配置数据源**：编辑 `sources.json`，添加社区 Key 采集 URL（默认已配置一个测试源）。
5.  **添加稳定供应商**：通过管理面板添加 P1/P2 供应商（如 NVIDIA、Cloudflare、Google 等）。
6.  **配置客户端**：将你的聊天机器人（如 AstrBot、OpenClaw）的 API 地址改为 `http://你的服务器IP:8800/v1`，API Key 任意填写。

## 完整代码

- **后端 `proxy.py`**：支持多供应商、多源数据抓取、热备用切换、自动清理多模态内容。
- **前端 `admin.html`**：模型标签管理、探测模型模态框、日志自动刷新、供应商测试。

## 总结

这个网关的设计和实现凝聚了我们许多思考和实践。

-   **它不是一个简单的代理，而是一个智能的“资源调度中心”**。它通过多层防御和自动切换，将不同来源、不同稳定性的 API Key 融合成一个统一、可靠的接口。
-   **它的核心优势在于“降本”和“增效”**。P0层帮你最大限度利用免费羊毛，降低调用成本；P1层的官方免费资源和粘度管理保证了服务的稳定；而透明的Web管理面板和故障排查设计，则显著提升了开发和维护效率。
-   **它的价值在于“免费”与“稳定”的平衡**。通过精心设计的冷却与调度机制，我们能在享受免费资源的同时，确保服务的连续性和可靠性。这套方案不仅解决了当下的成本问题，更为未来接入更多优质、免费的AI服务奠定了基础。

对于个人开发者来说，这是一个极具性价比的解决方案。它让我们可以用极低的成本，体验到各种前沿的大模型能力。

希望这个项目的实现思路和最终成果能对你有所帮助。完整的代码和更详尽的技术细节，可以在下面的链接中找到。如果你有任何疑问或想法，也欢迎随时交流。

**项目文档与代码仓库地址：**
[https://github.com/yhyh0000/LLM-Proxy-Gateway](https://github.com/yhyh0000/LLM-Proxy-Gateway)

搭建一个零成本、永不失联的大模型 API 网关（附完整代码）

🚀 从随手拍到电商大片：基于 ComfyUI + Qwen 的全自动 AI 生图工具

淘宝生意参谋市场排行数据采集教程

# ComfyUI 部署与 API 调用完整指南

本文档总结了从零开始部署 ComfyUI、下载模型、配置 API 工作流，并通过 Python 调用 API 自动生成图像的完整流程。

---

## 一、环境准备与 ComfyUI 部署

### 1.1 系统要求
- Ubuntu 20.04/22.04（推荐）
- NVIDIA 显卡（建议 24GB 显存，如 4090）
- 已安装 NVIDIA 驱动（≥ 550 版本）和 CUDA 12.4+

### 1.2 安装 ComfyUI（源码方式）

```bash
# 克隆仓库（使用国内镜像加速）
git clone https://gitclone.com/github.com/Comfy-Org/ComfyUI.git
# 或直接使用官方地址
git clone https://github.com/Comfy-Org/ComfyUI.git

cd ComfyUI
python -m venv venv
source venv/bin/activate
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt
```

### 1.3 启动 ComfyUI（限制双 GPU）

```bash
# 限制使用 GPU 0 和 1，开启外部访问
CUDA_VISIBLE_DEVICES=0,1 python main.py --listen 0.0.0.0 --port 32794
```

> 如果出现 `RuntimeError: The NVIDIA driver on your system is too old`，请升级驱动到 550+ 或安装 CUDA 12.1 版本的 PyTorch。

---

## 二、下载常用模型

### 2.1 配置国内镜像（加速下载）

```bash
export HF_ENDPOINT=https://hf-mirror.com
# 永久生效
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc
```

### 2.2 下载 Z-Image-Turbo 模型（适用于文生图）

```bash
cd ~/comfyUI/ComfyUI
mkdir -p models/diffusion_models models/text_encoders models/vae

# 主模型
wget -c https://hf-mirror.com/Comfy-Org/z_image_turbo/resolve/main/split_files/diffusion_models/z_image_turbo_bf16.safetensors -P models/diffusion_models/
# 文本编码器
wget -c https://hf-mirror.com/Comfy-Org/z_image_turbo/resolve/main/split_files/text_encoders/qwen_3_4b.safetensors -P models/text_encoders/
# VAE
wget -c https://hf-mirror.com/Comfy-Org/z_image_turbo/resolve/main/split_files/vae/ae.safetensors -P models/vae/
```

### 2.3 下载 Qwen-Image 系列（电商换背景）

```bash
mkdir -p models/loras
# 主模型
wget -c https://hf-mirror.com/Comfy-Org/Qwen-Image_ComfyUI/resolve/main/split_files/diffusion_models/qwen_image_2512_fp8_e4m3fn.safetensors -P models/diffusion_models/
# LoRA
wget -c https://hf-mirror.com/lightx2v/Qwen-Image-2512-Lightning/resolve/main/Qwen-Image-2512-Lightning-4steps-V1.0-fp32.safetensors -P models/loras/
# 文本编码器
wget -c https://hf-mirror.com/Comfy-Org/Qwen-Image_ComfyUI/resolve/main/split_files/text_encoders/qwen_2.5_vl_7b_fp8_scaled.safetensors -P models/text_encoders/
# VAE
wget -c https://hf-mirror.com/Comfy-Org/Qwen-Image_ComfyUI/resolve/main/split_files/vae/qwen_image_vae.safetensors -P models/vae/
```

### 2.4 下载 SD1.5 / SDXL 基础模型（可选）

```bash
# DreamShaper XL（单文件版）
wget -c https://hf-mirror.com/jayparmr/DreamShaper_XL1_0_Alpha2/resolve/main/DreamShaper_XL1_0_Alpha2.safetensors -P models/checkpoints/
```

---

## 三、导出 API 格式工作流

1. 在 ComfyUI 界面中加载你的工作流。
2. 点击右上角齿轮图标（Settings），勾选 **“Enable Dev mode Options”**。
3. 点击菜单中的 **“Save (API Format)”**，保存为 `workflow_api.json`。

> 普通 “Save” 保存的文件包含界面布局信息，不适合 API 调用。

---

## 四、Python 调用 ComfyUI API

### 4.1 通用脚本（自动识别节点类型）

```python
import json
import time
import random
import requests
from urllib.parse import urljoin

def find_node_by_class(workflow, class_type):
    for node_id, node in workflow.items():
        if node.get("class_type") == class_type:
            return node_id
    return None

def queue_prompt(workflow, server_url):
    resp = requests.post(urljoin(server_url, "/prompt"), json={"prompt": workflow})
    resp.raise_for_status()
    return resp.json()["prompt_id"]

def get_history(prompt_id, server_url, max_wait=120):
    url = urljoin(server_url, f"/history/{prompt_id}")
    start = time.time()
    while time.time() - start < max_wait:
        resp = requests.get(url)
        if resp.status_code == 200:
            data = resp.json()
            if prompt_id in data:
                return data[prompt_id]
        time.sleep(1)
    return None

def save_images(history, server_url, output_prefix):
    outputs = history.get("outputs", {})
    saved = []
    for node_out in outputs.values():
        for img in node_out.get("images", []):
            filename = img["filename"]
            img_data = requests.get(urljoin(server_url, f"/view?filename={filename}")).content
            local_name = f"{output_prefix}_{filename}"
            with open(local_name, "wb") as f:
                f.write(img_data)
            print(f"已保存: {local_name}")
            saved.append(local_name)
    return saved

def main():
    import argparse
    parser = argparse.ArgumentParser()
    parser.add_argument("-p", "--prompt", required=True)
    parser.add_argument("--seed", type=int, default=None)
    parser.add_argument("--steps", type=int, default=None)
    parser.add_argument("--width", type=int, default=None)
    parser.add_argument("--height", type=int, default=None)
    parser.add_argument("--server", default="http://127.0.0.1:32794")
    parser.add_argument("--workflow", default="workflow_api.json")
    parser.add_argument("--output", default="output")
    args = parser.parse_args()

    with open(args.workflow, "r") as f:
        workflow = json.load(f)

    # 设置提示词
    text_node = find_node_by_class(workflow, "CLIPTextEncode")
    if text_node:
        workflow[text_node]["inputs"]["text"] = args.prompt

    # 设置采样器
    sampler_node = find_node_by_class(workflow, "KSampler") or find_node_by_class(workflow, "SamplerCustom")
    if sampler_node:
        workflow[sampler_node]["inputs"]["seed"] = args.seed or random.randint(1, 10**9)
        if args.steps:
            workflow[sampler_node]["inputs"]["steps"] = args.steps

    # 设置尺寸
    latent_node = find_node_by_class(workflow, "EmptyLatentImage") or find_node_by_class(workflow, "EmptySD3LatentImage")
    if latent_node and (args.width or args.height):
        if args.width:
            workflow[latent_node]["inputs"]["width"] = args.width
        if args.height:
            workflow[latent_node]["inputs"]["height"] = args.height

    prompt_id = queue_prompt(workflow, args.server)
    print(f"任务 ID: {prompt_id}")
    history = get_history(prompt_id, args.server)
    if history:
        save_images(history, args.server, args.output)
    else:
        print("超时或生成失败")

if __name__ == "__main__":
    main()
```

### 4.2 使用示例

```bash
# 基本生成
python comfyui_api.py -p "a cute cat" --server http://111.2.199.31:32794 --workflow 文生图.json

# 完整参数
python comfyui_api.py \
  -p "Traditional Chinese landscape, misty mountains" \
  --seed 88888888 \
  --steps 8 \
  --width 1024 --height 1024 \
  --output landscape \
  --server http://111.2.199.31:32794
```

---

## 五、安装缺失的自定义节点

### 5.1 安装 ComfyUI Manager

```bash
cd ~/comfyUI/ComfyUI/custom_nodes
git clone https://github.com/ltdrdata/ComfyUI-Manager.git
```

重启 ComfyUI 时添加 `--enable-manager` 参数。

### 5.2 解决安全策略错误

若遇到 `security_level must be normal or below`，修改配置文件：

```bash
nano ~/comfyUI/ComfyUI/user/default/ComfyUI-Manager/config.ini
```

添加：
```ini
[default]
security_level = normal-
network_mode = personal_cloud
```

重启 ComfyUI。

### 5.3 手动安装常见节点

```bash
cd custom_nodes
git clone https://github.com/Fannovel16/comfyui_controlnet_aux.git
git clone https://github.com/cubiq/ComfyUI_IPAdapter_plus.git
git clone https://github.com/chflame163/ComfyUI_LayerStyle.git
git clone https://github.com/ssitu/ComfyUI_UltimateSDUpscale.git
```

安装后重启 ComfyUI。

---



## 六、常见问题

| 问题 | 解决方法 |
|------|----------|
| 连接不上 ComfyUI 服务 | 确认启动时加了 `--listen 0.0.0.0`，防火墙放行端口 |
| 模型找不到 | 检查 `models/` 目录结构，使用 `extra_model_paths.yaml` 添加外部路径 |
| 节点报红 | 通过 Manager 安装缺失节点，或手动 git clone |
| 生成图片全黑/报错 | 查看 ComfyUI 终端日志，通常是模型路径错误或显存不足 |
| 下载模型慢 | 使用 `hf-mirror.com` 镜像，或 `aria2c` 多线程下载 |

---

## 七、总结

通过上述步骤，你已经能够：
- 在服务器上部署 ComfyUI 并限制双 GPU 使用
- 下载常用电商模型（Z-Image、Qwen-Image 等）
- 导出 API 格式工作流并通过 Python 调用
- 安装自定义节点解决缺失依赖
- 处理常见网络和安全错误

现在你可以将这套流程集成到电商自动化系统中，实现“输入提示词 → 自动生成产品图”的完整链路。如有任何问题，欢迎继续交流。

手把手教程：让 Claude Code 使用自建 OpenAI 兼容代理

背景

搭建一个零成本、永不失联的大模型 API 网关（附完整代码）

从随手拍到电商大片：基于ComfyUI+Qwen的全自动多视角AI生图工具

淘宝生意参谋市场排行数据采集工具使用文档

1. 准备工作

ComfyUI 部署与 API 调用完整指南

一、环境准备与 ComfyUI 部署

1.1 系统要求