Updated 2026-08-05
Use an Alibaba Cloud API key in OpenCode
Alibaba's current OpenCode recipe uses the Anthropic SDK path for ordinary pay-as-you-go keys. The working combination is `@ai-sdk/anthropic`, a region-matched workspace Base URL ending in `/apps/anthropic/v1`, and an explicit model catalog. Keep the credential in `DASHSCOPE_API_KEY`, then use `/models` to switch between the models you actually added.
1. Install OpenCode and locate its configuration
Alibaba documents Node.js 18 or later and the `opencode-ai` npm package. Verify the executable before editing provider files so an older installation does not make a correct config look broken.
On macOS and Linux, the global user configuration is `~/.config/opencode/opencode.json`. OpenCode can also load project configuration, so verify which scope you are editing when one repository behaves differently from another.
npm install -g opencode-ai
opencode -v
mkdir -p ~/.config/opencodeSources checked
- Alibaba Cloud OpenCode guide - Primary source for installation, config paths, pay-as-you-go provider settings, and verification.
- OpenCode provider documentation - Upstream source for custom providers, environment substitution, and the model picker.
2. Export the ordinary Model Studio key
Set the key in the shell that launches OpenCode. The config can read it with OpenCode's `{env:VARIABLE}` substitution, which keeps the plaintext credential out of JSON and makes rotation independent from the provider catalog.
This must be an ordinary pay-as-you-go key whose workspace and region match the Base URL. Do not point an `sk-sp` plan key at this workspace endpoint.
export DASHSCOPE_API_KEY="replace-with-your-own-api-key"
test -n "$DASHSCOPE_API_KEY" && echo "API key variable is set"3. Add the Alibaba Anthropic provider and explicit models
The example below uses Beijing. Replace `{WorkspaceId}` with the workspace that owns the key. For Singapore, change the regional hostname to `ap-southeast-1` and keep `/apps/anthropic/v1` at the end.
Only add model IDs your workspace permits. `qwen3.7-max` and `qwen3.7-plus` are shown because Alibaba's OpenCode page documents both for the pay-as-you-go Anthropic route. Do not invent client limits; copy current context and output metadata only when you have checked the model page.
{
"$schema": "https://opencode.ai/config.json",
"model": "bailian-payg/qwen3.7-max",
"provider": {
"bailian-payg": {
"npm": "@ai-sdk/anthropic",
"name": "Alibaba Cloud Model Studio",
"options": {
"baseURL": "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic/v1",
"apiKey": "{env:DASHSCOPE_API_KEY}"
},
"models": {
"qwen3.7-max": {
"name": "Qwen3.7 Max",
"options": {
"thinking": { "type": "enabled", "budgetTokens": 8192 }
}
},
"qwen3.7-plus": {
"name": "Qwen3.7 Plus",
"options": {
"thinking": { "type": "enabled", "budgetTokens": 8192 }
}
}
}
}
}
}4. Start OpenCode and switch models with /models
Start a new OpenCode process after exporting the key. Enter `/models`, search for Alibaba Cloud Model Studio, and select `bailian-payg/qwen3.7-max` or another configured entry. The selection changes the current session; the top-level `model` field remains the persistent default.
Use the provider/model reference shown in the picker rather than a display label. Provider and model IDs are case-sensitive, and a model omitted from the `models` map will not appear for this custom provider.
opencode
# Inside OpenCode
/models
# Select one of the configured references
bailian-payg/qwen3.7-max
bailian-payg/qwen3.7-plusSources checked
- OpenCode model selection - Upstream source for `/models`, provider/model references, and session versus default selection.
5. Understand why this guide uses Anthropic Messages
OpenCode supports more than one provider package, but Alibaba's maintained pay-as-you-go example uses `@ai-sdk/anthropic` and the Anthropic-compatible workspace endpoint. That produces Messages requests, not Chat Completions or Responses requests.
If you intentionally build an OpenAI-compatible provider instead, change the package and endpoint together and test that protocol separately. Do not keep the Anthropic package while replacing only the path with `/compatible-mode/v1`.
6. Diagnose missing models and authentication failures
If the provider is missing, validate the JSON and confirm the file path. If the model is missing, confirm it exists under the provider's `models` object. If the request returns 401 or 403, confirm the OpenCode process received `DASHSCOPE_API_KEY`, then compare the key's workspace, region, model permission, and IP policy with the Base URL.
A `/v1/models` discovery 404 is not sufficient evidence that the key failed because Alibaba's Anthropic-compatible endpoint does not expose that resource. The configured model catalog and a real Messages request are the relevant test.
FAQ
Which protocol does Alibaba recommend for OpenCode?
Alibaba's current pay-as-you-go guide uses `@ai-sdk/anthropic` with the Anthropic-compatible `/apps/anthropic/v1` Base URL.
How do I switch Qwen models in OpenCode?
Add both exact IDs under the provider's `models` map, restart or reload OpenCode, then use `/models` to select the provider/model reference.
Why is my model missing from /models?
Custom providers have no automatic catalog. Add the exact model ID to `models`, confirm the provider is connected, and validate the JSON file scope.
Can I keep the API key out of opencode.json?
Yes. Use `{env:DASHSCOPE_API_KEY}` in `options.apiKey` and export the variable before launching OpenCode.
Should I use the /compatible-mode/v1 URL with @ai-sdk/anthropic?
No. That mixes an Anthropic client with an OpenAI-compatible path. Follow one complete provider protocol at a time.
A stable Alibaba OpenCode setup keeps four values aligned: the ordinary key, its workspace region, the Anthropic provider package, and an explicit model catalog. Use `/models` for session switching and the top-level `model` field for the persistent default.
Related model comparisons
Continue from this guide into structured DeepSeek-first comparison pages with model tables, routing advice, and pricing context.