Como usar Alibaba Cloud / Qwen

O que é

O Alibaba Cloud / Qwen é um provedor de IA que pode ser escolhido ao configurar um agente do Zé Bot. Ele oferece modelos Qwen no endpoint OpenAI compatível do Model Studio internacional e é acessado por um endpoint OpenAI compatível: https://dashscope-intl.aliyuncs.com/compatible-mode/v1.

Antes de começar

• Ter uma conta no Alibaba Cloud / Qwen.
• Criar uma chave de API no Alibaba Cloud Model Studio.
• Ter conexão com a internet; o Zé Bot não intermedeia a cobrança do provedor.

Como conectar

1. Abra um agente existente ou crie um novo.
2. No seletor de provedor e modelo, escolha Alibaba Cloud / Qwen.
3. Confira o Endpoint. O padrão é https://dashscope-intl.aliyuncs.com/compatible-mode/v1.
4. Cole a Chave de API no campo do agente. A chave fica no cofre seguro do sistema e não aparece no histórico.
5. Escolha o Modelo. O padrão é qwen3.8-max.
6. Envie uma tarefa curta para validar a conexão, como “Liste três ideias para organizar minha semana”.

Como escolher o modelo

O Zé Bot tenta consultar o catálogo https://dashscope-intl.aliyuncs.com/compatible-mode/v1/models com a chave do agente. Quando o provedor responde, o campo de modelo mostra os IDs disponíveis e também aceita um ID digitado. Quando o catálogo não responde, a lista de reserva traz qwen3.8-max, qwen3.7-plus, qwen3-coder-plus e qwen3.8-flash.

Os IDs de modelo são do provedor e podem mudar sem aviso. Se um modelo não existir mais, escolha outro no catálogo ou consulte a documentação oficial do Alibaba Cloud / Qwen.

Como criar um agente com Alibaba Cloud / Qwen

1. Em Agentes, crie um agente ou abra um existente.
2. Em Provedor, escolha Alibaba Cloud / Qwen.
3. Informe ou confirme o endpoint e a chave de API.
4. Escolha o modelo e, se o provedor oferecer, o nível de raciocínio.
5. Envie uma tarefa curta e confira a resposta antes de usar o agente em trabalho real.

Limites

• O Model Studio cobra por token e a disponibilidade dos modelos muda conforme a região da conta.
• O catálogo de modelos depende da conta e da região; alguns modelos podem não estar disponíveis para a sua chave.
• O runtime HTTP envia a conversa como Chat Completions e não encaminha ferramentas MCP. Para agentes que precisam usar ferramentas e arquivos do workspace, prefira Codex, Claude, OpenCode ou outro provedor ACP.
• O Zé Bot não controla cotas, limites de taxa nem preços do provedor. Consulte o painel do Alibaba Cloud / Qwen.

Problemas comuns

A chave é recusada com 401 ou 403

Confira se a chave foi copiada inteira, se pertence à conta certa e se tem permissão para o modelo escolhido. Chaves de plano de codificação podem não valer para a API padrão.

O catálogo de modelos não aparece

O Zé Bot mantém a lista de reserva e aceita o ID digitado. Se o provedor responder 404 ou 405 em /models, a conexão ainda pode funcionar; teste com uma tarefa curta.

A resposta demora ou retorna 429

O provedor aplicou limite de taxa ou a conta está sem cota. Aguarde, reduza a frequência ou ajuste o plano no painel do provedor.

O modelo não é encontrado

O ID pode ter sido descontinuado ou o modelo pode não estar liberado para a conta. Atualize o modelo no agente e consulte a documentação oficial.

Privacidade e segurança

A chave de API fica no cofre seguro do sistema operacional e não é enviada ao renderer. Ao executar uma tarefa, as instruções do agente e o prompt do turno são enviados ao endpoint do Alibaba Cloud / Qwen; o provedor processa esses dados conforme a política dele. Memórias, arquivos e ferramentas locais continuam no seu computador.

Próximos passos

• Leia o lançamento em /blog/qwen.
• Veja os outros manuais em /manual.