Alibaba Cloud Model Studio:Claude Code

O Claude Code é um assistente de codificação com IA via linha de comando desenvolvido pela Anthropic. Conecte-o ao Alibaba Cloud Model Studio usando as modalidades Pay-as-you-go, Coding Plan, Token Plan Personal Edition ou Token Plan Team Edition.

Instalar o Claude Code

Instalação

npm install -g @anthropic-ai/claude-code

claude --version

npm install -g @anthropic-ai/claude-code

Ignorar a verificação de login

Edite ou crie o arquivo ~/.claude.json (no Windows: C:\Users\<username>\.claude.json) e defina hasCompletedOnboarding como true para pular a verificação de login oficial da Anthropic.

{
  "hasCompletedOnboarding": true
}

Configurar credenciais de acesso

Crie o arquivo ~/.claude/settings.json (no Windows: C:\Users\<username>\.claude\settings.json) e adicione a configuração correspondente ao seu plano de faturamento.

Token Plan Personal Edition

Substitua YOUR_API_KEY pela API Key dedicada do Token Plan Personal Edition. Para modelos disponíveis, consulte supported models referente ao Token Plan Personal Edition.

{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
        "ANTHROPIC_BASE_URL": "https://token-plan.ap-southeast-1.maas.aliyuncs.com/apps/anthropic",
        "ANTHROPIC_MODEL": "qwen3.8-max",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen3.6-flash",
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen3.8-max",
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen3.8-max",
        "CLAUDE_CODE_SUBAGENT_MODEL": "qwen3.7-max",
        "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "983616"
    }
}

Token Plan Team Edition

Substitua YOUR_API_KEY pela API Key dedicada do Token Plan Team Edition. Para modelos disponíveis, consulte supported models referente ao Token Plan Team Edition.

{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
        "ANTHROPIC_BASE_URL": "https://token-plan.ap-southeast-1.maas.aliyuncs.com/apps/anthropic",
        "ANTHROPIC_MODEL": "qwen3.8-max",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen3.6-flash",
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen3.8-max",
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen3.8-max",
        "CLAUDE_CODE_SUBAGENT_MODEL": "qwen3.7-max",
        "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "983616"
    }
}

Coding Plan

Substitua YOUR_API_KEY pela API Key dedicada do Coding Plan. Para modelos disponíveis, consulte supported models referente ao Coding Plan.

{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
        "ANTHROPIC_BASE_URL": "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic",
        "ANTHROPIC_MODEL": "qwen3.7-plus",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen3.7-plus",
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen3.7-plus",
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen3.7-plus",
        "CLAUDE_CODE_SUBAGENT_MODEL": "qwen3.7-plus"
    }
}

Pay-as-you-go

Substitua YOUR_API_KEY pelo valor indicado em Alibaba Cloud Model Studio API Key. Para modelos disponíveis, consulte Anthropic-compatible API.

Defina ANTHROPIC_BASE_URL conforme a região. A API key deve corresponder à região selecionada:

• China North 2 (Beijing): https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic
• Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic. Substitua WorkspaceId pelo seu Get the Workspace ID real.

{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
        "ANTHROPIC_BASE_URL": "https://{WorkspaceId}.ap-southeast-1.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"
    }
}

Após salvar a configuração, abra um novo terminal e execute claude "hello". Uma resposta do modelo confirma que a configuração está funcionando. Para validar ainda mais, execute /status no Claude Code e verifique se ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN apontam para o endereço do Model Studio.

Configurar tamanho da janela de contexto

Por padrão, o Claude Code usa uma janela de contexto de 200K. Para lidar com bases de código extensas ou conversas longas, você pode expandir essa janela para 1M (1.000.000 tokens), desde que o modelo suporte esse comprimento de contexto. Há dois métodos de configuração:

Adicione CLAUDE_CODE_MAX_CONTEXT_TOKENS ao campo env no arquivo ~/.claude/settings.json:

{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
        "ANTHROPIC_BASE_URL": "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic",
        "ANTHROPIC_MODEL": "qwen3.7-plus",
        "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1000000"
    }
}

Acrescente [1m] ao nome do modelo. Essa abordagem funciona com modelos do Model Studio compatíveis com janela de contexto de 1M:

{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
        "ANTHROPIC_BASE_URL": "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic",
        "ANTHROPIC_MODEL": "qwen3.7-plus[1m]",
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen3.7-plus[1m]",
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen3.7-plus[1m]",
        "CLAUDE_CODE_SUBAGENT_MODEL": "qwen3.7-plus[1m]"
    }
}

Depois de modificar a configuração, abra uma nova janela de terminal para reiniciar o Claude Code e aplicar as alterações. Para mais detalhes sobre variáveis de ambiente, consulte a documentação oficial de variáveis de ambiente do Claude Code.

Modos de permissão

O Claude Code oferece seis modos de permissão que determinam se uma solicitação de confirmação aparece antes de uma ferramenta executar uma operação. A tabela a seguir descreve o comportamento de cada modo.

Flag de linha de comando

Use --permission-mode para definir o modo de permissão padrão de uma sessão:

claude --permission-mode plan
claude --permission-mode acceptEdits

Comando interativo

Insira /permissions durante uma sessão para gerenciar dinamicamente regras de pré-aprovação e pré-negação de ferramentas. É possível configurar regras de aprovação automática para as ferramentas bash, edit e MCP.

Configuração no settings.json

Configure o campo permissions no arquivo ~/.claude/settings.json (no Windows: C:\Users\<username>\.claude\settings.json), o mesmo arquivo de configuração que armazena suas credenciais de acesso:

{
    "permissions": {
        "allow": ["Bash(git:*)", "Read", "Edit"],
        "deny": ["Bash(rm:*)"],
        "defaultMode": "default"
    }
}

O campo allow aprova automaticamente chamadas de ferramentas correspondentes, enquanto o campo deny rejeita automaticamente as chamadas correspondentes. Ambos os campos aceitam curingas. Por exemplo, Bash(npm:*) corresponde a todos os comandos iniciados com npm. O campo defaultMode define o modo de permissão padrão da sessão e aceita qualquer um dos modos listados na tabela anterior.

Usar o CC Switch

O CC Switch é uma interface gráfica desktop open source da comunidade para gerenciar múltiplas API keys ou planos de faturamento. Alterne entre provedores com um clique, sem precisar editar manualmente o arquivo settings.json.

Instalar o CC Switch

• macOS: execute brew tap farion1231/ccswitch && brew install --cask cc-switch ou baixe o arquivo .dmg na página de Releases.
• Windows: baixe o instalador .msi ou a versão portátil .zip na página de Releases.
• Linux: no Arch, execute paru -S cc-switch-bin; nas demais distribuições, baixe os pacotes .deb / .rpm / .AppImage na página de Releases.

Adicionar um provedor

1. Na tela principal do CC Switch, selecione Claude Code na barra de ícones superior (ícone de estrela laranja) e clique em + no canto superior direito para abrir Add New Provider. Preencha os campos conforme a tabela abaixo e clique em Add.

   Billing plan	Configuration
   Token Plan Personal Edition	Provider name: Bailian-Token Plan Personal Edition API Key: get from console Endpoint: https://token-plan.ap-southeast-1.maas.aliyuncs.com/apps/anthropic
   Token Plan Team Edition	Provider name: Bailian-Token Plan Team Edition API Key: get from console Endpoint: https://token-plan.ap-southeast-1.maas.aliyuncs.com/apps/anthropic
   Coding Plan	Provider name: Bailian-Coding Plan API Key: get from console Endpoint: https://coding-intl.dashscope.aliyuncs.com/apps/anthropic
   Pay-as-you-go	Provider name: Bailian-Pay-as-you-go API Key: Model Studio API Key Endpoint: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic

2. Expanda Advanced Options para configurar o mapeamento de modelos. Defina o modelo principal e os modelos padrão Haiku, Sonnet e Opus conforme supported models do seu plano. Exemplo de mapeamento:

   • Modelo principal: qwen3.7-max (não suportado pelo Coding Plan)
   • Modelo padrão Haiku: qwen3.6-flash (não suportado pelo Coding Plan)
   • Modelo padrão Sonnet: qwen3.7-max (não suportado pelo Coding Plan)
   • Modelo padrão Opus: qwen3.7-max (não suportado pelo Coding Plan)

3. Retorne à tela principal, clique em Enable ao lado do provedor e inicie uma nova sessão do Claude Code para que a configuração tenha efeito.

Conectar o Claude Code Desktop

O Claude Code Desktop (Claude Desktop) e a CLI do Claude Code são dois pontos de entrada distintos, exibidos no CC Switch respectivamente nos painéis Claude Code e Claude Desktop. O aplicativo desktop acessa o Model Studio por meio do gateway local do CC Switch: o CC Switch grava automaticamente tanto o endereço do gateway quanto o token de autenticação na configuração do desktop, portanto não insira sua API Key do Model Studio no aplicativo desktop. A API Key do Model Studio deve ser informada apenas na configuração do provedor no CC Switch e é injetada automaticamente quando o roteador local encaminha a requisição.

1. Instale o Claude Code Desktop na página de download do Claude.
2. No CC Switch, alterne para o painel Claude Desktop pelo seletor de aplicativos à esquerda. Caso a opção não apareça, acesse Settings > General e verifique se o Claude Desktop não está oculto nas configurações de visibilidade de aplicativos.
3. Adicione o provedor Model Studio: se você já configurou um provedor Model Studio no painel Claude Code, clique em Import existing providers from Claude Code para reutilizá-lo; caso contrário, clique em + no canto superior direito para adicionar um novo. Como os IDs de modelos do Model Studio (como qwen3.7-max) não correspondem aos três IDs de função reconhecidos pelo Claude Desktop (claude-sonnet-* / claude-opus-* / claude-haiku-*), ative Needs model mapping e mapeie as funções Sonnet, Opus e Haiku para os modelos reais do Model Studio a serem requisitados (por exemplo, Sonnet > qwen3.7-max).
4. Ative o roteamento local: acesse Settings > Routing > Local Routing e ative Show Routing Toggle on Main Page; retorne ao painel Claude Desktop e ative a chave Claude Desktop local routing. O endereço de escuta padrão é 127.0.0.1:15721.
5. Clique em Enable no cartão do provedor. O CC Switch grava automaticamente a configuração de inferência de terceiros no Claude Code Desktop.
6. Mantenha o CC Switch em execução, encerre completamente e reinicie o Claude Code Desktop para aplicar as alterações. Selecione o modelo configurado no menu de modelos para começar a usá-lo.

Plugins do Claude Code para IDE

Após concluir a configuração da CLI acima, instale o plugin do Claude Code na sua IDE. O plugin reutiliza diretamente a configuração presente no arquivo settings.json.

VS Code

1. Pesquise por Claude Code for VS Code no marketplace de extensões e instale-a.
2. Reinicie o VS Code e clique no ícone no canto superior direito para abrir o Claude Code.
3. Digite / na caixa de diálogo, selecione General config e defina o modelo em Selected Model.

JetBrains

1. Pesquise por Claude Code no marketplace de extensões e instale-a.
2. Reinicie a IDE e clique no ícone no canto superior direito para começar a usar.

FAQ

Códigos de erro

Caso encontre erros durante a configuração, consulte a documentação de FAQ correspondente ao seu plano de faturamento:

• Pay-as-you-go: Anthropic API Compatible - Error Codes
• Coding Plan: Coding Plan FAQ
• Token Plan Personal Edition: Token Plan FAQ
• Token Plan Team Edition: Token Plan Team Edition FAQ

Requisições retornam 401 invalid_api_key

O tipo de API key não corresponde ao ANTHROPIC_BASE_URL. O Model Studio oferece três métodos de acesso, e cada um usa uma URL base diferente e uma API key dedicada.

Etapas de solução de problemas:

1. Verifique a URL da requisição. Confira o valor de ANTHROPIC_BASE_URL no arquivo ~/.claude/settings.json.
2. Confirme o tipo de API key. Use a tabela acima para confirmar se o tipo da sua API key corresponde à URL base.
3. Corrija a configuração. Ao usar uma API key Pay-as-you-go do Model Studio, defina ANTHROPIC_BASE_URL como https://dashscope.aliyuncs.com/apps/anthropic.

Após iniciar o Claude Code, a interface exibe "Unable to connect to Anthropic services. Failed to connect to api.anthropic.com: ERR_BAD_REQUEST"

O Claude Code está tentando se conectar ao service oficial da Anthropic em vez do Alibaba Cloud Model Studio. Isso geralmente indica que as variáveis de ambiente estão ausentes ou não entraram em vigor. Siga estas etapas:

1. Verifique a configuração. Execute o comando /status após iniciar o Claude Code. Confirme se ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN apontam para o endereço do Model Studio. Se a saída estiver vazia ou mostrar um endereço diferente do Model Studio, revise a configuração no arquivo settings.json.
2. Verifique hasCompletedOnboarding. Confirme se hasCompletedOnboarding está definido como true no arquivo ~/.claude.json. Sem isso, o Claude Code tenta se conectar ao service oficial da Anthropic para verificação de login na inicialização.
3. Abra um novo terminal. Após editar o arquivo de configuração, abra uma nova janela de terminal e execute claude para que as alterações tenham efeito.
4. Atualize o Claude Code. Se o problema persistir após todas as etapas acima, a versão do Claude Code pode estar desatualizada. Execute npm install -g @anthropic-ai/claude-code@latest para atualizar para a versão mais recente e tente novamente.

O CC Switch relata "No available model list endpoint found. Check the Base URL or confirm that the provider has opened the port" ao adicionar um provedor

Essa mensagem origina-se da verificação de conectividade que o CC Switch executa ao salvar um provedor: ele consulta um endpoint de lista de modelos (como /v1/models) na URL de requisição configurada. O endpoint compatível com Anthropic do Model Studio (terminado em /apps/anthropic) fornece apenas o endpoint de mensagens /v1/messages e não disponibiliza um endpoint de lista de modelos, fazendo com que a sondagem retorne 404 e o CC Switch relate "No available model list endpoint found".

Essa mensagem não afeta o uso normal do Claude Code e pode ser ignorada. O Claude Code envia conversas por meio de /v1/messages, e os modelos usados são especificados diretamente pelo mapeamento de modelos nas Advanced options do CC Switch, sem depender da descoberta automática por um endpoint de lista de modelos. Quando a URL de requisição e a API Key estiverem configuradas corretamente, basta clicar em Enable e iniciar uma nova sessão do Claude Code para conversar normalmente.

Se ainda assim não conseguir conversar, verifique se a URL de requisição termina com /apps/anthropic sem um /v1 adicional, e se você preencheu os modelos suportados pelo seu plano em model mapping under Advanced options.

O mapeamento de modelos no CC Switch retorna AccessDenied

Se as chamadas de modelo falharem no Claude Code com um erro AccessDenied (HTTP 403, código: access_denied) após configurar o mapeamento de modelos, verifique se o modelo está marcado como Upcoming deprecation no console do Model Studio > Model Gallery. Modelos marcados para descontinuação futura ainda aparecem na lista, mas as chamadas de API retornam 403 AccessDenied. Siga estas etapas:

1. Verifique se o modelo está marcado para descontinuação. No console do Model Studio > Model Gallery, pesquise o modelo em uso e verifique seu rótulo de status.
2. Mude para o modelo disponível mais recente. Substitua o modelo legado (como qwen-coder-turbo-0919) no mapeamento de modelos pelo modelo disponível mais recente (como qwen3-coder-plus).
3. Reconfigure o mapeamento de modelos e teste. Atualize o mapeamento de modelos em Advanced options no CC Switch, clique em Enable e inicie uma nova sessão do Claude Code para verificar.