Qwen Code 接入 OpenAI 兼容 API：从安装到首次调用

Qwen Code 是运行在终端中的开源 AI 编程 Agent。它可以读取代码、修改文件、运行命令，也支持 OpenAI、Anthropic、Gemini 等多种协议。即使你使用的不是 OpenAI 官方服务，只要网关提供 OpenAI 兼容端点，也可以通过 openai 协议接入。

本文依据 Qwen Code 官方仓库和认证文档在 2026 年 7 月核对，带你完成：

1. 安装并验证 Qwen Code；
2. 配置 OpenAI 兼容 Base URL、API Key 和模型 ID；
3. 启动 Qwen Code 并完成首次调用；
4. 使用 /model 切换模型；
5. 排查 401、404、模型不存在和工具调用问题。

需要特别注意：旧教程中的独立 qwen auth 命令已经移除。交互式认证应在 Qwen Code 内使用 /auth，自定义 Provider 则可通过 ~/.qwen/settings.json、.qwen/.env 或环境变量配置。

安装前需要什么

官方 NPM 安装方式要求 Node.js 22 或更高版本。先检查：

node --version
npm --version

如果 Node.js 版本低于 22，先升级运行环境。然后选择一种安装方式。

使用 NPM 安装

npm install -g @qwen-code/qwen-code@latest

使用 Homebrew 安装

macOS 和 Linux 也可以运行：

brew install qwen-code

安装后验证：

qwen --version

如果提示 command not found，先重新打开终端，或者确认 NPM 全局二进制目录已经加入 PATH。不要为了省事直接对陌生目录执行宽泛的 sudo chmod。

Qwen Code 如何理解 OpenAI 兼容 Provider

Qwen Code 的 modelProviders 按协议分组。官方文档中，OpenAI 兼容协议对应：

modelProviders key: openai
API Key: OPENAI_API_KEY
Base URL: OPENAI_BASE_URL
Model: OPENAI_MODEL

这里的 openai 是协议类型，并不限定请求必须发送到 OpenAI 官方。OpenRouter、自建网关、聚合 API，以及其他实现 OpenAI 常用接口的服务，都可以放在这个协议下。

四个核心对象分别负责：

对象	作用
协议 openai	告诉 Qwen Code 使用 OpenAI 兼容请求格式
Base URL	指定请求发往哪个 API 网关
API Key	证明调用权限
Model ID	指定网关实际调用的模型

模型显示名不能替代 Model ID。请从服务商当前模型列表复制精确 ID，不要猜测版本后缀、大小写或分隔符。

方法一：用环境变量快速完成首次调用

如果只想先验证连接，可在当前终端中设置：

export OPENAI_API_KEY="YOUR_API_KEY"
export OPENAI_BASE_URL="https://api.nbility.ai/v1"
export OPENAI_MODEL="YOUR_MODEL_ID"
qwen

也可以使用 QWEN_MODEL 作为模型变量的别名，但本文统一使用 OPENAI_MODEL，避免同一示例出现两套名字。

启动后，Qwen Code 会根据当前配置进入交互界面。先执行只读任务：

读取当前目录的 package.json，只总结 scripts，不要修改文件。

这能验证：

• Key 是否有效；
• Base URL 是否正确；
• Model ID 是否存在；
• 基础响应和流式输出是否正常。

不要一开始就让 Agent 修改大型项目或执行高风险命令。

方法二：使用 settings.json 保存 Provider

长期使用时，推荐在用户级文件中定义模型：

~/.qwen/settings.json

一个适用于 OpenAI 兼容网关的最小配置如下：

{
  "modelProviders": {
    "openai": [
      {
        "id": "YOUR_MODEL_ID",
        "name": "My Coding Model",
        "baseUrl": "https://api.nbility.ai/v1",
        "envKey": "NBILITY_API_KEY"
      }
    ]
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "YOUR_MODEL_ID"
  }
}

再通过环境变量提供密钥：

export NBILITY_API_KEY="YOUR_API_KEY"
qwen

字段含义：

字段	说明
modelProviders.openai	OpenAI 兼容协议下的模型列表
id	实际发送给 API 的模型 ID
name	/model 选择器里的可读名称
baseUrl	自定义 API 根地址
envKey	存放该模型密钥的环境变量名
selectedType	启动时选用的协议
model.name	默认激活的模型，必须匹配某个 id

官方文档支持把密钥放进 settings.json 的 env 字段，但那会以明文保存。更安全的做法是使用环境变量或 .qwen/.env。

使用 .qwen/.env 管理项目密钥

Qwen Code 会自动查找第一个可用的 .env 文件，项目内优先顺序是：

1. .qwen/.env；
2. .env；
3. 找不到时再检查 ~/.qwen/.env；
4. 最后检查 ~/.env。

多个文件不会合并。系统环境变量的优先级高于 .env，而 settings.json 的 env 字段优先级最低。

可以创建：

.qwen/.env

内容为：

NBILITY_API_KEY=YOUR_API_KEY

同时将它加入 .gitignore：

.qwen/.env

不要把真实 Key 写进文章、Issue、终端截图或 Git 提交。如果密钥曾经进入 Git 历史，仅删除当前文件并不够，应立即撤销并重新生成密钥。

Base URL 应该填到哪里

OpenAI 兼容 Base URL 通常停在版本根路径，例如：

https://api.example.com/v1

不要在 Base URL 后再加：

/chat/completions

客户端通常会自行拼接端点。如果你把完整端点当成 Base URL，可能得到重复路径和 404。

但不同网关的路径设计并不完全相同，最终以服务商文档为准。想系统理解路径结构，可以先阅读什么是 OpenAI 兼容 API。

用 /auth、/model 和 /doctor 检查状态

进入 Qwen Code 后，三个命令最常用：

/auth
/model
/doctor

• /auth：切换或重新配置认证方式；
• /model：查看 modelProviders 中配置的模型并切换；
• /doctor：检查当前认证和运行状态。

独立的 qwen auth status 等旧命令已经被移除。遇到旧教程时，不要继续围绕过时命令排错。

也可以在启动时指定模型：

qwen --model "YOUR_MODEL_ID"

如果一个 settings.json 中配置了多个模型，/model 会按协议分组展示，选择结果可以跨会话保留。

添加多个 OpenAI 兼容模型

你可以在 openai 数组中定义多个模型：

{
  "modelProviders": {
    "openai": [
      {
        "id": "FAST_MODEL_ID",
        "name": "Fast Model",
        "baseUrl": "https://api.nbility.ai/v1",
        "envKey": "NBILITY_API_KEY"
      },
      {
        "id": "CODING_MODEL_ID",
        "name": "Coding Model",
        "baseUrl": "https://api.nbility.ai/v1",
        "envKey": "NBILITY_API_KEY"
      },
      {
        "id": "REASONING_MODEL_ID",
        "name": "Reasoning Model",
        "baseUrl": "https://api.nbility.ai/v1",
        "envKey": "NBILITY_API_KEY"
      }
    ]
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "CODING_MODEL_ID"
  }
}

建议按任务切换，而不是永远使用最贵的模型：

• 小修改、解释和格式处理：快速模型；
• 常规功能和测试：主力编程模型；
• 跨模块重构和复杂排错：强推理模型。

模型是否适合 Agent，不能只看聊天效果。必须验证工具调用、流式参数、上下文稳定性和错误返回。

首次调用应该怎么验证

完成基础只读请求后，再逐步增加权限：

1. 读取一个小文件；
2. 生成一个最小修改计划；
3. 在临时分支创建一个测试文件；
4. 运行安全的测试命令；
5. 检查 Git diff；
6. 多轮继续任务，观察上下文是否稳定。

建议提示词：

先读取 package.json 和测试目录，给出一个不修改文件的最小测试计划。

确认计划合理后：

只新增一个最小测试，运行对应测试，并总结实际修改。

普通文本回复正常，不代表 Agent 链路完整。第三方网关还需要正确支持流式输出、工具调用和多轮上下文。

常见错误排查

401 Unauthorized

检查：

• API Key 是否完整；
• 环境变量名是否与 envKey 一致；
• 当前 Shell 是否真的加载了变量；
• Key 与 Base URL 是否属于同一服务；
• 账号是否有目标模型权限。

可以确认变量是否存在，但不要直接输出完整值：

if [ -n "$NBILITY_API_KEY" ]; then echo "key loaded"; else echo "key missing"; fi

404 Not Found

常见原因：

• Base URL 缺少 /v1；
• 错把 /chat/completions 填进 Base URL；
• 使用了网站域名而非 API 域名；
• 网关只实现了另一套路径。

Model not found

model.name 必须匹配 modelProviders 中某个 id，而该 id 又必须是网关识别的真实模型名。还要检查 API Key 是否拥有模型权限。

设置了变量但没有生效

Qwen Code 的优先级是：CLI 参数、系统环境变量、找到的第一个 .env、最后是 settings.json 的 env。如果旧环境变量仍存在，它会覆盖你刚修改的文件。

可以运行：

unset OPENAI_API_KEY OPENAI_BASE_URL OPENAI_MODEL QWEN_MODEL

然后只保留计划使用的一套配置，重新启动 Qwen Code。

能聊天，但不能改文件或运行工具

重点检查：

• 模型是否支持 Tool Calling；
• 网关是否保留工具调用字段；
• 流式响应中的工具参数是否完整；
• 模型是否只适合普通聊天；
• Qwen Code 与网关是否为最新兼容版本。

429、超时或 5xx

429 通常与额度、限流或并发有关；5xx 更可能来自网关或上游。使用有上限的指数退避，不要无限立即重试。详细策略可以参考 AI API 错误码排查指南。

安全与权限建议

Qwen Code 能读取文件、修改代码和运行 Shell，因此首次接入第三方 API 时还要控制执行范围：

• 在 Git 仓库和临时分支中测试；
• 不向模型暴露 .env、SSH Key 和生产凭据；
• 初期保留命令确认，不要开启宽泛自动批准；
• 执行前要求模型先解释计划；
• 修改后检查 diff 并运行测试；
• 给 API Key 设置合理额度和最小权限。

如果项目包含私有代码，还应确认所选网关和上游模型的数据处理政策。

通过 Nbility 接入多个模型

如果你想用一个 OpenAI 兼容入口测试多个模型，可以在 Nbility 模型广场复制当前模型 ID，然后使用：

Base URL: https://api.nbility.ai/v1
API Key: YOUR_API_KEY
Model ID: 从模型广场复制

将 Key 放入 .qwen/.env 或系统环境变量，不要写进仓库。遇到模型或兼容性问题时，可以通过 Nbility 工单提交脱敏后的错误信息。

FAQ

Qwen Code 只能使用 Qwen 模型吗？

不是。官方文档支持 OpenAI 兼容、Anthropic、Gemini 和 Vertex AI 等协议，也允许在 modelProviders 中配置多个模型。

OPENAI_MODEL 和 QWEN_MODEL 有什么区别？

在 OpenAI 兼容配置中，QWEN_MODEL 是 OPENAI_MODEL 的别名。建议在同一环境中只使用一个，避免覆盖关系难以判断。

为什么 qwen auth 不能用了？

独立认证命令已被移除。交互式配置使用 Qwen Code 内的 /auth，自定义 Provider 使用 settings.json、.env 或环境变量。

API Key 应该放进 settings.json 吗？

可以，但会明文保存。更建议使用系统环境变量或已加入 .gitignore 的 .qwen/.env。

OpenAI 兼容 API 能保证工具调用正常吗？

不能。兼容普通聊天不代表完整兼容 Agent。上线前必须验证流式输出、工具调用、多轮上下文和错误格式。

总结

Qwen Code 接入 OpenAI 兼容 API 的可靠流程是：

1. 使用 Node.js 22+ 安装 Qwen Code；
2. 用环境变量完成最小连接测试；
3. 在 ~/.qwen/settings.json 中定义 Provider 和模型；
4. 把真实 Key 放在系统环境或 .qwen/.env；
5. 用 /doctor、/model 和渐进式任务验证完整 Agent 链路；
6. 遇到问题时按认证、路径、模型、流式和工具调用逐层排查。

如果你还在比较不同终端编程 Agent，可以继续阅读 OpenCode 接入第三方 API和 Roo Code 自定义 API 配置。

参考资料

• Qwen Code 官方仓库
• Qwen Code Quickstart
• Qwen Code Authentication
• Qwen Code Settings