# 其他客户端接入

在支持自定义 OpenAI 兼容服务的客户端中配置 G 网，选择模型并验证连接。

## 选择合适的接入方式 [#选择合适的接入方式]

支持自定义 OpenAI 兼容服务的聊天或编程客户端，可以通过 G 网调用模型。先确认客户端采用的协议，再设置网关地址：

| 客户端协议 | 服务地址 | 接口文档 |
| --- | --- | --- |
| OpenAI Chat Completions | `https://api.gfw.net/v1` | [OpenAI 兼容 API](/docs/openai-api) |
| OpenAI Responses | `https://api.gfw.net/v1` | [Responses API](/docs/responses) |
| Anthropic Messages | `https://api.gfw.net` | [Anthropic 兼容 API](/docs/anthropic-api) |

客户端可能自行追加 `/v1`。如果配置字段已经明确要求根地址，填 `https://api.gfw.net`，并检查最终请求是否只出现一次 `/v1`。

## 通用配置 [#通用配置]

在客户端新建一个自定义服务，使用以下参数：

| 设置项 | 配置 |
| --- | --- |
| 服务名称 | `G 网`，仅用于客户端显示 |
| 服务类型 | OpenAI Compatible 或 OpenAI 兼容服务 |
| API Base URL | `https://api.gfw.net/v1`，以客户端字段说明为准 |
| API Key | 在 [控制台](/console/keys) 创建的模型调用密钥 |
| 模型 ID | 使用 [模型库](/models) 中的 `model_code`，例如 `deepseek-v4-pro` |

先关闭工具调用、联网搜索和其他扩展，用一条短文本验证基础连接。文字对话应选择对话模型；图片和视频任务使用对应媒体端点。

## Cline 与 Roo Code [#cline-与-roo-code]

在服务提供商设置中选择支持自定义地址的 OpenAI Compatible 类型，填写 Base URL、API Key 和模型 ID。不同版本的字段名称可能略有差异，核心是发送到 `/v1/chat/completions` 的请求。

编程 Agent 还需要模型支持工具调用。通过基础连接测试后，再启用工具功能；如果客户端要求特定工具消息格式，应按 [工具调用](/docs/tool-calls) 核对兼容性。


**提示**

同一个模型能够回答文本问题，不代表它与所有 Agent 的工具循环完全兼容。不要把 Chat Completions 的工具能力推定为 Responses 的完整工具能力；两者的边界分别见接口文档。


## Cherry Studio 等聊天客户端 [#cherry-studio-等聊天客户端]

创建一个 OpenAI 兼容提供商并填写通用配置。如果客户端能够从服务发现模型，可以先尝试获取目录；发现失败时，手动添加模型库中的真实模型 ID。

将新模型加入会话后发送一条短文本。开启视觉输入或推理模式前，确认模型支持对应能力。客户端自带的联网、知识库或插件属于客户端功能，是否经过模型服务取决于具体配置。

## 用 HTTP 请求排查连接 [#用-http-请求排查连接]

设置 `GFW_API_KEY` 后，先验证模型目录请求：

```bash
curl --fail-with-body --silent --show-error --max-time 30 \
  https://api.gfw.net/v1/models \
  -H "Authorization: Bearer ${GFW_API_KEY}" \
  -H 'Accept: application/json'
```

目录成功后，再按 [快速开始](/docs/quickstart) 发起最小对话。这样可以区分地址或鉴权问题与客户端消息格式问题。

| 现象 | 排查方式 |
| --- | --- |
| 401 | 检查是否使用模型 API Key，而非控制台登录令牌；检查粘贴空格 |
| 404 或 HTML 响应 | 检查地址、协议和重复的 `/v1` |
| 找不到模型 | 从模型库复制真实模型 ID，核对 Key 的模型访问权限 |
| 文字正常、工具失败 | 检查模型工具能力和客户端协议，先查看工具调用错误 |
| 连续超时 | 设置客户端超时，保留请求时间和模型 ID，查看调用日志 |

## 密钥与工具权限 [#密钥与工具权限]

把密钥保存在客户端的凭据设置中，避免写入项目源码或截图。对编程 Agent 的文件写入、命令执行和外部访问设置符合任务范围的权限。G 网返回模型输出；本地工具的执行和授权由客户端管理。

## 相关文档 [#相关文档]

- [Claude Code 接入](/docs/claude-code)
- [Codex CLI 接入](/docs/codex)
- [模型与能力](/docs/models)
- [工具调用](/docs/tool-calls)
- [用量与调用日志](/docs/usage-logs)
- [错误码与重试](/docs/errors)