# 扣子（Coze）接入 QCode 教程

照着下面 7 步做，你可以按自己的扣子账号版本选对路径，把 QCode 的 Claude、GPT 与国产模型接入扣子智能体或工作流，并在后台核对请求记录。


**一句话结论**：扣子没有面向个人账号的「全局自定义模型 Base URL」开关。**个人与团队账号**请通过「自定义插件」或「工作流 HTTP 请求节点」直连 QCode 接口，可同时调用 `claude-opus-5-5`（Anthropic 接口）和 `gpt-6.2-sol`（OpenAI 兼容接口）；**企业旗舰版管理员**可在「扣子编程（`code.coze.cn`）→ 企业组织管理 → 模型接入 → 自定义模型」原生接入 `gpt-6.2-sol` 与国产模型，但该入口协议固定为 OpenAI Chat Completions，**不支持 Claude**。

| 接入路径 | 适用账号 | 可用 QCode 模型 | 接入地址 | 鉴权方式 |
|---|---|---|---|---|
| 自定义插件 / 工作流 HTTP（Claude） | 所有扣子账号 | `claude-opus-5-5` 等 Claude 系列 | `https://api.qcode.cc/api/v1/messages` | 请求头 `x-api-key: cr_xxxxxxxx` 与 `anthropic-version: 2023-06-01` |
| 自定义插件 / 工作流 HTTP（GPT / 国产） | 所有扣子账号 | `gpt-6.2-sol`、国产模型 | `https://api.qcode.cc/openai/v1/chat/completions` | 请求头 `Authorization: Bearer cr_xxxxxxxx` |
| 原生自定义模型（扣子编程后台） | 仅企业旗舰版组织管理员 | `gpt-6.2-sol`、国产模型（**不支持 Claude**） | `https://api.qcode.cc/openai/v1`（自动拼 `/chat/completions`） | 鉴权选 `Authorization` 填 `cr_xxxxxxxx`（备选 Header） |

核对于 2026-11-22 · 扣子（coze.cn）与扣子编程（code.coze.cn）· 纯文字结构化指南


[扣子（Coze）](https://www.coze.cn) 是面向智能体与工作流搭建的云端平台，包含主产品「扣子」（`www.coze.cn`）和面向企业与低代码管理的「扣子编程」（`code.coze.cn`）两个界面。开始动手前，先了解四条真实的产品限制，避免在界面里反复寻找不存在的选项：

> **真实支持度与限制边界**：
> 1. **强制登录扣子账号**：无论使用网页端还是桌面端，均须通过手机号、邮箱或扫码登录扣子平台账号，无法跳过平台账号离线使用。
> 2. **原生「模型接入」仅限企业旗舰版管理员**：按扣子官方文档，原生「模型接入 → 自定义模型」入口**只对企业旗舰版开放，且只有组织超级管理员或管理员能看到并配置**；普通个人账号与普通工作空间看不到该入口。
> 3. **原生自定义模型不支持 Claude**：扣子原生自定义模型的 API 协议固定为 OpenAI Chat/completions，且固定要求上游支持流式响应（`stream=true`），没有 Anthropic Messages 协议选项。QCode 的 OpenAI 兼容端点不接受 Claude 模型，因此 `claude-opus-5-5` **只能通过自定义插件或工作流 HTTP 请求调用**。
> 4. **HTTP 插件 / 工作流方案的能力边界**：个人与团队账号通过 HTTP 请求调用 QCode 时，QCode 是作为智能体的外部工具或工作流处理节点运行的，无法替换智能体默认的主调度模型，且需等待完整 JSON 返回后再呈现结果（非原生逐字流式输出）。


- **适用平台**：浏览器网页端（`www.coze.cn` / `code.coze.cn`）；可选 Windows / macOS 桌面端
- **接入路径**：自定义插件 / 工作流 HTTP 请求（所有账号）；原生自定义模型（仅企业旗舰版管理员）
- **内容核对于**：2026-11-22
- **预计用时**：10–15 分钟
- **需要准备**：已登录的扣子账号；一个 `cr_` 开头的 QCode API 密钥



- 已注册并能正常登录扣子（[www.coze.cn](https://www.coze.cn)）；若准备使用原生自定义模型，确认所属组织为**企业旗舰版**、当前账号为**组织超级管理员或管理员**，且可访问扣子编程（[code.coze.cn](https://code.coze.cn)）
- 已注册 QCode.cc，并在[控制台](https://qcode.cc/dashboard)复制好 `cr_` 开头的 API 密钥。还没有账号？先[注册 QCode](https://qcode.cc/auth/sign-up?utm_source=docs.qcode.cc&utm_medium=tut_before&utm_campaign=knowledge_base&src=docs-ide-coze-before)，在[定价页](https://qcode.cc/pricing?utm_source=docs.qcode.cc&utm_medium=tut_before&utm_campaign=knowledge_base&src=docs-ide-coze-before)选择合适的方案，再到[控制台](https://qcode.cc/dashboard)创建密钥
- 明确要调用的模型：需要 `claude-opus-5-5` 请走**路径 A（HTTP 插件 / 工作流）**；使用 `gpt-6.2-sol` 或国产模型，个人账号走**路径 A**，企业旗舰版管理员可走**路径 B（原生自定义模型）**
- 当前网络能正常访问 `www.coze.cn`、`code.coze.cn`、`api.qcode.cc` 与 `probe.qcode.cc`


**需要 API Key？**

还没有 QCode 账号的话，先[注册 QCode](https://qcode.cc/auth/sign-up?utm_source=docs.qcode.cc&utm_medium=tut_key_step&utm_campaign=knowledge_base&src=docs-ide-coze-key)。想按实际用量付费，可先购买一个[按量包](https://qcode.cc/pay-as-you-go?utm_source=docs.qcode.cc&utm_medium=tut_key_step&utm_campaign=knowledge_base&src=docs-ide-coze-key)，再到[控制台](https://qcode.cc/dashboard)创建并复制以 `cr_` 开头的完整 API 密钥。


## 准备：确认入口与选择接入路径

扣子全部配置都可以直接在浏览器中完成，无需专门安装桌面客户端。如果你习惯使用桌面端，只能从 [扣子官网](https://www.coze.cn) 首页将鼠标移至「下载桌面端」下载 Windows 或 macOS 安装包（扣子不是开源桌面软件，没有 GitHub Releases、winget 或微软商店安装包；安装后默认进入扣子智能体工作台，配置企业自定义模型仍需打开浏览器访问 `code.coze.cn`）。

根据你的账号版本与目标模型，在下方选择对应路径：

**路径 A：个人 / 团队账号（自定义插件 / HTTP 请求）**

- **适用人群**：所有扣子账号（包括普通个人账号、团队工作空间，以及需要调用 `claude-opus-5-5` 的企业用户）。
- **支持模型**：同时支持 `claude-opus-5-5`（走 Anthropic 端点 `https://api.qcode.cc/api/v1/messages`）与 `gpt-6.2-sol`、国产模型（走 OpenAI 兼容端点 `https://api.qcode.cc/openai/v1/chat/completions`）。
- **操作步骤**：完成下方 **第 1 步 → 第 2 步 → 第 3 步 → 第 4 步 → 第 7 步**（跳过仅限企业管理员的第 5、6 步）。


**路径 B：企业旗舰版管理员（原生自定义模型）**

- **适用人群**：已开通扣子**企业旗舰版**、且当前账号为**组织超级管理员或管理员**的用户。
- **支持模型**：支持 `gpt-6.2-sol` 与国产模型（走 `https://api.qcode.cc/openai/v1`）；**不支持 Claude 系列**（扣子原生入口不提供 Anthropic 协议）。
- **核心优势**：接入并授权工作空间后，成员可在智能体编排页的模型选择器里像内置模型一样直接切换，且原生支持流式响应。
- **操作步骤**：完成下方 **第 1 步 → 第 5 步 → 第 6 步 → 第 7 步**（无需配置第 2–4 步的 HTTP 插件）。


## 分步配置指南



### 先在本地验证 QCode 密钥与端点连通

进入扣子后台之前，先在本地终端（Windows PowerShell、macOS 终端或 Linux Shell）发一次最小测试请求，确认你的 `cr_` 密钥和目标模型正常可用。这样如果后面在扣子里遇到报错，就能立刻判断问题出在扣子表单配置而不是密钥本身。

按你准备调用的模型家族切换选项卡，把 `cr_xxxxxxxx` 替换为你的真实密钥后执行：

**验证 Claude（claude-opus-5-5）**

```bash
curl -sS https://api.qcode.cc/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: cr_xxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "你好，请用一句话介绍你自己"}
    ]
  }'
```


**验证 GPT（gpt-6.2-sol）**

```bash
curl -sS https://api.qcode.cc/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cr_xxxxxxxx" \
  -d '{
    "model": "gpt-6.2-sol",
    "stream": false,
    "messages": [
      {"role": "user", "content": "你好，请用一句话介绍你自己"}
    ]
  }'
```



做对了你会看到：终端返回一段完整的 JSON；Claude 响应的 `content[0].text` 字段，或 GPT 响应的 `choices[0].message.content` 字段中包含中文自我介绍，且没有 `error` 对象。


**卡住了？本地测试返回 401 或 model_not_available_on_endpoint**

按顺序核对三点：1）密钥必须完整以 `cr_` 开头，引号和冒号后不要多粘贴换行或多余空格；2）`claude-opus-5-5` 必须请求 `https://api.qcode.cc/api/v1/messages` 并使用 `x-api-key` 请求头，不能发往 `/openai/v1`；3）`gpt-6.2-sol` 必须请求 `https://api.qcode.cc/openai/v1/chat/completions` 并使用 `Authorization: Bearer cr_xxxxxxxx`。在 Windows PowerShell 中如遇单引号转义问题，可改用 `curl.exe` 或通过扣子工作流 HTTP 节点的测试功能直接验证。




### 路径 A：在工作流 HTTP 节点或自定义插件里填入 QCode 接口

登录 [扣子主站](https://www.coze.cn) 并进入目标工作空间，按你的使用方式二选一：

- **工作流 HTTP 请求节点（上手最快）**：新建或打开一个工作流，在画布中添加「HTTP 请求」节点，并将请求方法设为 `POST`。
- **自定义插件（便于多智能体复用）**：进入工作空间的插件 / 资源库页面，选择基于已有 HTTP 服务创建自定义插件，再添加一个 `POST` 方法的工具。

按你需要调用的模型家族，照下面对应选项卡填写 URL、请求头（Headers）和 JSON 请求体（Body）。其中 `{{user_prompt}}` 代表你在扣子工作流输入节点或插件入参里定义的文本变量，实际配置时按扣子界面提供的变量选择器插入即可：

**Claude（Anthropic 协议 · claude-opus-5-5）**

| 配置项 | 填写内容 |
|---|---|
| 请求方法 | `POST` |
| 完整请求 URL | `https://api.qcode.cc/api/v1/messages`（若插件分开填写基础 URL 与路径：基础 URL 填 `https://api.qcode.cc/api`，路径填 `/v1/messages`） |
| Header 1 | `Content-Type`: `application/json` |
| Header 2 | `x-api-key`: `cr_xxxxxxxx`（替换为你的密钥，**不加** `Bearer ` 前缀） |
| Header 3 | `anthropic-version`: `2023-06-01` |

Body 类型选 `JSON`，填写：

```json
{
  "model": "claude-opus-5-5",
  "max_tokens": 2048,
  "messages": [
    {
      "role": "user",
      "content": "{{user_prompt}}"
    }
  ]
}
```


**GPT / 国产模型（OpenAI 兼容 · gpt-6.2-sol）**

| 配置项 | 填写内容 |
|---|---|
| 请求方法 | `POST` |
| 完整请求 URL | `https://api.qcode.cc/openai/v1/chat/completions`（若插件分开填写基础 URL 与路径：基础 URL 填 `https://api.qcode.cc/openai/v1`，路径填 `/chat/completions`） |
| Header 1 | `Content-Type`: `application/json` |
| Header 2 | `Authorization`: `Bearer cr_xxxxxxxx`（`Bearer` 与密钥之间保留一个英文空格） |

Body 类型选 `JSON`，填写：

```json
{
  "model": "gpt-6.2-sol",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": "{{user_prompt}}"
    }
  ]
}
```

如需改用国产模型，只需把 `"model"` 改成 `glm-5.3`、`kimi-k3`、`deepseek-v4-pro` 或 `qwen3.8-max` 等 OpenAI 兼容端点支持的模型 ID。



做对了你会看到：请求方法为 `POST`，URL 与模型家族协议严格匹配，Headers 里密钥和版本头齐全，JSON 编辑区没有语法红线提示。


**卡住了？JSON 提示格式错误，或不知道怎么填多轮历史消息**

先确认所有引号都是英文半角双引号 `"`，最后一个字段后没有多余逗号，且 `"stream"` 保持 `false`（工作流 HTTP 节点和插件默认按单次 JSON 响应解析，开启流式会导致返回体变成多行 `data:` 片段而无法解析）。如果用户输入里可能包含双引号或换行符，建议通过扣子工作流或插件的「JSON 参数绑定 / 结构化入参」传入，不要把未转义的长文本直接硬拼进 JSON 字符串。




### 路径 A：配置响应字段提取并试运行

HTTP 请求跑通后，需要把返回 JSON 里的正文内容提取出来，供后续工作流输出节点或智能体读取。两种协议的返回路径不同，按你配置的接口对照填写输出参数映射：

**提取 Claude 响应（Anthropic 格式）**

典型响应结构：

```json
{
  "id": "msg_01...",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "你好，我是 Claude，可以帮助你完成推理、写作与编程任务。"
    }
  ],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 32
  }
}
```

- **正文提取路径**：`content[0].text`（在工作流里可结合「代码节点」或输出参数配置直接读取 `body.content[0].text`）。


**提取 GPT / 国产模型响应（OpenAI 兼容格式）**

典型响应结构：

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gpt-6.2-sol",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好，我可以帮你处理问答、分析与代码编写。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 24,
    "total_tokens": 42
  }
}
```

- **正文提取路径**：`choices[0].message.content`（读取 `body.choices[0].message.content` 即可拿到纯文本回答）。


配置好输出参数后，点击工作流或插件工具的「试运行 / 调试」，给 `user_prompt` 传入一句「你好，请用一句话介绍你自己」，观察返回状态码和提取出的文本结果。


做对了你会看到：调试返回 HTTP 状态码 `200`，输出面板里成功提取出不含外层 JSON 结构的纯文本中文回复。


**卡住了？试运行超时或输出字段提取为空**

1）如果请求超时，先把 `max_tokens` 适当调小（例如 `1024`）测试短回复，并将 URL 域名从 `api.qcode.cc` 换为亚洲节点 `asia.qcode.cc`（例如 `https://asia.qcode.cc/api/v1/messages` 或 `https://asia.qcode.cc/openai/v1/chat/completions`）；2）如果状态码是 `200` 但提取出的字段为空，展开原始响应体 `body`，检查是否把 `content[0].text` 与 `choices[0].message.content` 填反，或者忘了把响应体字符串先解析为 JSON 对象。




### 路径 A：发布并绑定到扣子智能体

调试通过后，将你的自定义插件或工作流发布到当前工作空间，然后打开目标智能体的编排页：

1. 在编排页的「技能」区域，将刚才发布的插件或工作流添加到智能体中。
2. 在「人设与回复逻辑（系统提示词）」中明确写出触发规则，避免扣子默认模型跳过插件直接自己回答。例如：

```text
当用户提出复杂代码编写、深度分析或明确要求使用 QCode 模型回答时，必须调用已绑定的 QCode 插件/工作流，把用户的完整问题传入 `user_prompt` 参数，并将工具返回的文本结果准确呈现给用户，不要自行编造替代答案。
```

保存后，在右侧「预览与调试」对话框里发一句触发上述条件的消息（例如「请调用 QCode 工具，用一句话介绍你自己」），观察调试过程是否实际触发了插件或工作流调用。


做对了你会看到：预览区的调用过程里出现刚才绑定的插件或工作流执行记录，状态成功，且对话气泡输出了由 QCode 返回的回复。


**卡住了？智能体没有调用插件，直接自己回复了**

优先检查三处：1）插件或工作流必须已点击「发布」，仅保存草稿无法被智能体稳定调用；2）插件工具的英文/中文描述以及 `user_prompt` 参数说明要写清楚用途，方便调度模型识别；3）如果你希望**每一轮用户输入都强制走 QCode 而不由默认模型决定是否触发**，可以把智能体切换为工作流驱动模式，让用户输入直接进入包含 QCode HTTP 节点的工作流。




### 路径 B（仅企业旗舰版管理员）：在扣子编程后台接入原生自定义模型

> 本步骤与第 6 步**仅适用于扣子企业旗舰版的组织超级管理员或管理员**。如果你是普通个人账号，请直接跳到第 7 步核对请求记录。

1. 浏览器打开扣子编程 [code.coze.cn](https://code.coze.cn) 并登录你的企业管理员账号。
2. 点击页面左下角个人头像，选择所属的**企业账号**，再点击该企业组织的「设置」图标，进入「企业组织管理」。
3. 在「企业组织管理」中依次进入 **「模型接入 → 自定义模型」**，点击 **「接入模型」**。
4. 在弹窗中按下表填写参数，完成后按需勾选模型能力（如工具调用、深度思考）与上下文长度并保存：

| 表单字段 | 填写内容 | 说明 |
|---|---|---|
| 模型展示名称 | `QCode GPT 6.2 Sol`（可自定义） | 仅影响成员在界面上看到的名称 |
| 模型唯一标识 | `gpt-6.2-sol` | 会直接写入请求的 `model` 字段；也可填 `glm-5.3` 等国产模型 ID，**切勿填 Claude 模型** |
| 模型 API URL | `https://api.qcode.cc/openai/v1` | 扣子会自动拼接 `/chat/completions`，**不要**再手写 `/chat/completions` |
| API 协议 | `OpenAI Chat/completions` | 平台固定选项，无法更改 |
| 鉴权方式 | `Authorization` | 备选 `Header` 方式（见下方折叠提示） |
| 鉴权密钥 | `cr_xxxxxxxx` | 填写 QCode 密钥；存储方式选明文即可，不必接入火山 KMS |


做对了你会看到：保存成功后回到「自定义模型」列表，刚接入的 `QCode GPT 6.2 Sol` 正常出现在列表中，没有停运或异常提示。


**卡住了？找不到「模型接入」，或测试连接报 401 / 404**

- **完全看不到「模型接入」**：确认当前选中的是企业账号而非个人账号，且该企业组织已开通**企业旗舰版**、你的角色是组织超级管理员或管理员。不满足条件时该入口不会显示，请改走路径 A。
- **提示 <code>404</code>**：检查「模型 API URL」是否只填到 `/openai/v1`，不要在末尾多写 `/chat/completions` 或多余斜杠。
- **提示 <code>401</code> / 鉴权失败**：先确认密钥以 `cr_` 开头且无多余空格；若选 `Authorization` 仍报 `401`，可改选 `Header` 鉴权方式，Header Key 填 `Authorization`，Header Value 填 `Bearer cr_xxxxxxxx` 后重新保存测试。




### 路径 B（仅企业旗舰版管理员）：授权可用工作空间并在智能体中选用

扣子接入自定义模型后，**默认对所有工作空间都不可用**，必须由管理员手动打开授权，成员才能看到：

1. 留在「企业组织管理 → 模型接入 → 自定义模型」列表，找到刚接入的模型，点击该行右侧的 **「… → 修改可用空间」**。
2. 在弹窗中打开目标工作空间的启用开关并保存。
3. 切回扣子智能体编排页（或让目标工作空间成员打开编排页），点开模型选择器，在 **「自定义模型」** 分组中选中刚接入的 `QCode GPT 6.2 Sol`。
4. 在右侧对话框输入「你好，请用一句话介绍你自己」并发送，观察流式回复是否正常逐字输出。


做对了你会看到：目标工作空间的可用开关处于开启状态；智能体模型列表的「自定义模型」分组里能选中该模型，发送消息后正常流式回复，无 `401`、`404` 或 `model not found` 报错。


**卡住了？成员看不到模型，或发送消息后一直转圈无回复**

- **成员看不到模型**：回到「修改可用空间」确认选中的是成员当前所在的那个工作空间，并让成员刷新编排页。
- **提示模型不存在**：核对「模型唯一标识」是否误填成了展示名称（例如填了 `QCode GPT 6.2 Sol`）；它必须是 QCode 实际支持的模型 ID（如 `gpt-6.2-sol`）。
- **发消息一直转圈**：扣子原生自定义模型固定以流式模式（`stream=true`）请求上游；确认 URL 填写为 `https://api.qcode.cc/openai/v1`（大陆环境也可改用 `https://asia.qcode.cc/openai/v1`）且没有被企业出网策略拦截。




### 到 probe.qcode.cc 核对请求记录

无论你走的是路径 A 还是路径 B，最后都建议核对一次真实网关日志，确认回复确实来自 QCode 而不是扣子内置模型代答：

1. 在浏览器打开 [probe.qcode.cc](https://probe.qcode.cc/)。
2. 粘贴你在扣子里使用的同一把 `cr_` API 密钥，点击「查询」。
3. 向下滚动到请求列表，核对最新一条记录的请求时间是否与刚才在扣子内调试或对话的时刻一致，且状态码列显示 `200`。


做对了你会看到：请求列表顶部出现与刚才测试时刻吻合的记录，状态显示 `200`，并有对应的首字耗时与总耗时数据。




## 验证成功

核对下面几项，全部吻合就说明扣子已经稳定接通 QCode：

- 本地测试命令对 `claude-opus-5-5` 或 `gpt-6.2-sol` 均返回 `200` 与有效文本；
- **路径 A**：扣子工作流 HTTP 节点或自定义插件试运行返回 `200`，成功提取出 `content[0].text`（Claude）或 `choices[0].message.content`（GPT / 国产），并在智能体预览区可见工具调用成功；
- **路径 B**：企业旗舰版「自定义模型」状态正常、目标工作空间开关已开启，成员在智能体「自定义模型」分组选中 `gpt-6.2-sol` 后能收到流式回复；
- 在 [probe.qcode.cc](https://probe.qcode.cc/) 使用同一把密钥查到对应时间、状态码为 `200` 的请求记录。


### 全部完成

你已经把 QCode 接入扣子，并清楚掌握了自定义插件 / HTTP 请求与企业原生自定义模型两条路径的边界。接下来可以：

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)
- [国产模型接入](/docs/usage/cn-models)
- [计费说明](/docs/reference/billing)
- [故障排查](/docs/reference/troubleshooting)
- 接下来：在[定价页](https://qcode.cc/pricing?utm_source=docs.qcode.cc&utm_medium=tut_done&utm_campaign=knowledge_base&src=docs-ide-coze-done)比较各个方案
- 回到[控制台](https://qcode.cc/dashboard)查看用量和余额


## 常见报错

| 报错现象 / 原文 | 原因 | 怎么办 |
|---|---|---|
| 找不到「模型接入 → 自定义模型」入口 | 原生自定义模型仅向企业旗舰版的组织超级管理员或管理员开放，普通个人账号无此菜单 | 确认是否切到企业账号且已开通企业旗舰版；个人或普通团队账号请直接采用本教程的**路径 A（自定义插件 / 工作流 HTTP 请求）** |
| `model_not_available_on_endpoint` | 把 `claude-opus-5-5` 填进了 OpenAI 兼容端点（`/openai/v1`）或扣子原生自定义模型 | QCode 的 OpenAI 兼容端点不接受 Claude。调用 `claude-opus-5-5` 必须通过 HTTP 请求直连 Anthropic 端点 `https://api.qcode.cc/api/v1/messages`；扣子原生自定义模型只能填 `gpt-6.2-sol` 或国产模型 |
| `404 Not Found` | URL 路径拼写不匹配：原生自定义模型多写了 `/chat/completions`，或 HTTP 插件漏写了路径后缀 | 原生自定义模型的「模型 API URL」只填到 `https://api.qcode.cc/openai/v1`（扣子会自动拼 `/chat/completions`）；HTTP 请求节点则必须填完整地址（`/api/v1/messages` 或 `/openai/v1/chat/completions`） |
| `401 Unauthorized` / 鉴权失败 | 密钥不完整、含前后空格，或鉴权头格式与接口协议不符 | 核对密钥完整以 `cr_` 开头；Anthropic 接口用 `x-api-key: cr_...` + `anthropic-version: 2023-06-01`；OpenAI 兼容 HTTP 接口用 `Authorization: Bearer cr_...`；原生自定义模型选 `Authorization` 仍 401 时，改试 `Header` 鉴权并手写 `Bearer cr_...` |
| `Model not found` / 模型不存在 | 把自定义的展示名称填进了模型 ID，或模型名拼写有误 | 核对「模型唯一标识」或 JSON 中的 `"model"` 字段，填写 QCode 实际支持的模型 ID（如 `claude-opus-5-5`、`gpt-6.2-sol`、`glm-5.3`） |
| HTTP 节点解析 JSON 失败或原生对话一直转圈 | 流式设置与场景相反：HTTP 节点收到 SSE 流无法当普通 JSON 解析，或企业原生路径被网络阻断 | HTTP 插件 / 工作流请求体必须显式写 `"stream": false`；企业原生自定义模型固定 `stream=true`，确认网络能稳定连通 `api.qcode.cc` 或改试 `asia.qcode.cc` |
| 成员在智能体模型列表里看不到刚接入的自定义模型 | 企业后台新接入的模型默认对所有工作空间关闭 | 管理员回到「自定义模型」列表，点该模型右侧「… → 修改可用空间」，手动开启目标工作空间开关 |

## 常见问题

### 密钥到期后怎么办？

分两种情况处理：

- **个人套餐**的密钥到期后不可续期，只能重新开通套餐并更换一把新密钥；
- **按量包**的密钥到期后再购买一个新的按量包，同一把密钥会自动恢复，无需修改扣子中的配置。

如果更换了新密钥，请同步更新扣子自定义插件 / 工作流 HTTP 节点里的请求头密钥（路径 A），或在「扣子编程 → 企业组织管理 → 模型接入 → 自定义模型」里编辑对应模型的鉴权密钥（路径 B）。

### 为什么普通个人账号不能直接替换扣子智能体的默认模型？

这是扣子平台自身的权限与产品设计限制：原生「自定义模型」入口目前只面向企业旗舰版组织的超级管理员与管理员开放，个人账号后台没有自定义模型 Base URL 的设置项。个人账号若想在扣子中使用 QCode，可以通过自定义插件或工作流 HTTP 请求节点把 QCode 作为工具或处理节点接入。

### 为什么企业旗舰版「自定义模型」里不能接入 `claude-opus-5-5`？

扣子原生「自定义模型」的 API 协议固定为 OpenAI Chat/completions，平台未提供 Anthropic Messages 协议选项；而 QCode 的 OpenAI 兼容端点仅服务 GPT 与国产模型，不接受 Claude 请求。因此企业用户如需在扣子中调用 `claude-opus-5-5`，同样需要通过自定义插件或工作流 HTTP 请求节点直连 `https://api.qcode.cc/api/v1/messages`。

### 工作流 HTTP 请求偶尔超时怎么办？

可从三方面排查：1）将请求域名从全球节点 `api.qcode.cc` 切换为亚洲节点 `asia.qcode.cc`（路由更近，同一把密钥通用）；2）在请求体中合理控制 `max_tokens`（如 `1024`–`2048`）并精简提示词，缩短单次生成耗时；3）适当调大工作流 HTTP 节点的超时配置，避免长回复被扣子节点提前截断。

### 扣子需要下载桌面端吗？有没有开源安装包？

不需要。无论是配置自定义插件、搭建工作流，还是在 `code.coze.cn` 管理企业自定义模型，在浏览器网页端即可全部完成。扣子确实提供 Windows 和 macOS 桌面端，但不是开源软件，没有 GitHub Releases、winget 或微软商店安装包，只能从 [www.coze.cn](https://www.coze.cn) 官网「下载桌面端」获取。

## 接入速览与可用模型

### QCode 节点与协议地址

三个接入域业务能力一致、同一把 `cr_` 密钥通用，按扣子所在网络环境任选其一即可：

| 节点 | Anthropic 接口（仅路径 A HTTP 请求） | OpenAI 兼容 Base URL（路径 A 需加 `/chat/completions`；路径 B 填至此） |
|---|---|---|
| 全球 | `https://api.qcode.cc/api/v1/messages` | `https://api.qcode.cc/openai/v1` |
| 亚洲（大陆首选） | `https://asia.qcode.cc/api/v1/messages` | `https://asia.qcode.cc/openai/v1` |
| 北美 / 欧洲 | `https://us.qcode.cc/api/v1/messages` | `https://us.qcode.cc/openai/v1` |

### 推荐模型与扣子路径对照

| 模型 | 模型 ID | 适用路径 | 协议端点 |
|---|---|---|---|
| Claude Opus 5.5 | `claude-opus-5-5` | 仅路径 A（自定义插件 / 工作流 HTTP） | Anthropic（`/api/v1/messages`） |
| GPT 6.2 Sol | `gpt-6.2-sol` | 路径 A 与路径 B（企业原生自定义模型）均可 | OpenAI 兼容（`/openai/v1`） |
| 国产主力模型 | `glm-5.3`、`kimi-k3`、`deepseek-v4-pro`、`qwen3.8-max` 等 | 路径 A 与路径 B 均可 | OpenAI 兼容（`/openai/v1`） |

> QCode 暂不提供 Gemini 系列模型，请在扣子中选用 Claude、GPT 或国产模型。完整国产模型 ID 见 [国产模型接入](/docs/usage/cn-models)，实时在售型号以 [qcode.cc/models](https://qcode.cc/models) 为准。

## 相关文档

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) — 协议 × 模型家族真源表
- [国产模型接入](/docs/usage/cn-models) — OpenAI 兼容端点可用国产模型清单
- [计费说明](/docs/reference/billing) — 套餐与按量包计费规则
- [故障排查](/docs/reference/troubleshooting) — 通用状态码与网络连通排查
- [扣子官方自定义模型接入文档](https://docs.coze.cn/guides/deploy_custom_model) — 企业旗舰版原生接入官方说明