Updated 2026-08-05
Use an Alibaba Cloud API key in Claude Code
Claude Code should use Alibaba's Anthropic-compatible Messages endpoint, not the OpenAI-compatible Base URL. Put the ordinary Model Studio key in `ANTHROPIC_AUTH_TOKEN`, stop the regional Base URL at `/apps/anthropic`, and map Claude Code's main, Haiku, Sonnet, Opus, and subagent roles to real model IDs permitted by the workspace. Use `/status` to verify the route before editing a repository.
1. Install one current Claude Code CLI
Alibaba documents the npm package with Node.js 18 or later. Anthropic also offers native installers, but the provider configuration is independent of installation method. Keep one current executable so an older binary does not shadow the settings you just changed.
After installation, confirm the version and create the user settings directory. This guide covers Claude Code CLI and IDE surfaces that reuse its settings, not the separate Claude Desktop local-gateway workflow.
npm install -g @anthropic-ai/claude-code
claude --version
mkdir -p ~/.claudeSources checked
- Alibaba Cloud Claude Code guide - Primary source for installation, pay-as-you-go settings, regional hosts, model mappings, and `/status` verification.
- Anthropic Claude Code setup - Upstream source for the current Claude Code client and supported installation paths.
2. Complete onboarding without routing through Anthropic
Alibaba's documented third-party-provider flow sets `hasCompletedOnboarding` to `true` in `~/.claude.json`. This prevents the CLI from starting an unrelated Anthropic login flow before it reads the Model Studio environment block.
If Claude Code later tries to reach `api.anthropic.com`, check this onboarding flag and the active settings before assuming the Alibaba key is invalid.
{
"hasCompletedOnboarding": true
}3. Configure the ordinary API key and Anthropic-compatible route
Create `~/.claude/settings.json` with the environment block below. The Beijing host is a template: replace `{WorkspaceId}` with the workspace that owns the key. A Singapore key needs the `ap-southeast-1` hostname instead.
Do not append `/v1` to `ANTHROPIC_BASE_URL`. Claude Code appends `/v1/messages`; adding it yourself can create a duplicated `/v1/v1` path. The example maps the strongest main roles to `qwen3.7-max` and the lighter Haiku role to `qwen3.6-flash`.
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
"ANTHROPIC_BASE_URL": "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic",
"ANTHROPIC_MODEL": "qwen3.7-max",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen3.6-flash",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen3.7-max",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen3.7-max",
"CLAUDE_CODE_SUBAGENT_MODEL": "qwen3.7-max"
}
}Sources checked
- Alibaba Anthropic-compatible Messages API - Primary source for the Base URL ending, `/v1/messages`, and model-discovery limitations.
4. Verify the active endpoint and model before granting edit access
Open a new terminal and run one small prompt. Then use `/status` inside Claude Code to inspect `ANTHROPIC_BASE_URL`, authentication, and the selected model. A response alone does not prove the intended role mapping handled the request.
For a direct protocol check, send a minimal request to `/apps/anthropic/v1/messages`. If the direct call succeeds but Claude Code fails, focus on settings scope, onboarding, model mapping, and process environment rather than rotating the key.
claude "Reply with claude-code-ok"
# Inside an interactive Claude Code session
/status5. Switch models for one session or change the persistent mapping
Use `claude --model MODEL_ID` to start one session with another permitted Alibaba model. This is useful for comparing `qwen3.7-max` and `qwen3.7-plus` without rewriting every role mapping. The exact value is sent to the configured gateway, so it must be a real API model ID.
For a persistent switch, update `ANTHROPIC_MODEL` and whichever default or subagent roles should follow it, then start a new process. Leaving old role mappings in place can produce mixed model usage even when the main model changed successfully.
# One session only
claude --model qwen3.7-plus
# After a persistent settings change
claude "Report the active model and summarize this repository read-only"Sources checked
- Anthropic Claude Code CLI reference - Upstream source for the `--model` session flag.
6. Diagnose duplicated paths, missing discovery, and mixed routing
A request containing `/v1/v1/` means the configured Base URL includes one version segment too many. A `/v1/models` 404 can be expected because Alibaba's Anthropic-compatible endpoint exposes Messages but not model discovery. Add and map exact model IDs manually.
If main work uses one model and subagent work uses another, inspect all five mapping variables before calling it a fallback. Claude Code has multiple model roles by design. Keep the mapping intentional and document which roles are allowed to differ.
FAQ
Which Alibaba protocol should Claude Code use?
Use the Anthropic-compatible Messages route with `ANTHROPIC_BASE_URL` ending at `/apps/anthropic`.
Why must the Base URL omit /v1?
Claude Code appends `/v1/messages`. Including `/v1` in the Base URL can produce a duplicated `/v1/v1` path.
How do I switch only the current Claude Code session?
Start it with `claude --model MODEL_ID`, using a model ID permitted by the same workspace.
Why does /status show the Alibaba endpoint but usage reaches two models?
Check the Haiku, Sonnet, Opus, and subagent mappings. They can intentionally differ from the main model.
Does Claude Code need an Anthropic API key for this setup?
No. The ordinary Alibaba key is supplied through `ANTHROPIC_AUTH_TOKEN` and sent to the configured Model Studio endpoint.
Claude Code needs a complete Anthropic Messages configuration: onboarding completed, region-matched `/apps/anthropic` Base URL, ordinary Model Studio key, and explicit model-role mappings. Verify with `/status`, then switch session or persistent models without changing the protocol.
Related model comparisons
Continue from this guide into structured DeepSeek-first comparison pages with model tables, routing advice, and pricing context.