概述

本文档介绍如何在 Qwen Code 中配置自定义模型，特别是连接使用自签名证书的私有 API 端点（如 vLLM 部署的模型服务）。

环境信息

• Qwen Code 版本: 基于 Node.js 开发
• OpenAI SDK 版本: 5.11.0
• HTTP 客户端: undici (^6.22.0)
• 操作系统: Linux

配置步骤

1. 准备证书文件

确保您的自签名证书文件存在且格式正确：

# 验证证书文件
ls -la /home/user/qwen/vllm.crt

证书应为标准的 PEM 格式，包含 -----BEGIN CERTIFICATE----- 和 -----END CERTIFICATE----- 标记。
证书用于vLLM的https配置。

2.在需要访问目标主机的客户端机器上导入自签名证书，以Ubuntu为例

sudo cp /home/user/qwen/vllm.crt /usr/local/share/ca-certificates/vllm.crt
sudo update-ca-certificates

3. 设置环境变量

在启动 Qwen Code 之前，设置 NODE_EXTRA_CA_CERTS 环境变量：

export NODE_EXTRA_CA_CERTS=/home/user/qwen/vllm.crt

说明:

• 此环境变量告诉 Node.js 使用指定的 CA 证书验证 HTTPS 连接
• OpenAI SDK 和 undici 客户端会自动识别此环境变量
• 无需修改代码即可支持自签名证书

4. 配置模型设置

编辑 ~/.qwen/settings.json 文件：

{
  "ide": {
    "hasSeenNudge": true
  },
  "modelProviders": {
    "openai": [
      {
        "id": "Qwen/Qwen3.5-27B-FP8",
        "name": "Qwen3.5 27B FP8",
        "envKey": "EMPTY_API_KEY",
        "baseUrl": "https://your-ip-address/v1",
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 3,
          "contextWindowSize": 32768,
          "samplingParams": {
            "temperature": 0.7,
            "top_p": 0.9,
            "max_tokens": 4096
          }
        }
      }
    ]
  },
  "env": {
    "EMPTY_API_KEY": "dummy-key"
  },
  "$version": 3,
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "qwen3.5-27b-fp8",
    "generationConfig": {
      "timeout": 60000
    }
  }
}

关键配置项:

配置项	说明	推荐值
timeout	请求超时时间（毫秒）	60000 (60秒)
maxRetries	最大重试次数	3
contextWindowSize	上下文窗口大小	32768
baseUrl	API 端点地址	https://your-ip-address/v1

5. 验证 API 连接

在启动 Qwen Code 之前，先验证 API 端点是否可访问：

# 验证https的OpenAI兼容API可以访问
curl -k https://your-ip-address/v1/models

# 设置环境变量并测试连接
export NODE_EXTRA_CA_CERTS=/home/user/qwen/vllm.crt
curl -L https://your-ip-address/v1/models

预期输出：

{
  "object": "list",
  "data": [{
    "id": "Qwen/Qwen3.5-27B-FP8",
    "object": "model",
    "created": 1772705949,
    "owned_by": "vllm",
    "root": "Qwen/Qwen3.5-27B-FP8",
    "max_model_len": 32768
  }]
}

6. 启动 Qwen Code

使用以下命令启动 Qwen Code：

export NODE_EXTRA_CA_CERTS=/home/user/qwen/vllm.crt && qwen

或者将环境变量设置添加到 shell 配置文件（如 ~/.bashrc 或 ~/.zshrc）：

echo 'export NODE_EXTRA_CA_CERTS=/home/user/qwen/vllm.crt' >> ~/.bashrc
source ~/.bashrc
qwen

故障排除

问题 1: SSL/TLS 证书错误

症状:

UNABLE_TO_GET_ISSUER_CERT_LOCALLY
SELF_SIGNED_CERT_IN_CHAIN
DEPTH_ZERO_SELF_SIGNED_CERT

解决方案:
确保正确设置了 NODE_EXTRA_CA_CERTS 环境变量：

export NODE_EXTRA_CA_CERTS=/home/user/qwen/vllm.crt

问题 2: 流式请求超时

症状:

[API Error: Streaming request timeout after 12s. 
Try reducing input length or increasing timeout in config.]

解决方案:
增加 settings.json 中的超时配置：

{
  "generationConfig": {
    "timeout": 60000,
    "maxRetries": 3
  }
}

问题 3: 连接被拒绝

症状:

ECONNREFUSED
ETIMEDOUT

解决方案:

1. 检查 API 端点是否可访问

2. 检查网络连接

3. 如果使用代理，配置代理设置：

   export HTTP_PROXY=http://proxy.example.com:8080
   export HTTPS_PROXY=http://proxy.example.com:8080
   

技术实现细节

OpenAI SDK 配置

Qwen Code 使用 OpenAI SDK 5.11.0，通过以下方式配置：

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'your-api-key',
  baseURL: 'https://your-ip-address/v1',
  timeout: 60000,
  maxRetries: 3,
  fetchOptions: {
    dispatcher: new Agent({
      headersTimeout: 0,
      bodyTimeout: 0,
    })
  }
});

自签名证书支持

OpenAI SDK 底层使用 undici HTTP 客户端，支持以下方式配置自定义 CA 证书：

1. 环境变量方式（推荐）：NODE_EXTRA_CA_CERTS
2. 代码配置方式：通过 Agent 的 connect.ca 选项

环境变量方式无需修改代码，是最简单可靠的解决方案。

参考资源

• Qwen Code
• OpenAI SDK 文档
• undici 文档
• Node.js TLS 文档

总结

通过正确配置 NODE_EXTRA_CA_CERTS 环境变量和 settings.json 文件，Qwen Code 可以无缝连接使用自签名证书的私有 API 端点。主要步骤包括：

1. 准备有效的自签名证书文件
2. 设置 NODE_EXTRA_CA_CERTS 环境变量
3. 配置模型参数（超时、重试等）
4. 验证连接并启动 Qwen Code

这种配置方式既保证了安全性（验证服务器证书），又提供了灵活性（支持自签名证书）。