모델 제공자

Qwen Code는 settings.json의 modelProviders 설정을 통해 여러 모델 제공자를 구성할 수 있습니다. 이를 통해 /model 명령을 사용하여 다양한 AI 모델과 제공자 간에 전환할 수 있습니다.

개요

modelProviders를 사용하여 /model 선택기가 전환할 수 있는 제공자 id별 모델을 선언합니다. 각 키는 제공자 id이며 값은 모델 정의 배열(ModelConfig[])입니다. 내장 제공자의 경우 키는 유효한 auth 유형(openai, anthropic, gemini, vertex-ai)이어야 합니다. 사용자 정의 제공자 id(예: idealab)는 최상위 providerProtocol 설정을 통해 프로토콜에 매핑하는 한 허용됩니다. 각 모델 항목에는 id가 필요합니다. envKey는 선택 사항이며 권장됩니다(생략 시 auth 유형의 기본 환경 키로 폴백, 예: openai의 경우 OPENAI_API_KEY). 선택적으로 name, description, baseUrl 및 generationConfig를 포함할 수 있습니다. 자격 증명은 설정에 영구 저장되지 않으며, 런타임은 process.env[envKey]에서 읽습니다. Qwen OAuth 모델은 하드코딩된 상태로 유지되며 재정의할 수 없습니다.

Auth 유형별 구성 예시

아래는 다양한 인증 유형에 대한 포괄적인 구성 예시로, 사용 가능한 매개변수와 그 조합을 보여줍니다.

지원되는 Auth 유형

modelProviders 객체 키는 유효한 authType 값이어야 합니다. 현재 지원되는 auth 유형은:

[!warning] 내장 프로토콜이 아니거나 providerProtocol을 통해 매핑되지 않은 제공자 id(예: "openai-custom"과 같은 오타)는 라우팅할 수 없으므로 전체 항목이 경고와 함께 건너뛰어집니다 — 모델이 /model 선택기에 표시되지 않습니다. 내장 제공자의 경우 위의 지원되는 auth 유형 값 중 하나를 사용하거나, 사용자 정의 id에 대한 providerProtocol 매핑을 추가하세요.

사용자 정의 제공자 id (providerProtocol)

내장 제공자 id(openai, gemini, anthropic, vertex-ai, qwen-oauth)는 자동으로 SDK 프로토콜로 라우팅됩니다. 사용자 정의 제공자 id를 사용하려면 — 예를 들어 여러 OpenAI 호환 엔드포인트를 더 친근한 이름으로 그룹화 — modelProviders 아래에 선언하고 최상위 providerProtocol 설정으로 내장 프로토콜에 매핑하세요:

{
  "modelProviders": {
    "idealab": [
      {
        "id": "my-model",
        "envKey": "IDEALAB_API_KEY",
        "baseUrl": "https://idealab.example.com/v1"
      }
    ]
  },
  "providerProtocol": {
    "idealab": "openai"
  }
}

일치하는 providerProtocol 항목이 없으면 사용자 정의 제공자 id는 건너뛰어집니다(위의 경고 참조).

API 요청에 사용되는 SDK

Qwen Code는 각 제공자에 요청을 전송하기 위해 다음 공식 SDK를 사용합니다:

즉, 구성한 baseUrl은 해당 SDK의 예상 API 형식과 호환되어야 합니다. 예를 들어, openai auth 유형을 사용할 때 엔드포인트는 OpenAI API 형식 요청을 수락해야 합니다.

OpenAI 호환 제공자 (openai)

이 auth 유형은 OpenAI의 공식 API뿐만 아니라 OpenRouter 및 Requesty와 같은 집계 모델 제공자를 포함한 모든 OpenAI 호환 엔드포인트를 지원합니다.

{
  "env": {
    "OPENAI_API_KEY": "sk-your-actual-openai-key-here",
    "OPENROUTER_API_KEY": "sk-or-your-actual-openrouter-key-here",
    "REQUESTY_API_KEY": "sk-your-actual-requesty-key-here"
  },
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 3,
          "retryInitialDelayMs": 3000,
          "retryMaxDelayMs": 30000,
          "enableCacheControl": true,
          "contextWindowSize": 128000,
          "modalities": {
            "image": true
          },
          "customHeaders": {
            "X-Client-Request-ID": "req-123"
          },
          "extra_body": {
            "enable_thinking": true,
            "service_tier": "priority"
          },
          "samplingParams": {
            "temperature": 0.2,
            "top_p": 0.8,
            "max_tokens": 4096,
            "presence_penalty": 0.1,
            "frequency_penalty": 0.1
          }
        }
      },
      {
        "id": "gpt-4o-mini",
        "name": "GPT-4o Mini",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 30000,
          "samplingParams": {
            "temperature": 0.5,
            "max_tokens": 2048
          }
        }
      },
      {
        "id": "openai/gpt-4o",
        "name": "GPT-4o (via OpenRouter)",
        "envKey": "OPENROUTER_API_KEY",
        "baseUrl": "https://openrouter.ai/api/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 3,
          "samplingParams": {
            "temperature": 0.7
          }
        }
      },
      {
        "id": "openai/gpt-4o-mini",
        "name": "GPT-4o Mini (via Requesty)",
        "envKey": "REQUESTY_API_KEY",
        "baseUrl": "https://router.requesty.ai/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 3,
          "samplingParams": {
            "temperature": 0.7
          }
        }
      }
    ]
  }
}

Anthropic (anthropic)

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-your-actual-anthropic-key-here"
  },
  "modelProviders": {
    "anthropic": [
      {
        "id": "claude-3-5-sonnet",
        "name": "Claude 3.5 Sonnet",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 3,
          "contextWindowSize": 200000,
          "samplingParams": {
            "temperature": 0.7,
            "max_tokens": 8192,
            "top_p": 0.9
          }
        }
      },
      {
        "id": "claude-3-opus",
        "name": "Claude 3 Opus",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1",
        "generationConfig": {
          "timeout": 180000,
          "samplingParams": {
            "temperature": 0.3,
            "max_tokens": 4096
          }
        }
      }
    ]
  }
}

Google Gemini (gemini)

{
  "env": {
    "GEMINI_API_KEY": "AIza-your-actual-gemini-key-here"
  },
  "modelProviders": {
    "gemini": [
      {
        "id": "gemini-2.0-flash",
        "name": "Gemini 2.0 Flash",
        "envKey": "GEMINI_API_KEY",
        "baseUrl": "https://generativelanguage.googleapis.com",
        "capabilities": {
          "vision": true
        },
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 2,
          "contextWindowSize": 1000000,
          "schemaCompliance": "auto",
          "samplingParams": {
            "temperature": 0.4,
            "top_p": 0.95,
            "max_tokens": 8192,
            "top_k": 40
          }
        }
      }
    ]
  }
}

일반 Qwen Code 에이전트 정책을 따르면서 도구를 사용할 수 있는 vision 모델의 경우, 두 가지 기능을 모두 가진 전체 턴 이미지 라우팅에 옵트인하세요:

"capabilities": {
  "vision": true,
  "agent": true
}

텍스트 전용 기본 모델이 해당 모델을 구성된 vision 폴백으로 사용하는 경우, 완전한 이미지 포함 턴은 도구 호출과 재시도 동안 정확히 해당 제공자, 모델 및 엔드포인트에 유지됩니다. 다음 독립 턴은 기본 모델로 돌아가며, 각 모델 요청은 대상이 지원하는 미디어 모달리티만 받습니다. 더 안전한 Vision Bridge 트랜스크립션 흐름을 유지하려면 agent를 생략(또는 false로 설정)하세요.

로컬 자체 호스팅 모델 (OpenAI 호환 API를 통해)

대부분의 로컬 추론 서버(vLLM, Ollama, LM Studio 등)는 OpenAI 호환 API 엔드포인트를 제공합니다. 로컬 baseUrl과 openai auth 유형을 사용하여 구성하세요:

{
  "env": {
    "OLLAMA_API_KEY": "ollama",
    "VLLM_API_KEY": "not-needed",
    "LMSTUDIO_API_KEY": "lm-studio"
  },
  "modelProviders": {
    "openai": [
      {
        "id": "qwen2.5-7b",
        "name": "Qwen2.5 7B (Ollama)",
        "envKey": "OLLAMA_API_KEY",
        "baseUrl": "http://localhost:11434/v1",
        "generationConfig": {
          "timeout": 300000,
          "maxRetries": 1,
          "contextWindowSize": 32768,
          "samplingParams": {
            "temperature": 0.7,
            "top_p": 0.9,
            "max_tokens": 4096
          }
        }
      },
      {
        "id": "llama-3.1-8b",
        "name": "Llama 3.1 8B (vLLM)",
        "envKey": "VLLM_API_KEY",
        "baseUrl": "http://localhost:8000/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 2,
          "contextWindowSize": 128000,
          "samplingParams": {
            "temperature": 0.6,
            "max_tokens": 8192
          }
        }
      },
      {
        "id": "local-model",
        "name": "Local Model (LM Studio)",
        "envKey": "LMSTUDIO_API_KEY",
        "baseUrl": "http://localhost:1234/v1",
        "generationConfig": {
          "timeout": 60000,
          "samplingParams": {
            "temperature": 0.5
          }
        }
      }
    ]
  }
}

인증이 필요 없는 로컬 서버의 경우, API 키에 임의의 플레이스홀더 값을 사용할 수 있습니다:

# Ollama (인증 불필요)
export OLLAMA_API_KEY="ollama"
 
# vLLM (인증이 구성되지 않은 경우)
export VLLM_API_KEY="not-needed"

Alibaba Cloud Coding Plan

Alibaba Cloud Coding Plan은 코딩 작업에 최적화된 사전 구성된 Qwen 모델 세트를 제공합니다. 이 기능은 Alibaba Cloud Coding Plan API 접근이 있는 사용자를 위해 자동 모델 구성 업데이트와 함께 간소화된 설정 경험을 제공합니다.

개요

/auth 명령을 사용하여 Alibaba Cloud Coding Plan API 키로 인증하면 Qwen Code가 자동으로 다음 모델을 구성합니다:

설정

1. Alibaba Cloud Coding Plan API 키를 획득합니다:
   • 중국: https://bailian.console.aliyun.com/?tab=model#/efm/coding_plan 
   • 국제: https://modelstudio.console.alibabacloud.com/?tab=dashboard#/efm/coding_plan 
2. Qwen Code에서 /auth 명령을 실행합니다
3. Alibaba ModelStudio를 선택한 후 하위 메뉴에서 Coding Plan을 선택합니다
4. 지역을 선택합니다
5. 프롬프트에 API 키를 입력합니다

모델이 자동으로 구성되어 /model 선택기에 추가됩니다.

지역

Alibaba Cloud Coding Plan은 두 지역을 지원합니다:

지역은 인증 중에 선택되어 modelProviders 구성 아래의 settings.json에 저장됩니다. 지역을 전환하려면 /auth 명령을 다시 실행하고 다른 지역을 선택하세요.

API 키 저장

/auth 명령을 통해 Coding Plan을 구성하면 API 키는 예약된 환경 변수 이름 BAILIAN_CODING_PLAN_API_KEY를 사용하여 저장됩니다. 기본적으로 settings.json 파일의 env 필드에 저장됩니다.

# ~/.qwen/.env
BAILIAN_CODING_PLAN_API_KEY=your-api-key-here

자동 업데이트

Coding Plan 모델 구성은 버전 관리됩니다. Qwen Code가 모델 템플릿의 새 버전을 감지하면 업데이트를 요청합니다. 업데이트를 수락하면:

• 기존 Coding Plan 모델 구성이 최신 버전으로 대체됩니다
• 수동으로 추가한 사용자 정의 모델 구성은 보존됩니다
• 업데이트된 구성의 첫 번째 모델로 자동 전환됩니다

업데이트 과정은 수동 개입 없이 항상 최신 모델 구성과 기능에 접근할 수 있도록 보장합니다.

수동 구성 (고급)

Coding Plan 모델을 수동으로 구성하려면 다른 OpenAI 호환 제공자와 마찬가지로 settings.json에 추가할 수 있습니다:

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "name": "qwen3-coder-plus",
        "description": "Qwen3-Coder via Alibaba Cloud Coding Plan",
        "envKey": "YOUR_CUSTOM_ENV_KEY",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1"
      }
    ]
  }
}

해석 계층 및 원자성

유효한 auth/model/credential 값은 필드별로 다음 우선 순위를 사용하여 선택됩니다(먼저 존재하는 것이 우선). --auth-type과 --model을 함께 사용하여 제공자 항목을 직접 가리킬 수 있습니다. 이러한 CLI 플래그는 다른 계층보다 먼저 실행됩니다.

*존재하는 경우 CLI auth 플래그가 설정을 재정의합니다. 그렇지 않으면 security.auth.selectedType 또는 암묵적 기본값이 auth 유형을 결정합니다. Qwen OAuth와 OpenAI는 추가 구성 없이 노출되는 유일한 auth 유형입니다.

Generation Config 계층화: 침투 불가능한 제공자 계층

구성 해석은 하나의 중요한 규칙을 가진 엄격한 계층화 모델을 따릅니다: modelProvider 계층은 침투 불가능합니다.

작동 방식

1. modelProvider 모델이 선택된 경우(예: /model 명령으로 제공자 구성 모델 선택):

   • 제공자의 전체 generationConfig가 원자적으로 적용됩니다
   • 제공자 계층은 완전히 침투 불가능합니다 — 하위 계층(CLI, env, settings)은 generationConfig 해석에 전혀 참여하지 않습니다
   • modelProviders[].generationConfig에 정의된 모든 필드는 제공자의 값을 사용합니다
   • 제공자가 정의하지 않은 모든 필드는 undefined로 설정됩니다(settings에서 상속되지 않음)
   • 이렇게 하면 제공자 구성이 완전한 자체 포함 “봉인된 패키지”로 작동합니다

   모델이 modelProviders에 나열되면, 해당 모델에 대한 모든 모델별 generation 설정을 일치하는 제공자 항목에 넣으세요. 최상위 model.generationConfig 값은 contextWindowSize, modalities, customHeaders 및 extra_body를 포함하여 제공자 모델에 대해 무시됩니다. 적용되려면 modelProviders[authType][].generationConfig 아래에서 이러한 필드를 구성하세요.

2. modelProvider 모델이 선택되지 않은 경우(예: 원시 모델 ID와 함께 --model 사용, 또는 CLI/env/settings를 직접 사용):

   • 해석이 하위 계층으로 전달됩니다
   • 필드가 CLI → env → settings → 기본값에서 채워집니다
   • 이렇게 하면 런타임 모델이 생성됩니다(다음 섹션 참조)

generationConfig의 필드별 우선 순위

원자적 필드 처리

다음 필드는 원자적 객체로 취급됩니다 - 제공자 값이 전체 객체를 완전히 대체하며, 병합이 발생하지 않습니다:

• samplingParams - Temperature, top_p, max_tokens 등
• customHeaders - 사용자 정의 HTTP 헤더
• extra_body - 추가 요청 본문 매개변수

예시

// 사용자 설정 (~/.qwen/settings.json)
{
  "model": {
    "generationConfig": {
      "timeout": 30000,
      "samplingParams": { "temperature": 0.5, "max_tokens": 1000 }
    }
  }
}
 
// modelProviders 구성
{
  "modelProviders": {
    "openai": [{
      "id": "gpt-4o",
      "envKey": "OPENAI_API_KEY",
      "generationConfig": {
        "timeout": 60000,
        "samplingParams": { "temperature": 0.2 }
      }
    }]
  }
}

gpt-4o가 modelProviders에서 선택되면:

• timeout = 60000(제공자에서, 설정을 재정의)
• samplingParams.temperature = 0.2(제공자에서, 설정 객체를 완전히 대체)
• samplingParams.max_tokens = undefined(제공자에 정의되지 않았고, 제공자 계층은 settings에서 상속하지 않음 — 제공되지 않으면 필드가 명시적으로 undefined로 설정됨)

--model gpt-4를 통해 원시 모델 사용(modelProviders가 아닌, 런타임 모델 생성):

• timeout = 30000(settings에서)
• samplingParams.temperature = 0.5(settings에서)
• samplingParams.max_tokens = 1000(settings에서)

modelProviders 자체의 병합 전략은 REPLACE입니다: 프로젝트 설정의 전체 modelProviders가 사용자 설정의 해당 섹션을 재정의하며, 두 설정을 병합하지 않습니다.

추론 / 사고 구성

generationConfig 아래의 선택적 reasoning 필드는 모델이 응답하기 전에 얼마나 적극적으로 추론하는지를 제어합니다. Anthropic 및 Gemini 변환기는 항상 이를 존중합니다. OpenAI 호환 파이프라인은 generationConfig.samplingParams가 설정되지 않은 경우에만 존중합니다 — 아래 “interaction with samplingParams” 주의 사항을 참조하세요.

{
  "modelProviders": {
    "openai": [
      {
        "id": "deepseek-v4-pro",
        "name": "DeepSeek V4 Pro",
        "baseUrl": "https://api.deepseek.com/v1",
        "envKey": "DEEPSEEK_API_KEY",
        "generationConfig": {
          // 4단계 스케일:
          //   'low'    | 'medium' — DeepSeek에서 서버 측 'high'로 매핑
          //   'high'   — 기본 추론 강도
          //   'max'    — DeepSeek 전용 추가 강력한 티어
          // 또는 추론을 완전히 비활성화하려면 `false`를 설정합니다.
          "reasoning": { "effort": "max" },
        },
      },
    ],
  },
}

제공자별 동작

reasoning: false

reasoning: false(리터럴 부울)를 설정하면 모든 제공자에서 추론이 명시적으로 비활성화됩니다 — 추론의 이점이 없는 저렴한 사이드 쿼리에 유용합니다. 이는 일회성 호출(예: 제안 생성)에 대해 request.config.thinkingConfig.includeThoughts: false를 통해 요청 수준에서도 존중됩니다.

api.deepseek.com baseURL에서 OpenAI 파이프라인은 DeepSeek V4+가 요구하는 명시적 thinking: { type: 'disabled' } 필드를 내보냅니다 — 서버 측 기본값은 'enabled'이므로 reasoning_effort를 생략하기만 하면 여전히 사고 지연/비용이 발생합니다. 자체 호스팅 DeepSeek 백엔드(sglang/vllm) 및 기타 OpenAI 호환 서버는 이 필드를 받지 않습니다. 이러한 서버에서 사고를 비활성화해야 하는 경우 samplingParams/extra_body를 통해 thinking: { type: 'disabled' }(또는 추론 프레임워크가 노출하는 Knob)를 주입하세요.

samplingParams와의 상호 작용 (OpenAI 호환만)

budget_tokens

effort와 함께 budget_tokens를 포함하여 정확한 사고 토큰 예산을 고정할 수 있습니다:

"reasoning": { "effort": "high", "budget_tokens": 50000 }

Anthropic의 경우 thinking.budget_tokens가 됩니다. OpenAI/DeepSeek의 경우 필드는 보존되지만 현재 서버에서 무시됩니다 — reasoning_effort가 핵심 knob입니다.

제공자 모델 vs 런타임 모델

Qwen Code는 두 가지 유형의 모델 구성을 구분합니다:

제공자 모델

• modelProviders 구성에 정의됨
• 완전한 원자적 구성 패키지를 가짐
• 선택되면 구성이 침투 불가능한 계층으로 적용됨
• 전체 메타데이터(이름, 설명, 기능)와 함께 /model 명령 목록에 표시됨
• 다중 모델 워크플로우 및 팀 일관성에 권장

런타임 모델

• CLI(--model), 환경 변수 또는 설정을 통해 원시 모델 ID를 사용할 때 동적으로 생성됨
• modelProviders에 정의되지 않음
• 구성이 해석 계층(CLI → env → settings → 기본값)을 “투영”하여 구축됨
• 완전한 구성이 감지되면 RuntimeModelSnapshot으로 자동 캡처됨
• 자격 증명을 다시 입력하지 않고 재사용 가능

RuntimeModelSnapshot 수명 주기

modelProviders를 사용하지 않고 모델을 구성하면 Qwen Code가 구성을 보존하기 위해 자동으로 RuntimeModelSnapshot을 생성합니다:

# ID가 $runtime|openai|my-custom-model인 RuntimeModelSnapshot을 생성
qwen --auth-type openai --model my-custom-model --openai-api-key $KEY --openai-base-url https://api.example.com/v1

스냅샷:

• 모델 ID, API 키, 기본 URL 및 generation config를 캡처
• 세션 간 지속(런타임 중 메모리에 저장)
• 런타임 옵션으로 /model 명령 목록에 표시
• /model $runtime|openai|my-custom-model을 사용하여 전환 가능

주요 차이점

각각을 사용해야 하는 경우

• 제공자 모델 사용: 팀에서 공유하는 표준 모델이 있거나, 일관된 구성이 필요하거나, 실수한 재정의 방지
• 런타임 모델 사용: 새 모델을 빠르게 테스트하거나, 임시 자격 증명을 사용하거나, 임시 엔드포인트로 작업

선택 지속 및 권장 사항

• /model 및 /auth는 modelProviders를 이미 정의하는 가장 가까운 쓰기 가능한 범위에 model.name(해당되는 경우) 및 security.auth.selectedType을 지속합니다. 그렇지 않으면 사용자 범위로 폴백합니다. 이렇게 하면 작업 공간/사용자 파일이 활성 제공자 카탈로그와 동기화됩니다.
• modelProviders가 없으면 해석기가 CLI/env/settings 계층을 혼합하여 런타임 모델을 생성합니다. 단일 제공자 설정에는 괜찮지만 자주 전환할 때는 번거롭습니다. 다중 모델 워크플로우가 일반적인 경우 제공자 카탈로그를 정의하여 전환이 원자적이고, 소스가 추적 가능하며, 디버그하기 쉽게 합니다.