Codex 如何使用通义千问 Qwen？国产模型配置教程

大家好，我是 Codex 中文网的站长宇哥。

这篇文章专门讲 Codex 如何使用通义千问 Qwen。和普通“换个模型名”不同，Qwen 接入最容易卡在三个地方：阿里云百炼是否开通、Base URL 是否填对、模型名是否和当前地域/服务一致。

本文按真实排查顺序来写：先确认百炼控制台和 API Key，再用 OpenAI 兼容接口做最小测试，最后再回到 Codex 配置。这样出问题时不会混在一起猜。

先说结论

Codex 接入 Qwen，本质上是把 Codex 的模型 provider 指向阿里云百炼的 OpenAI 兼容接口。

你需要准备三项信息：

API Key：阿里云百炼 API Key
Base URL：百炼 OpenAI 兼容接口地址
Model：例如 qwen-plus、qwen-max、qwen-coder-plus 等

阿里云百炼官方文档说明，Qwen 模型支持 OpenAI 兼容接口，迁移时主要调整 API Key、BASE_URL 和 model name。官方文档也提醒，具体模型名称和计费以百炼控制台为准。

官方资料：

• 阿里云百炼 OpenAI Chat 接口兼容
• 阿里云 Model Studio OpenAI-compatible Chat
• 阿里云百炼文本生成模型 API 参考

适合谁看

这篇文章适合下面几类人：

• 想在 Codex 里使用通义千问 Qwen 的开发者；
• 已经有阿里云百炼账号，但不知道 Base URL 怎么填的人；
• 想用国产模型替代默认模型做 AI Coding 的用户；
• 遇到 401、404 model not found、连接失败、模型响应异常的人；
• 想把 Qwen、DeepSeek、GLM、Kimi、OpenRouter 等 provider 做成可切换配置的人。

第一步：确认你用的是哪种 Qwen 服务

先分清楚两种常见情况。

第一种是 阿里云百炼 / DashScope API。这是本文主要讲的方式，适合把 Qwen 当作 OpenAI 兼容模型接入 Codex。

第二种是 Qwen Code 或 Coding Plan。这类工具可能有专门的 endpoint 和认证方式，例如 Qwen Code 文档里提到 Coding Plan 会使用独立 endpoint。不要把它和普通 DashScope OpenAI 兼容接口混用。

如果你只是想让 Codex 调用 Qwen 大模型，优先按“百炼 OpenAI 兼容接口”这条线排查。

第二步：在百炼控制台准备 API Key

进入阿里云百炼控制台后，建议按这个顺序检查：

1. 已登录正确的阿里云账号。

2. 已开通百炼 / Model Studio 服务。

3. 已创建 API Key。

4. 当前账号或业务空间有可调用的模型。

5. 确认余额、免费额度或计费方式没有问题。

API Key 不要写进 Git 仓库。建议放在 shell 环境变量里：

export DASHSCOPE_API_KEY="你的百炼APIKey"

如果你的 Codex provider 配置读取的是 OPENAI_API_KEY，也可以临时这样映射：

export OPENAI_API_KEY="$DASHSCOPE_API_KEY"

检查环境变量是否存在时，不要直接打印完整 key，可以只看长度：

echo ${#DASHSCOPE_API_KEY}

如果输出是 0，说明当前终端没有读到 key。

第三步：确认 Base URL

Qwen 通过百炼 OpenAI 兼容接口调用时，Base URL 通常会是下面这种形式：

https://dashscope.aliyuncs.com/compatible-mode/v1

阿里云也在官方文档里提供了业务空间专属域名的形式，例如北京地域常见格式类似：

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1

这里的 {WorkspaceId} 要替换成你自己百炼业务空间的 ID。不同地域可能是不同域名，比如新加坡、日本、美国、香港等。不要从网上随便复制一个 Base URL 就直接用，最终以你当前百炼控制台和官方文档展示为准。

常见错误是把控制台页面地址当成 API 地址，比如：

https://bailian.console.aliyun.com

这不是模型 API Base URL。Codex 调模型要用 OpenAI 兼容接口地址，也就是以 /compatible-mode/v1 结尾的地址。

第四步：确认模型名

模型名不要自己猜。建议在百炼控制台复制模型名称。

常见模型名可能包括：

qwen-plus
qwen-max
qwen-turbo
qwen-coder-plus

这些名称会随着百炼模型版本和地域支持情况变化。你在 ChatGPT、网页控制台或其他工具里看到的名字，不一定就是当前 API 可调用的 model 字段。

如果你主要用 Codex 写代码，可以优先关注 Qwen Coder 系列；如果做普通问答、文章整理、需求分析，qwen-plus 这类通用模型通常更合适。具体可用性、价格和上下文长度请以百炼控制台为准。

第五步：先用 curl 做最小测试

不要一上来就改 Codex。先用 curl 验证 Qwen API 本身能不能通。

下面示例使用 OpenAI 兼容 Chat Completions：

curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-plus",
    "messages": [
      {
        "role": "user",
        "content": "只回复一句：Qwen API 测试成功。"
      }
    ]
  }'

如果你使用业务空间专属域名，把 URL 换成你自己的：

curl https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-plus",
    "messages": [
      {
        "role": "user",
        "content": "只回复一句：Qwen API 测试成功。"
      }
    ]
  }'

这一步能成功，再去配置 Codex。否则 Codex 里一定也会失败。

第六步：配置 Codex provider

不同 Codex 版本的配置项可能会调整，核心思路是一样的：新增一个 provider，指定 Qwen 的 Base URL、API Key 环境变量和默认模型。

用户级配置文件一般在：

~/.codex/config.toml

可以先备份：

cp ~/.codex/config.toml ~/.codex/config.toml.bak

下面是一个思路示例：

model = "qwen-plus"
model_provider = "dashscope"

[model_providers.dashscope]
name = "DashScope Qwen"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"

如果你使用业务空间专属域名：

model = "qwen-plus"
model_provider = "dashscope"

[model_providers.dashscope]
name = "DashScope Qwen"
base_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"

如果你的 Codex 当前版本要求使用 OPENAI_API_KEY，可以把 env_key 改成 OPENAI_API_KEY，并在终端里设置：

export OPENAI_API_KEY="$DASHSCOPE_API_KEY"

配置完成后，先用一个最小任务测试：

codex "只回复一句：Codex 已经连上 Qwen。不要读取文件，不要修改文件。"

如果成功，再进入一个测试项目：

codex "请总结当前项目目录结构，不要修改任何文件。"

这样可以区分“模型调用成功”和“项目上下文读取成功”。

第七步：常见报错排查

401 Unauthorized

优先检查 API Key。

常见原因：

• DASHSCOPE_API_KEY 没有设置；
• key 复制时多了空格或换行；
• 当前 shell 没有重新加载 .zshrc / .bashrc；
• Codex 配置里的 env_key 和你实际设置的环境变量不一致；
• API Key 所属账号没有开通百炼服务。

可以检查：

echo ${#DASHSCOPE_API_KEY}

如果你配置里写的是 env_key = "OPENAI_API_KEY"，就检查：

echo ${#OPENAI_API_KEY}

404 model not found

这通常是模型名问题，不一定是接口坏了。

检查：

• 模型名是否从百炼控制台复制；
• 当前地域是否支持该模型；
• 账号是否已经开通该模型；
• 是否把展示名当成 API model name；
• 是否把 qwen-coder-plus、qwen-plus、qwen-max 写混。

建议先把模型改成控制台明确可用的通用模型，例如 qwen-plus，跑通后再切换到更适合代码任务的模型。

连接失败或超时

常见原因：

• Base URL 写成控制台地址；
• 少写 /compatible-mode/v1；
• 公司网络或本机代理拦截；
• 使用了错误地域的 endpoint；
• 国际站和中国站 endpoint 混用。

先测试：

curl -I https://dashscope.aliyuncs.com/compatible-mode/v1

如果这里都连不上，先解决网络和域名问题。

429 Too Many Requests

429 通常和频率、额度、并发或计费限制有关。

处理顺序：

1. 降低调用频率。

2. 等几分钟再试。

3. 查看百炼控制台额度。

4. 确认是否有欠费或限流。

5. 自动化任务里不要一次并发太多 Codex 请求。

返回格式异常

如果 curl 能通，但 Codex 里报解析错误，通常是 provider 兼容层或参数差异。

可以先把配置简化：

• 不开 streaming；
• 不加复杂工具调用；
• 不启用多模态；
• 只用普通 chat completions；
• 先用 qwen-plus 这类通用文本模型。

等基础对话跑通后，再逐步增加工具调用、长上下文或代码任务。

推荐配置习惯

我建议把配置拆成三层：

个人密钥放环境变量

export DASHSCOPE_API_KEY="你的百炼APIKey"

不要把 key 写进仓库。

provider 放用户级配置

~/.codex/config.toml

这适合长期使用的 provider，例如 OpenAI、DashScope、OpenRouter 等。

项目规则放项目级配置

.codex/config.toml

项目级配置适合放仓库规则、测试命令、代码风格说明，不适合放个人 API Key。

一套完整排查清单

你可以按下面顺序排查：

1. 百炼服务是否开通
2. API Key 是否创建
3. 当前 shell 是否能读到 DASHSCOPE_API_KEY
4. Base URL 是否是 OpenAI 兼容接口
5. Base URL 是否包含 /compatible-mode/v1
6. 模型名是否从控制台复制
7. curl chat/completions 是否成功
8. Codex config.toml 是否指向正确 provider
9. env_key 是否和环境变量一致
10. 最小 Codex 请求是否成功
11. 进入项目后只读分析是否成功

按照这个顺序查，基本可以定位大多数 Qwen 接入问题。

FAQ

Qwen 的 Base URL 必须用业务空间专属域名吗？

不一定。旧的 dashscope.aliyuncs.com/compatible-mode/v1 在很多场景仍然能用，但阿里云官方文档已经提供了业务空间专属域名的形式。新项目建议优先看百炼控制台和官方文档给你的地址。

Codex 里应该用 DASHSCOPE_API_KEY 还是 OPENAI_API_KEY？

看你的 provider 配置。更清晰的方式是 env_key = "DASHSCOPE_API_KEY"；如果当前 Codex 版本或兼容工具只认 OPENAI_API_KEY，就把百炼 key 映射到 OPENAI_API_KEY。

qwen-plus 和 qwen-coder-plus 怎么选？

普通问答、文档整理、需求分析可以先用 qwen-plus。代码生成、项目分析、编程任务可以优先测试 Qwen Coder 系列。最终以你账号可用模型和实际效果为准。

为什么 curl 能通，Codex 还是失败？

通常是 Codex provider 配置没有读取到正确 key，或者 model provider 没有切过去。先让 Codex 做“只回复一句”的最小请求，不要一上来就进入复杂项目。

可以把多个国产模型都配进 Codex 吗？

可以。建议每个 provider 单独命名，比如 dashscope、deepseek、openrouter。排错时一次只切一个 provider，不要同时改 Base URL、模型名和 key。

总结

Codex 接入 Qwen，不要只盯着“模型名怎么写”。真正稳定的流程是：

百炼开通
↓
API Key
↓
Base URL
↓
模型名
↓
curl 最小测试
↓
Codex provider 配置
↓
Codex 最小任务
↓
真实项目任务

只要这条链路跑通，后面你就可以把 Qwen 作为 Codex 的一个常用 provider，用于代码阅读、配置分析、文章生成、脚本编写和项目改造。