Updated 2026-08-05

Use an Alibaba Cloud API key in OpenClaw

Alibaba's maintained OpenClaw configuration uses an Anthropic Messages provider in `~/.openclaw/openclaw.json`. Add the provider with `models.mode = "merge"`, keep existing channels and plugins, register only supported model IDs, and set a `provider/model` primary reference. Restart the gateway, then use `/model` for a session-level switch without rewriting the entire file.

1. Install or reopen OpenClaw without discarding existing state

Install a current OpenClaw release or re-enter onboarding if it is already present. Existing users should inspect `~/.openclaw/openclaw.json` before copying provider examples because that file can also contain channels, plugins, gateway authentication, and agent defaults.

The provider update is a merge operation. Do not replace the whole file when the user already has Feishu, WeChat, DingTalk, Telegram, Skills, or MCP configuration.

npm install -g openclaw@latest
openclaw --version

# Re-enter onboarding when needed
openclaw onboard --install-daemon

Sources checked

Alibaba Cloud OpenClaw guide - Primary source for installation, pay-as-you-go provider JSON, merge behavior, model commands, and troubleshooting.
OpenClaw model providers - Upstream source for custom provider schemas and Anthropic-compatible endpoint behavior.

2. Add a region-matched Anthropic Messages provider

The example uses a Beijing workspace and the provider ID `bailian`. Replace `{WorkspaceId}` and `YOUR_API_KEY` with the values belonging to the same ordinary Model Studio key. A Singapore key uses the `ap-southeast-1` workspace hostname.

The Base URL ends at `/apps/anthropic` because OpenClaw appends `/v1/messages`. Set `api` to `anthropic-messages`. Do not combine this provider mode with the OpenAI-compatible `/compatible-mode/v1` path.

{
  "models": {
    "mode": "merge",
    "providers": {
      "bailian": {
        "baseUrl": "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic",
        "apiKey": "YOUR_API_KEY",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "qwen3.7-max",
            "name": "Qwen3.7 Max",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 1000000,
            "maxTokens": 65536,
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "compat": { "thinkingFormat": "openai" }
          },
          {
            "id": "qwen3.6-plus",
            "name": "Qwen3.6 Plus",
            "reasoning": false,
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 65536,
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "compat": { "thinkingFormat": "openai" }
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "bailian/qwen3.7-max" },
      "models": {
        "bailian/qwen3.7-max": {},
        "bailian/qwen3.6-plus": {}
      }
    }
  }
}

3. Treat model metadata and cost fields as client configuration

OpenClaw needs model metadata to size context and expose capabilities. Copy context, output, modality, and reasoning values from current Alibaba model documentation. Do not copy limits from another model simply because both use Qwen in the display name.

The zero-valued `cost` object in Alibaba's OpenClaw example is local client metadata; it does not make Model Studio calls free. Actual pay-as-you-go billing remains on the Alibaba account that owns the key.

Sources checked

Alibaba qwen3.7-max model reference - Primary source for context, output, modalities, and reasoning capabilities used in the model entry.

4. Restart the gateway and verify the provider status

Save the merged JSON, restart the gateway, and open the terminal UI. Use `/status` and `/model status` to confirm the provider endpoint, API mode, and active model before sending a tool-enabled task.

If an old cached provider keeps returning authentication errors, Alibaba documents removing only the stale `providers` block from `~/.openclaw/agents/main/agent/models.json`, then restarting OpenClaw. Do not delete channel or Skill configuration as a first diagnostic step.

openclaw gateway restart
openclaw tui

# Inside OpenClaw
/status
/model status

5. Switch the current session or persistent primary model

Use `/model` to open the picker or enter the strict provider/model reference directly. A session selection takes effect without rewriting `agents.defaults.model.primary`. Use `/model default` to clear the session override and return to the persistent primary.

For a persistent change, edit `agents.defaults.model.primary` to another model already registered under both the provider catalog and the allowed `agents.defaults.models` map, then restart the gateway.

# Inside OpenClaw
/model
/model bailian/qwen3.6-plus
/model status
/model default

Sources checked

OpenClaw model selection commands - Upstream source for session selection, strict provider/model references, defaults, and status.

6. Keep provider configuration separate from channels and Skills

Model routing lives under `models` and `agents`. Message channels live under `channels`, while Skills, MCP services, and plugins have their own blocks. A model change should not overwrite the credentials or state of those integrations.

When preparing a reusable setup document, show the provider fragment and the merge points instead of telling readers to replace the entire `openclaw.json`. This keeps onboarding reversible and protects existing deployments.

FAQ

Which protocol should OpenClaw use with an ordinary Alibaba API key?

Alibaba's maintained OpenClaw example uses `api: "anthropic-messages"` with a Base URL ending at `/apps/anthropic`.

How do I switch models in the current OpenClaw session?

Use `/model provider/model`, such as `/model bailian/qwen3.6-plus`. Use `/model default` to return to the persistent primary.

How do I change the default model permanently?

Register the model in the provider and allowed model maps, change `agents.defaults.model.primary`, and restart the gateway.

Can I overwrite openclaw.json with the example?

Only for a truly new installation. Existing users should merge the model and agent blocks so channels, plugins, Skills, and gateway settings survive.

Do zero cost fields mean Alibaba calls are free?

No. Those values are OpenClaw client metadata. The ordinary Model Studio key remains pay-as-you-go on the owning Alibaba account.

A safe OpenClaw integration is a narrow merge: add one region-matched Anthropic provider, register exact model metadata, set a provider/model primary, and leave channels and Skills untouched. Verify with `/model status`, then switch sessions without rewriting the provider.

Related model comparisons

Continue from this guide into structured DeepSeek-first comparison pages with model tables, routing advice, and pricing context.

Best AI model for agentic workflows: DeepSeek V4-first routing Best AI model for coding: DeepSeek V4-first comparison DeepSeek V4 API Pricing: Pro, Flash and Major Rivals

Configure Alibaba API key in Hermes