# 主流客户端集成

除了官方 CLI 工具（Claude Code / Codex），RelayFlows 兼容所有遵循 Anthropic / OpenAI 协议规范的第三方客户端。下面是主流 GUI 与 IDE 插件的接入配置。

通用前提：已在 API 密钥 页面创建好密钥，且密钥所在分组启用了你要用的上游产品。

# 先选对 Base URL

我们提供三个 Base URL。第三方客户端建议用带协议前缀的那两个：

为什么要区分：根地址两种协议共用，「获取模型列表」返回的是两家合并的清单。第三方客户端会把整份清单塞进模型选择器，而每个协议入口只能发对应那一家的模型 —— 从 Claude 客户端的下拉里挑一个 gpt-5.5，或者从 OpenAI 客户端里挑一个 claude-sonnet-4-6，请求都会失败。带前缀的地址让列表只出该协议能用的模型，从源头避免这个坑。

顺带还解决一个问题：部分客户端（如 Hermes Agent）是靠 Base URL 里有没有 /anthropic 来判断该用 Anthropic 协议还是退回 OpenAI 协议的。用带前缀的地址，这个自动判断刚好落对。

已经在用根地址的配置不需要改，行为完全没变。前缀只是多给一个更省心的选择。

两个前缀下的路径都同时接受带和不带 /v1 两种写法（客户端对这个的处理五花八门），所以 /anthropic/v1/messages 和 /anthropic/messages 都通。

# Cherry Studio

跨平台桌面 LLM 客户端，支持多模型并行、对话历史本地存储。

# 接入步骤（Claude）

1. 打开 Cherry Studio → 设置 → 模型服务
2. 添加自定义服务，填写：
   • 服务商名称：RelayFlows-Claude（自定义）
   • API Host：https://api.relayflows.com/anthropic
   • API Key：你的 sk-rf-... 密钥
   • 协议适配：选择 Anthropic
3. 点「获取模型列表」—— 这时返回的就只有 Claude 模型，直接全选即可

# 接入步骤（GPT）

重复上述步骤再加一个服务商：API Host 换成 https://api.relayflows.com/openai，协议适配 改成 OpenAI。模型列表同理只返回 GPT。

# Hermes Agent

Nous Research 的自主 agent，走 Anthropic Messages 协议。

# 接入步骤

配置里填两项：

base_url: https://api.relayflows.com/anthropic
api_mode: anthropic_messages

api_mode 必须显式写。 Hermes 会靠 base_url 里有没有 /anthropic 自动判断协议，但这个自动判断有静默回退的毛病 —— 猜错时它不会报错，而是直接按 OpenAI chat-completions 发请求，然后在很下游的地方给你一个看不懂的失败。显式写死这一项就绕开了整条猜测逻辑。

# 两个正常现象，别当故障

• 模型探测打的是 /anthropic/models，不是 /anthropic/v1/models。它把配置的 base_url 当成已经带版本了。两个路径我们都注册了，所以两种行为都通。
• 每条真实消息后约 34 毫秒会多一个请求。 那是 Hermes 自动生成对话标题用的，tools 为空、只有几百字节。也就是说一轮对话在 用量统计 里会看到两条记录，第二条很小。这是客户端行为，不是重复计费。

# OpenClaw

自托管的 AI 助手，配置在 ~/.openclaw/openclaw.json。

# ⚠️ 必须新建一个 provider id，不要改内置的 anthropic

OpenClaw 的内置 anthropic provider 忽略自定义 baseUrl —— 你把 models.providers.anthropic.baseUrl 指向别处，配置校验能过、网关也确实写进了 models.json，但一个字节的流量都不会走过去（上游 issue #56679）。所以要新起一个 provider id。

# 配置示例

{
  "models": {
    "providers": {
      "relayflows": {
        "baseUrl": "https://api.relayflows.com/anthropic",
        "apiKey": "${RELAYFLOWS_API_KEY}",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-sonnet-4-6",
            "name": "Claude Sonnet 4.6",
            "contextWindow": 200000,
            "maxTokens": 64000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "relayflows/claude-sonnet-4-6" },
      "models": { "relayflows/claude-sonnet-4-6": { "alias": "RelayFlows" } }
    }
  }
}

${RELAYFLOWS_API_KEY} 从 ~/.openclaw/env 读，密钥不用写进 JSON。

不想手写 JSON 的话：配置向导的 provider 列表拉到最底下，选 Custom Provider (Any OpenAI or Anthropic compatible endpoint)。

# 三个容易踩的点

1. 模型要注册两次。 models.providers.relayflows.models[] 里要有一行，agents.defaults.models 的白名单里也要有 —— 而且白名单的 key 必须是全限定名 relayflows/claude-sonnet-4-6，不能只写模型 id。少任何一边都不生效。
2. baseUrl 不带 /v1。 anthropic-messages 协议下 OpenClaw 自己会拼 /v1/messages。（如果你要的是 GPT，就再加一个 provider："api": "openai-completions" + "baseUrl": "https://api.relayflows.com/openai/v1"，那条要带 /v1。）
3. contextWindow 填 200000。 这是我们这条链路真能兑现的上限，跟模型列表里返回的一致。不填的话 OpenClaw 默认也是 200000，正好；但别自己往上写 1M —— 发出去会失败。

顺带一提：对非官方直连的 Anthropic 端点，OpenClaw 会自动不发那些隐式 beta 头（claude-code-*、interleaved-thinking-* 之类）。这对我们正好是对的，不用去 headers 里手动补。

# VS Code — Continue 插件

VS Code 内最流行的 AI 编程助手，支持 inline 补全、聊天侧栏、代码改写。

# 安装

1. VS Code 扩展市场搜索 Continue 安装
2. 点击 Continue 侧栏图标 → 设置（齿轮）→ 打开 config.json

# 配置示例

{
  "models": [
    {
      "title": "Claude Sonnet 4.6 (RelayFlows)",
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "apiBase": "https://api.relayflows.com/anthropic",
      "apiKey": "sk-rf-你的密钥"
    },
    {
      "title": "GPT-5.5 (RelayFlows)",
      "provider": "openai",
      "model": "gpt-5.5",
      "apiBase": "https://api.relayflows.com/openai/v1",
      "apiKey": "sk-rf-你的密钥"
    }
  ],
  "tabAutocompleteModel": {
    "title": "Haiku 4.5 (RelayFlows)",
    "provider": "anthropic",
    "model": "claude-haiku-4-5-20251001",
    "apiBase": "https://api.relayflows.com/anthropic",
    "apiKey": "sk-rf-你的密钥"
  }
}

Continue 会自己在 apiBase 后面拼路径：Anthropic 拼 /v1/messages，OpenAI 拼 /chat/completions。所以 Anthropic 那条不要自己带 /v1，OpenAI 那条要带。

上面的模型名只是示例。可用模型以你自己的列表为准 —— 客户端点一次「获取模型列表」，或直接 curl -H "Authorization: Bearer sk-rf-..." https://api.relayflows.com/anthropic/models。有些模型名带日期后缀（如 claude-haiku-4-5-20251001），照列表原样填，别自己简写。

# VS Code — Claude Code 官方插件

如果你已安装 Claude Code CLI（见 客户端下载与安装），VS Code 插件会自动复用 CLI 的配置，无需重复填写 API key。

# Cursor

Cursor 只支持 OpenAI 协议，所以只能用 GPT 系模型。

1. Cursor → Settings → Models
2. 关闭官方提供的 OpenAI / Anthropic 模型
3. 在 OpenAI API Key 一栏填入：
   • Override OpenAI Base URL：https://api.relayflows.com/openai/v1
   • API Key：sk-rf-你的密钥
4. 添加自定义模型名（以 https://api.relayflows.com/openai/models 返回的为准）：
   • gpt-5.5
   • gpt-5.3-codex

Cursor 里不要填 Claude 模型名。 Cursor 走的是 OpenAI 协议入口，该入口只连 ChatGPT 上游，填 claude-* 会直接失败。想在编辑器里用 Claude，请用 Claude Code 官方插件或 Continue（见上）。

# Zed

Zed 编辑器（Rust 写的高性能编辑器）通过 settings.json 配置：

{
  "assistant": {
    "default_model": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-6"
    },
    "version": "2"
  },
  "language_models": {
    "anthropic": {
      "api_url": "https://api.relayflows.com/anthropic",
      "low_speed_timeout_in_seconds": 60
    }
  }
}

API key 通过 Zed 的 assistant: set api key 命令面板输入。

# JetBrains IDE

# 官方 AI Assistant 插件

JetBrains AI Assistant 官方版本目前只支持自家 OAuth 登录，不开放自定义 endpoint。如需用 RelayFlows，改用下面的第三方插件之一：

• CodeGPT — 支持自定义 OpenAI / Anthropic base URL
• Continue — 同 VS Code 配置，JetBrains 也有插件

# CodeGPT 配置示例

1. Settings → Tools → CodeGPT → Providers → Custom OpenAI
2. API Endpoint：https://api.relayflows.com/openai/v1/chat/completions
3. API Key：sk-rf-你的密钥
4. Model：gpt-5.5 或其他你启用的 GPT 模型

# Open WebUI

自部署的 ChatGPT 风格 Web UI，只走 OpenAI 协议（所以是 GPT 系模型）。

# 管理员配置（全站生效）

1. ⚙️ Admin Settings → Connections → OpenAI → ➕ Add Connection
2. 填两项：
   • URL：https://api.relayflows.com/openai/v1 —— /v1 后缀必须带
   • API Key：sk-rf-你的密钥
3. 保存。我们支持 /models 自动探测，所以模型会自己列出来（而且只有 GPT 系，不会混进 Claude）—— 不需要手填 Model IDs (Filter) 白名单。

每条 connection 都有开关，可以临时停用而不删配置。

# 用环境变量代替（Docker）

docker run -d -p 3000:8080 \
  -e ENABLE_OPENAI_API=true \
  -e OPENAI_API_BASE_URL=https://api.relayflows.com/openai/v1 \
  -e OPENAI_API_KEY=sk-rf-你的密钥 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

# 用户级 Direct Connections

管理员开启后，普通用户可以自己配：User Settings → Connections → ➕，Base URL 同上。

注意这条路是浏览器直接发请求，受 CORS 限制。我们的接口对此是放行的，但如果你在自己前面又套了一层反代，记得把 CORS 头带上。

# LobeChat / NextChat

同样只走 OpenAI 协议：

API key 一栏都填 sk-rf-...。

# n8n / Dify / 工作流平台

低代码工作流平台中接入 RelayFlows：

• n8n：HTTP Request 节点，URL 填 https://api.relayflows.com/openai/v1/chat/completions，Header 加 Authorization: Bearer sk-rf-...
• Dify：模型供应商 → OpenAI → API endpoint 填 https://api.relayflows.com/openai/v1
• FastGPT：同 Dify 配置方式

需要 Claude 模型的话，这些平台若支持 Anthropic 供应商，就把地址填 https://api.relayflows.com/anthropic。

# 自己写代码接入

任何符合 OpenAI / Anthropic 官方 SDK 规范的代码都可以直接换 base URL：

# Python (Anthropic SDK)

from anthropic import Anthropic
client = Anthropic(
    api_key="sk-rf-你的密钥",
    base_url="https://api.relayflows.com/anthropic",
)
msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(msg.content[0].text)

client.models.list() 在这个 base_url 下也只会返回 Claude 模型。

# Node.js (OpenAI SDK)

import OpenAI from 'openai';
const client = new OpenAI({
  apiKey: 'sk-rf-你的密钥',
  baseURL: 'https://api.relayflows.com/openai/v1',
});
const response = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: 'Hello' }],
});
console.log(response.choices[0].message.content);

# 接入完成后做什么

1. 跑一次最简单请求验证连通性（见各客户端的"测试连接"按钮）
2. 进 控制台 → 用量统计 看刚才的请求是否计入
3. 进 服务状态 看上游路由的健康度
4. 出现错误优先查 错误码参考 与 常见问题