picoclaw/docs/guides/providers.pt-br.md

🔌 Provedores e Configuração de Modelos

Voltar ao README

Provedores

Note

O Groq fornece transcrição de voz gratuita via Whisper. Se configurado, mensagens de áudio de qualquer canal serão automaticamente transcritas no nível do agente.

Provider	Purpose	Get API Key
gemini	LLM (Gemini direct)	aistudio.google.com
zhipu	LLM (Zhipu direct)	bigmodel.cn
volcengine	LLM(Volcengine direct)	volcengine.com
openrouter	LLM (recommended, access to all models)	openrouter.ai
anthropic	LLM (Claude direct)	console.anthropic.com
openai	LLM (GPT direct)	platform.openai.com
deepseek	LLM (DeepSeek direct)	platform.deepseek.com
qwen	LLM (Qwen direct)	dashscope.console.aliyun.com
groq	LLM + Voice transcription (Whisper)	console.groq.com
cerebras	LLM (Cerebras direct)	cerebras.ai
vivgrid	LLM (Vivgrid direct)	vivgrid.com
moonshot	LLM (Kimi/Moonshot direct)	platform.moonshot.cn
minimax	LLM (Minimax direct)	platform.minimaxi.com
avian	LLM (Avian direct)	avian.io
mistral	LLM (Mistral direct)	console.mistral.ai
longcat	LLM (Longcat direct)	longcat.ai
modelscope	LLM (ModelScope direct)	modelscope.cn

Configuração de Modelos (model_list)

Novidade? O PicoClaw agora usa uma abordagem de configuração centrada no modelo. Basta especificar o formato vendor/model (ex.: zhipu/glm-4.7) para adicionar novos provedores — sem necessidade de alteração de código!

Este design também permite suporte multi-agente com seleção flexível de provedores:

• Agentes diferentes, provedores diferentes: Cada agente pode usar seu próprio provedor LLM
• Fallback de modelos: Configure modelos primários e de fallback para resiliência
• Balanceamento de carga: Distribua requisições entre múltiplos endpoints
• Configuração centralizada: Gerencie todos os provedores em um só lugar

📋 Todos os Vendors Suportados

Vendor	model Prefix	Default API Base	Protocol	API Key
OpenAI	openai/	https://api.openai.com/v1	OpenAI	Get Key
Anthropic	anthropic/	https://api.anthropic.com/v1	Anthropic	Get Key
智谱 AI (GLM)	zhipu/	https://open.bigmodel.cn/api/paas/v4	OpenAI	Get Key
DeepSeek	deepseek/	https://api.deepseek.com/v1	OpenAI	Get Key
Google Gemini	gemini/	https://generativelanguage.googleapis.com/v1beta	Gemini	Get Key
Groq	groq/	https://api.groq.com/openai/v1	OpenAI	Get Key
Moonshot	moonshot/	https://api.moonshot.cn/v1	OpenAI	Get Key
通义千问 (Qwen)	qwen/	https://dashscope.aliyuncs.com/compatible-mode/v1	OpenAI	Get Key
NVIDIA	nvidia/	https://integrate.api.nvidia.com/v1	OpenAI	Get Key
Ollama	ollama/	http://localhost:11434/v1	OpenAI	Local (no key needed)
OpenRouter	openrouter/	https://openrouter.ai/api/v1	OpenAI	Get Key
LiteLLM Proxy	litellm/	http://localhost:4000/v1	OpenAI	Your LiteLLM proxy key
VLLM	vllm/	http://localhost:8000/v1	OpenAI	Local
Cerebras	cerebras/	https://api.cerebras.ai/v1	OpenAI	Get Key
VolcEngine (Doubao)	volcengine/	https://ark.cn-beijing.volces.com/api/v3	OpenAI	Get Key
神算云	shengsuanyun/	https://router.shengsuanyun.com/api/v1	OpenAI	-
BytePlus	byteplus/	https://ark.ap-southeast.bytepluses.com/api/v3	OpenAI	Get Key
Vivgrid	vivgrid/	https://api.vivgrid.com/v1	OpenAI	Get Key
LongCat	longcat/	https://api.longcat.chat/openai	OpenAI	Get Key
ModelScope (魔搭)	modelscope/	https://api-inference.modelscope.cn/v1	OpenAI	Get Token
Antigravity	antigravity/	Google Cloud	Custom	OAuth only
GitHub Copilot	github-copilot/	localhost:4321	gRPC	-

Configuração Básica

{
  "model_list": [
    {
      "model_name": "ark-code-latest",
      "model": "volcengine/ark-code-latest",
      "api_keys": ["sk-your-api-key"]
    },
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_keys": ["sk-your-openai-key"]
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_keys": ["sk-ant-your-key"]
    },
    {
      "model_name": "glm-4.7",
      "model": "zhipu/glm-4.7",
      "api_keys": ["your-zhipu-key"]
    }
  ],
  "agents": {
    "defaults": {
      "model_name": "gpt-5.4"
    }
  }
}

Campos de entrada model_list

Campo	Tipo	Obrigatório	Descrição
model_name	string	Sim	Nome único para referenciar este modelo na config do agent
model	string	Sim	Identificador fornecedor/modelo (ex: openai/gpt-5.4, azure/gpt-5.4, anthropic/claude-sonnet-4.6)
api_keys	string[]	Sim*	Chave(s) API para autenticação. Múltiplas chaves permitem rotação por requisição. Não necessário para providers locais (Ollama, LM Studio, VLLM)
api_base	string	Não	Substitui a URL base da API padrão
proxy	string	Não	URL do proxy HTTP para esta entrada de modelo
user_agent	string	Não	Cabeçalho User-Agent personalizado enviado com requisições API (suportado por providers OpenAI-compatible, Gemini, Anthropic e Azure)
request_timeout	int	Não	Timeout de requisição em segundos (o padrão varia por provider)
max_tokens_field	string	Não	Substitui o nome do campo max tokens no corpo da requisição (ex: max_completion_tokens para modelos o1)
thinking_level	string	Não	Nível de pensamento estendido: off, low, medium, high, xhigh ou adaptive
extra_body	object	Não	Campos adicionais para injetar em cada corpo de requisição
streaming.enabled	bool	Não	Opt-in para provider streaming nesta entrada de modelo. O padrão é false e o canal ativo também precisa de settings.streaming.enabled como true
rpm	int	Não	Limite de requisições por minuto
fallbacks	string[]	Não	Nomes dos modelos de fallback para failover automático
enabled	bool	Não	Ativar ou desativar esta entrada de modelo (padrão: true)

Quando streaming estiver desativado, omita o bloco streaming. Escrever "streaming": {"enabled": false} é opcional e não é necessário.

Exemplos por Vendor

OpenAI

{
  "model_name": "gpt-5.4",
  "model": "openai/gpt-5.4",
  "api_keys": ["sk-..."]
}

VolcEngine (Doubao)

{
  "model_name": "ark-code-latest",
  "model": "volcengine/ark-code-latest",
  "api_keys": ["sk-..."]
}

智谱 AI (GLM)

{
  "model_name": "glm-4.7",
  "model": "zhipu/glm-4.7",
  "api_keys": ["your-key"]
}

DeepSeek

{
  "model_name": "deepseek-chat",
  "model": "deepseek/deepseek-chat",
  "api_keys": ["sk-..."]
}

Anthropic (com chave de API)

{
  "model_name": "claude-sonnet-4.6",
  "model": "anthropic/claude-sonnet-4.6",
  "api_keys": ["sk-ant-your-key"]
}

Execute picoclaw auth login --provider anthropic para colar seu token de API.

Anthropic Messages API (formato nativo)

Para acesso direto à API Anthropic ou endpoints personalizados que suportam apenas o formato de mensagem nativo da Anthropic:

{
  "model_name": "claude-opus-4-6",
  "model": "anthropic-messages/claude-opus-4-6",
  "api_keys": ["sk-ant-your-key"],
  "api_base": "https://api.anthropic.com"
}

Use o protocolo anthropic-messages quando:

• Usar proxies de terceiros que suportam apenas o endpoint nativo /v1/messages da Anthropic (não o compatível com OpenAI /v1/chat/completions)
• Conectar a serviços como MiniMax, Synthetic que requerem o formato de mensagem nativo da Anthropic
• O protocolo anthropic existente retorna erros 404 (indicando que o endpoint não suporta formato compatível com OpenAI)

Nota: O protocolo anthropic usa formato compatível com OpenAI (/v1/chat/completions), enquanto anthropic-messages usa o formato nativo da Anthropic (/v1/messages). Escolha com base no formato suportado pelo seu endpoint.

Ollama (local)

{
  "model_name": "llama3",
  "model": "ollama/llama3"
}

Proxy/API Personalizado

{
  "model_name": "my-custom-model",
  "model": "openai/custom-model",
  "api_base": "https://my-proxy.com/v1",
  "api_keys": ["sk-..."],
  "user_agent": "MyApp/1.0",
  "request_timeout": 300
}

LiteLLM Proxy

{
  "model_name": "lite-gpt4",
  "model": "litellm/lite-gpt4",
  "api_base": "http://localhost:4000/v1",
  "api_keys": ["sk-..."]
}

O PicoClaw remove apenas o prefixo externo litellm/ antes de enviar a requisição, então aliases de proxy como litellm/lite-gpt4 enviam lite-gpt4, enquanto litellm/openai/gpt-4o envia openai/gpt-4o.

Balanceamento de Carga

Configure múltiplos endpoints para o mesmo nome de modelo — o PicoClaw fará automaticamente round-robin entre eles:

{
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_base": "https://api1.example.com/v1",
      "api_keys": ["sk-key1"]
    },
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_base": "https://api2.example.com/v1",
      "api_keys": ["sk-key2"]
    }
  ]
}

Migração da Configuração Legacy providers

A configuração antiga providers está descontinuada e foi removida no V2. Configs V0/V1 existentes são auto-migradas.

Configuração Antiga (descontinuada):

{
  "providers": {
    "zhipu": {
      "api_key": "your-key",
      "api_base": "https://open.bigmodel.cn/api/paas/v4"
    }
  },
  "agents": {
    "defaults": {
      "provider": "zhipu",
      "model": "glm-4.7"
    }
  }
}

Configuração Nova (recomendada):

{
  "version": 3,
  "model_list": [
    {
      "model_name": "glm-4.7",
      "model": "zhipu/glm-4.7",
      "api_keys": ["your-key"]
    }
  ],
  "agents": {
    "defaults": {
      "model_name": "glm-4.7"
    }
  }
}

Para guia de migração detalhado, veja migration/model-list-migration.md.

Arquitetura de Provedores

O PicoClaw roteia provedores por família de protocolo:

• Protocolo compatível com OpenAI: OpenRouter, gateways compatíveis com OpenAI, Groq, Zhipu e endpoints estilo vLLM.
• Protocolo Gemini nativo: Google Gemini via endpoints nativos models/*:generateContent e models/*:streamGenerateContent.
• Protocolo Anthropic: Comportamento nativo da API Claude.
• Caminho Codex/OAuth: Rota de autenticação OAuth/token da OpenAI.

Isso mantém o runtime leve enquanto torna novos backends compatíveis com OpenAI basicamente uma operação de configuração (api_base + api_keys).

Zhipu

1. Obter chave de API e URL base

• Obtenha a chave de API

2. Configurar

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "glm-4.7",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "providers": {
    "zhipu": {
      "api_key": "Your API Key",
      "api_base": "https://open.bigmodel.cn/api/paas/v4"
    }
  }
}

3. Executar

picoclaw agent -m "Hello"

Exemplo de configuração completa

{
  "agents": {
    "defaults": {
      "model_name": "anthropic/claude-opus-4-5"
    }
  },
  "session": {
    "dm_scope": "per-channel-peer"
  },
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-xxx"
    },
    "groq": {
      "api_key": "gsk_xxx"
    }
  },
  "channel_list": {
    "telegram": {
      "enabled": true,
      "type": "telegram",
      "token": "123456:ABC...",
      "allow_from": ["123456789"]
    },
    "discord": {
      "enabled": true,
      "type": "discord",
      "token": "",
      "allow_from": [""]
    },
    "whatsapp": {
      "enabled": false,
      "type": "whatsapp",
      "bridge_url": "ws://localhost:3001",
      "use_native": false,
      "session_store_path": "",
      "allow_from": []
    },
    "feishu": {
      "enabled": false,
      "type": "feishu",
      "app_id": "cli_xxx",
      "app_secret": "xxx",
      "encrypt_key": "",
      "verification_token": "",
      "allow_from": []
    },
    "qq": {
      "enabled": false,
      "type": "qq",
      "app_id": "",
      "app_secret": "",
      "allow_from": []
    }
  },
  "tools": {
    "web": {
      "brave": {
        "enabled": false,
        "api_key": "BSA...",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      },
      "perplexity": {
        "enabled": false,
        "api_key": "",
        "max_results": 5
      },
      "searxng": {
        "enabled": false,
        "base_url": "http://localhost:8888",
        "max_results": 5
      }
    },
    "cron": {
      "exec_timeout_minutes": 5
    }
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

---

📝 Comparação de Chaves de API

Service	Pricing	Use Case
OpenRouter	Free: 200K tokens/month	Multiple models (Claude, GPT-4, etc.)
Volcengine CodingPlan	¥9.9/first month	Best for Chinese users, multiple SOTA models (Doubao, DeepSeek, etc.)
Zhipu	Free: 200K tokens/month	Suitable for Chinese users
Brave Search	$5/1000 queries	Web search functionality
SearXNG	Free (self-hosted)	Privacy-focused metasearch (70+ engines)
Groq	Free tier available	Fast inference (Llama, Mixtral)
Cerebras	Free tier available	Fast inference (Llama, Qwen, etc.)
LongCat	Free: up to 5M tokens/day	Fast inference
ModelScope	Free: 2000 requests/day	Inference (Qwen, GLM, DeepSeek, etc.)

---