Model providers and authentication
Use /auth in the interactive terminal. For a managed or headless setup,
define the provider in the system or user config file; project config cannot
add credentials or provider definitions.
Choose a provider interactively
/auth
The picker offers Aliyun AK/SK, DashScope, OpenAI-compatible, Coding Plan, and
Token Plan profiles. Built-in plan endpoints use the China catalog by default.
Choose the international catalog before starting cosh when needed:
COSH_SERVICE_SITE=international cosh
china/cn and international/intl/global are accepted values. This
only changes built-in plan endpoints; it does not rewrite a saved custom URL.
Configure a provider
Put this example in ~/.copilot-shell/config.toml (or the administrator file
/etc/copilot-shell/config.toml) and export the key in the environment:
[ai]
active_provider = "dashscope"
active_model = "qwen3.7-plus"
[ai.providers.dashscope]
type = "dashscope"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
api_key = "${DASHSCOPE_API_KEY}"
model = "qwen3.7-plus"
Other common profiles use the same shape:
[ai.providers.openai]
type = "openai"
base_url = "https://api.openai.com/v1"
api_key = "${OPENAI_API_KEY}"
model = "gpt-4o"
[ai.providers.deepseek]
type = "deepseek"
base_url = "https://api.deepseek.com/v1"
api_key = "${DEEPSEEK_API_KEY}"
model = "deepseek-chat"
[ai.providers.aliyun]
type = "aliyun"
access_key_id = "${ALIBABA_CLOUD_ACCESS_KEY_ID}"
access_key_secret = "${ALIBABA_CLOUD_ACCESS_KEY_SECRET}"
security_token = "${ALIBABA_CLOUD_SECURITY_TOKEN}"
model = "qwen3.7-plus"
For an ECS RAM role, use type = "aliyun" with
auth_source = "ecs_ram_role"; static AK/SK values are then unnecessary.
type | Use |
|---|---|
dashscope | DashScope OpenAI-compatible endpoint with Qwen reasoning support |
openai | OpenAI request conventions, including max_completion_tokens |
deepseek | OpenAI-compatible endpoint with reasoning-content support |
aliyun | Alibaba Cloud SysOM with AK/SK or ECS RAM role |
| any other value | Generic OpenAI-compatible behavior |
Set explicit_cache = true only for DashScope when you want explicit cache
markers. Leave it unset or false for the default behavior.
Precedence and missing credentials
The active provider and model are resolved in this order: configuration layers,
then COSH_AI_PROVIDER/COSH_MODEL/COSH_OUTPUT_LANGUAGE, then provider
fields and their environment fallbacks. --model <name> overrides only the
model; use COSH_AI_PROVIDER or active_provider to switch providers.
| Variable | Fallback |
|---|---|
OPENAI_BASE_URL | OpenAI-compatible base URL |
DASHSCOPE_API_KEY, then OPENAI_API_KEY | API-key providers |
ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, ALIBABA_CLOUD_SECURITY_TOKEN | Aliyun credentials |
If a key is missing, interactive Core asks for authentication. A standalone headless client must answer that control request or configure credentials before startup. See Configuration for file-layer rules and Headless mode for the control protocol.