Updated 2026-08-05
One Alibaba API key, three protocols, six different client configurations
Do not copy one Base URL into every coding tool. A standard Alibaba Cloud Model Studio API key can call multiple compatible protocols, but each client expects a particular request contract. Codex uses OpenAI-compatible Responses, Cursor uses standard OpenAI-compatible chat, and Alibaba's documented OpenCode, Claude Code, and OpenClaw paths use Anthropic Messages. Hermes can use either Messages or Chat Completions. Choose the client first, then the protocol, then the model.
1. Start with the client-to-protocol matrix
The credential can stay the same when its workspace permits the selected model, but the wire format cannot. Responses sends `input` and returns Response objects. Chat Completions sends `messages` and returns `choices`. Anthropic Messages also sends `messages`, but uses Anthropic headers and content blocks instead of the OpenAI response shape.
The Base URL shown below uses the Beijing workspace pattern. A Singapore, Tokyo, Frankfurt, or Virginia key must use the matching regional API Host from Model Studio. Never infer the region from the key prefix.
| Tool | Protocol | Base URL ending | Model switch |
|---|---|---|---|
| Codex CLI | OpenAI Responses | /compatible-mode/v1 | Edit `model` and start a new task |
| Cursor | OpenAI Chat Completions | /compatible-mode/v1 | Select another added model in Cursor Settings |
| OpenCode | Anthropic Messages | /apps/anthropic/v1 | Use `/models` |
| Claude Code | Anthropic Messages | /apps/anthropic | Use `--model` for one session or update model mappings |
| OpenClaw | Anthropic Messages | /apps/anthropic | Use `/model provider/model` |
| Hermes | Anthropic Messages or OpenAI Chat | /apps/anthropic` or `/compatible-mode/v1 | Use `hermes chat -m` or change `model.default` |
Sources checked
- Alibaba Cloud Model Studio API key guide - Primary source for ordinary pay-as-you-go keys, workspace API Hosts, regions, and permissions.
- Alibaba Cloud client and tool guides - Provider-maintained example showing how one tool maps the ordinary key to a specific client protocol.
2. OpenAI Responses is the Codex route
Responses calls `POST /compatible-mode/v1/responses`, accepts an `input` field, and returns a Response object rather than a Chat Completions `choices` array. Current Codex custom providers require this route through `wire_api = "responses"`.
A successful Chat Completions curl does not prove Codex compatibility. Test the Responses endpoint with a model Alibaba currently documents for Responses before putting the same values into `~/.codex/config.toml`.
curl -X POST \
"https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/responses" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.7-plus",
"input": "Reply with responses-ok"
}'Sources checked
- Alibaba OpenAI-compatible Responses API - Primary source for the current endpoint, request body, regional hosts, and Responses limitations.
3. OpenAI Chat Completions is the Cursor route and a Hermes option
Chat Completions calls `POST /compatible-mode/v1/chat/completions`, sends a `messages` array, and returns an OpenAI-compatible `choices` array. Cursor's Override OpenAI Base URL flow uses this standard chat surface. Hermes can also use it when its Anthropic-specific `api_mode` setting is removed or replaced with the tool's Chat Completions mode.
The Base URL stops at `/compatible-mode/v1`; the client appends `/chat/completions`. Do not paste the full endpoint into a field that expects a base URL unless that tool explicitly asks for the complete request URL.
curl -X POST \
"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": "qwen3.7-max",
"messages": [{"role": "user", "content": "Reply with chat-ok"}]
}'Sources checked
- Alibaba OpenAI-compatible Chat API - Primary source for `/chat/completions`, bearer authentication, and the `messages` contract.
4. Anthropic Messages is the documented Claude Code, OpenCode, and OpenClaw route
The final HTTP request is `POST /apps/anthropic/v1/messages`. Claude Code, OpenClaw, and Hermes expect a Base URL ending at `/apps/anthropic` and append `/v1/messages`. Alibaba's OpenCode example uses `@ai-sdk/anthropic` with a Base URL ending at `/apps/anthropic/v1`, after which the SDK appends `/messages`.
That one-segment difference is client behavior, not a different Alibaba product. If a request becomes `/v1/v1/messages`, remove the extra `/v1` from the configured Base URL. The Anthropic-compatible endpoint does not provide `/v1/models`, so add model IDs manually when a client depends on model discovery.
curl -X POST \
"https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic/v1/messages" \
-H "x-api-key: $DASHSCOPE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.7-max",
"max_tokens": 32,
"messages": [{"role": "user", "content": "Reply with messages-ok"}]
}'Sources checked
- Alibaba Anthropic-compatible Messages API - Primary source for the Messages endpoint, Base URL rule, and missing model-discovery endpoint.
5. Model switching changes the model ID, not the key or protocol
When two models belong to the same workspace and both support the client's protocol, switching changes only the exact model ID. The region, workspace API Host, credential, and wire format stay fixed. If the target model is not permitted or does not support that protocol, the switch should fail visibly rather than silently falling back.
Use the provider's API model ID, including punctuation and case. A display name such as 'Qwen Max' is not a valid substitute. Cursor is the exception for several documented model names that require punctuation adjustments in its UI; follow Alibaba's Cursor-specific mapping table.
| Tool | Session switch | Persistent default |
|---|---|---|
| Codex | Start a task with the configured model | Change top-level `model` in `config.toml` |
| OpenCode | `/models` | Set top-level `model` to `provider/model` |
| Cursor | Choose a model in the chat model picker | Keep the model enabled under Cursor Settings > Models |
| Claude Code | `claude --model MODEL_ID` | Update `ANTHROPIC_MODEL` and Claude role mappings |
| OpenClaw | `/model provider/model` | Change `agents.defaults.model.primary` |
| Hermes | `hermes chat -m MODEL_ID` | Change `model.default` |
6. Keep credential class and region out of the model switch
These articles cover ordinary pay-as-you-go Model Studio API keys, typically current `sk-ws` keys or supported legacy `sk-` keys. They do not use plan-specific `sk-sp` credentials. A plan key and an ordinary key can expose similarly named models while requiring different Base URLs and entitlements.
Before distributing any configuration, bind it to the exact workspace, region, allowed model set, and IP policy. A copied model switch should never replace those access controls.
FAQ
Can every tool use the same Alibaba Base URL?
No. The regional host can match, but the path and protocol differ. Codex uses Responses, Cursor uses Chat Completions, and Alibaba's documented Claude Code, OpenCode, and OpenClaw routes use Anthropic Messages.
Why does one Anthropic Base URL include /v1 and another not?
Different clients append different path segments. Follow the client-specific guide so the final request resolves to `/apps/anthropic/v1/messages` exactly once.
Do I need a new key to switch from qwen3.7-plus to qwen3.7-max?
Not when both models are allowed in the same workspace. Change the exact model ID while keeping the key, region, host, and protocol fixed.
Does a successful Chat Completions test prove Codex will work?
No. Codex needs the Responses route. Test `/responses` with a supported model separately.
Why does Anthropic model discovery return 404?
Alibaba's Anthropic-compatible endpoint provides Messages but not `/v1/models`. Add supported model IDs manually instead of treating discovery failure as an invalid key.
Treat protocol as part of the product contract. Keep one ordinary Model Studio key tied to its workspace and region, select the client-specific wire format, and switch only the exact model ID after confirming that model supports the chosen protocol.
Related model comparisons
Continue from this guide into structured DeepSeek-first comparison pages with model tables, routing advice, and pricing context.