RealRelay.ai
编码智能体

Qwen Code 接入指南

把 RealRelay.ai 作为 OpenAI 兼容的提供商接入 Qwen Code：安装、在 ~/.qwen/settings.json 中添加模型条目、检查连接并切换模型。

创建 API 密钥浏览目录
协议
OpenAI Chat Completions · OpenAI Responses
基础地址
https://www.realrelay.ai/v1
官方文档
qwenlm.github.io
已对照工具官方文档核对
2026-10

概览

Qwen Code 是 Qwen 团队推出的终端编码智能体。它会读取你的项目、编辑文件并运行命令。它能对接任何 OpenAI 兼容的服务，因此接入的是 RealRelay.ai 的 Chat Completions 端点 /v1/chat/completions。

  • 一个从控制台的 API 密钥页面获取的 API 密钥。

  • 末尾带 /v1 的基础地址。Qwen Code 会在后面拼上 /chat/completions。

  • 一个与 GET /v1/models 列出的完全一致的模型 ID，例如 z-ai/glm-5.2。该模型需要支持工具调用。

Qwen Code 的 /auth 菜单提供 QwenCloud、Alibaba ModelStudio 和一组第三方服务。RealRelay.ai 不在其中；请改用下面的设置文件。

安装

npm 包需要 Node.js 22 或更高版本。Qwen Code 的 README 还列出了 Homebrew 和它自己的独立安装程序。

npm (Node.js 22+)
npm install -g @qwen-code/qwen-code@latestqwen --version
Homebrew (macOS · Linux)
brew install qwen-code
macOS · Linux
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash
Windows PowerShell
irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex

如果 qwen --version 输出了版本号，说明安装成功。使用独立安装程序后，请先新开一个终端。

配置

  1. 1

    把密钥存进环境变量

    设置文件从 REALRELAY_API_KEY 读取密钥，这样文件本身不含任何机密。你可以在 shell 中设置它，也可以写进 ~/.qwen/.env，Qwen Code 启动时会加载这个文件。

    ~/.zshrc · ~/.bashrc
    export REALRELAY_API_KEY="sk-***"
    Windows PowerShell
    [Environment]::SetEnvironmentVariable("REALRELAY_API_KEY", "sk-***", "User")

    关闭并重新打开终端，让它读到新变量。

    ~/.qwen/.env
    REALRELAY_API_KEY=sk-***
  2. 2

    把模型添加到 settings.json

    如果文件不存在，就新建一个。Windows 上的路径是 %USERPROFILE%.qwen\settings.json。Qwen Code 建议把提供商写在这个用户级文件中，而不是项目的 .qwen/settings.json。

    ~/.qwen/settings.json
    1{2  "modelProviders": {3    "openai": [4      {5        "id": "z-ai/glm-5.2",6        "name": "z-ai/glm-5.2 (RealRelay.ai)",7        "baseUrl": "https://www.realrelay.ai/v1",8        "envKey": "REALRELAY_API_KEY",9        "generationConfig": {10          "contextWindowSize": 20000011        }12      }13    ]14  },15  "security": {16    "auth": {17      "selectedType": "openai"18    }19  },20  "model": {21    "name": "z-ai/glm-5.2"22  }23}

  • modelProviders 下的 openai 表示协议，而不是厂商。该列表中的每个条目都以 OpenAI 风格的请求发送。不要改名：Qwen Code 会跳过它不认识的提供商名称。

  • id 是发给 RealRelay.ai 的模型 ID。envKey 指定保存密钥的变量名。

  • contextWindowSize 告诉 Qwen Code 该模型的上下文窗口有多大。不设置的话，Qwen Code 会根据模型名称猜测，而 RealRelay.ai 的模型列表不包含这个数值。

  • 有了 selectedType 和 model.name，Qwen Code 启动时就会直接使用这个模型，不会要求你运行 /auth。model.name 必须与上面某个 id 一致。

如果只想快速测试、不写设置文件，三个标准的 OpenAI 变量就够了。但它们也会作用于其他读取 OPENAI_API_KEY 的工具，所以日常使用请优先用设置文件。

Terminal
1export OPENAI_API_KEY="sk-***"2export OPENAI_BASE_URL="https://www.realrelay.ai/v1"3export OPENAI_MODEL="z-ai/glm-5.2"4qwen

验证

  1. 1

    直接调用端点

    用你的密钥运行这条命令。如果返回的 JSON 包含 choices 数组，说明地址、密钥和模型都没问题。

    Terminal
    1curl -sS "https://www.realrelay.ai/v1/chat/completions" \2  -H "Authorization: Bearer sk-***" \3  -H "content-type: application/json" \4  -d '{"model": "z-ai/glm-5.2", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK"}]}'
  2. 2

    从终端发送一条提示词

    这会在不进入交互界面的情况下运行 Qwen Code，并打印回复。

    Terminal
    qwen -p "Reply with OK"
  3. 3

    检查会话

    在项目中启动 qwen 并运行 /doctor。它会显示认证类型和环境检查结果。发一条简短消息，该请求会出现在控制台的用量日志中。

    Qwen Code
    cd /path/to/your/projectqwen/doctor

模型

每个要使用的模型都是 openai 列表中的一个条目。每个模型加一个条目，然后在会话中用 /model 切换。你的选择会保留到下一次会话。

~/.qwen/settings.json → modelProviders.openai
1{2  "id": "z-ai/glm-5.2",3  "name": "z-ai/glm-5.2 (RealRelay.ai)",4  "baseUrl": "https://www.realrelay.ai/v1",5  "envKey": "REALRELAY_API_KEY",6  "generationConfig": { "contextWindowSize": 200000 }7},8{9  "id": "<another-model-id>",10  "name": "<another-model-id> (RealRelay.ai)",11  "baseUrl": "https://www.realrelay.ai/v1",12  "envKey": "REALRELAY_API_KEY",13  "generationConfig": { "contextWindowSize": 128000 }14}

如果只想在某次运行中使用某个模型，就在命令行中传入：

Terminal
qwen --model "z-ai/glm-5.2"

这些示例中的窗口大小是安全的起始值。请把 contextWindowSize 设为模型目录页上的真实上限。要限制输出长度，请设置 QWEN_CODE_MAX_OUTPUT_TOKENS 环境变量。

少数 OpenAI 模型在 Responses 端点 /v1/responses 上提供。在这些模型的条目中加上 wireApi，Qwen Code 就会把请求发往该端点：

~/.qwen/settings.json → modelProviders.openai
1{2  "id": "openai/gpt-5.3-codex",3  "name": "openai/gpt-5.3-codex (RealRelay.ai, Responses)",4  "wireApi": "responses",5  "baseUrl": "https://www.realrelay.ai/v1",6  "envKey": "REALRELAY_API_KEY",7  "generationConfig": { "contextWindowSize": 400000 }8}

哪些模型适合智能体、哪些模型在 Responses 端点上提供，请见选择模型。

故障排查

  • Qwen Code 启动时打开了 /auth 菜单。它没有找到可用的配置。检查 selectedType 是否为 openai，以及 model.name 是否与列表中的某个 id 一致。

  • /model 中没有该模型。modelProviders 下的提供商键不是 openai，或者 JSON 有语法错误。

  • 401。密钥没有送达 RealRelay.ai。shell 中 export 的密钥优先于 .env 文件，而 .env 文件又优先于 settings.json 的 env 块；优先级更高处的旧值会盖住新值。

  • 404。基础地址缺少 /v1，或者已经以 /chat/completions 结尾。请使用以 /v1 结尾的地址。

  • 找不到模型。id 必须与 GET /v1/models 返回的 ID 完全一致，包括斜杠前面的部分。

  • 长会话中出现上下文报错。contextWindowSize 没有设置，或大于模型的真实窗口。按目录页设置它。

  • 带 wireApi: "responses" 的模型报错。只有“选择模型”中列出的模型在 /v1/responses 上提供。其他模型请去掉 wireApi。