OpenBot não se conecta à APIYI? Com 3 variáveis de ambiente, seu colega de IA liga o computador sozinho

Nota do autor: o OpenBot não tem uma interface para “escolher o modelo”. O modelo fica configurado no .env e no model.yaml do pacote do tenant. Neste artigo, você vai ver como conectar o APIYI alterando três variáveis de ambiente e uma linha do YAML. Depois, vamos liberar apenas 3 ferramentas de computador e validar a configuração com um teste de “abrir uma página + ler um arquivo + consultar a auditoria”.

Você clonou o OpenBot do CopilotKit, abriu o .env.example e procurou por toda a interface, mas não encontrou um menu para “escolher o provedor de modelos”. Você não tem um cartão para usar a OpenAI diretamente e só quer usar o APIYI, com pagamento por uso, para acessar o claude-opus-5-5. O problema é que nem sabe onde configurar o modelo.

A resposta é simples: o OpenBot não tem uma opção para “escolher o modelo”. O modelo fica no .env e no model.yaml do pacote do tenant. Para conectar o APIYI, não é preciso alterar o código: basta mudar três variáveis de ambiente e uma linha do YAML. Depois, comece liberando apenas 3 ferramentas de computador e, quando a validação passar, libere outras conforme necessário.

Este não é um tutorial para fazer tudo funcionar com um clique. O OpenBot é um template e, para executá-lo, você precisa de Docker, Bun 1.4+, um projeto CopilotKit Intelligence e uma chave de modelo. Vamos explicar todos esses pré-requisitos. Além disso, existem dois projetos chamados OpenBot no GitHub; aqui, falamos do projeto do CopilotKit.

O que você vai aprender: ao final do artigo, você saberá ajustar as três configurações, começar com 3 ferramentas e fazer um teste de validação: “abrir uma página + ler um arquivo + consultar a auditoria”. Também terá uma tabela para diagnosticar problemas comuns, como erros 400 e 401, modelo inexistente, ferramentas que não são chamadas e inicialização recusada.

O modelo do OpenBot não é configurado na interface

OpenBot é um template, não um produto

CopilotKit/OpenBot é um repositório de código aberto sob licença MIT, criado em 2026-08-17. Em 2026-11-02, o repositório tinha 9.561 estrelas, a versão oficial mais recente era a v0.2.0 (2026-10-12) e o topo do README ainda indicava Beta. A proposta é dar a cada colega de IA, chamado de Bot no repositório, um computador próprio, com navegador real, sessão de login, arquivos e as ferramentas que lhe forem concedidas.

O README é direto: trata-se de “um template, não um produto”. Não há uma versão hospedada para criar uma conta, e ele também não é distribuído como pacote de dependência. A forma de usá-lo é clonar o repositório, substituir o pacote de exemplo em examples/ pelos seus próprios colegas, canais e habilidades e executar tudo por conta própria. Portanto, a resposta para “onde escolho o modelo?” está nos arquivos de configuração, não na interface.

Os quatro pré-requisitos para rodar o OpenBot

A tabela abaixo mostra o que você precisa preparar antes de conectar um modelo. Se faltar qualquer item, não será possível validar a configuração.

Pré-requisito	Requisitos	Observações
Docker	Executar o PostgreSQL (com pgvector) e o Bot integrado	`scripts/start.sh` inicia os serviços Docker e executa as migrações
Bun	Versão 1.4 ou superior	Use `bun install` para instalar as dependências
CopilotKit Intelligence	Um projeto e uma licença; há um plano gratuito	O ambiente de avaliação local usa macOS + Docker Desktop. A licença local vale por 30 dias e pode ser renovada com `npx copilotkit@latest local renew`
Chave do modelo	Uma chave para um endpoint compatível com OpenAI	Neste artigo, usamos um token da APIYI, com base_url `https://api.apiyi.com/v1`

O Intelligence é o item mais fácil de subestimar. Os comentários de .env.example deixam claro que, se faltarem a URL, a URL do gateway ou a chave do Intelligence, o servidor simplesmente não inicia. Nas palavras do arquivo: “Não há modo degradado”. Isso acontece porque as conversas persistentes e a memória ficam armazenadas nele; sem esse serviço, o contexto seria perdido a cada conversa. Por isso, o OpenBot não pode ser descrito como uma solução “totalmente offline”.

OPENAI_BASE_URL altera toda a implantação

O README diz que “nenhum modelo vem incluído”: o modelo não é distribuído com o pacote, e as credenciais são fornecidas pelo administrador, criptografadas e armazenadas no banco de dados, sem aparecer nos logs. O modelo é definido por variáveis de ambiente no nível da implantação. A mais importante delas é OPENAI_BASE_URL, que, segundo a documentação oficial, pode apontar para qualquer endpoint compatível com a mesma API, incluindo gateways de múltiplos fornecedores, proxies ou modelos executados no seu próprio hardware. Os comentários de .env.example são ainda mais específicos: qualquer endpoint com suporte a /v1/chat/completions serve.

Essa variável vale para toda a implantação, não para um Bot específico. Ela é lida em três pontos: pelo cliente que o servidor de API usa para o agente integrado, pelo agent-bot, que constrói seu próprio cliente, e pelo agent-langgraph com BOT_PROVIDER=openai. Segundo a documentação oficial, a vantagem é evitar que, em uma mesma implantação, metade das solicitações vá para o novo endereço enquanto a outra metade continue usando o endereço antigo.

Conecte o OpenBot à APIYI com três alterações: configuração das variáveis de ambiente

Como o OpenBot se conecta à APIYI

A APIYI oferece uma interface compatível com a OpenAI. Defina base_url como https://api.apiyi.com/v1 e as requisições serão enviadas para /v1/chat/completions, atendendo ao requisito do OpenBot para OPENAI_BASE_URL. Outro detalhe importante: o OpenBot transmite o nome do modelo exatamente como foi informado. Como /v1/models da APIYI retorna o nome sem prefixo, claude-opus-5-5, não adicione openai/ seguindo o exemplo do gateway oficial. O exemplo oficial openai/gpt-5.6-terra só se aplica a endpoints que usam um namespace no nome do modelo.

Confira primeiro a tabela geral e depois siga os passos.

Onde alterar	Novo valor	Por quê
`OPENAI_API_KEY` no `.env`	O token `sk-...` criado no console da APIYI	O agente integrado e os dois Bots incluídos usam essa chave por padrão
`OPENAI_BASE_URL` no `.env`	`https://api.apiyi.com/v1`	Direciona as requisições aos modelos de toda a implantação para o endpoint compatível da APIYI
`BOT_MODEL` no `.env`	`claude-opus-5-5`	Define qual modelo o Bot em inicialização usará; se ficar vazio, será usado o valor do arquivo de especificação do provedor
`default_model` em `examples/<seu-pacote>/model.yaml`	`claude-opus-5-5`	O pacote de exemplo usa atualmente `gpt-5.6-terra`; sem a alteração, ocorrerá um erro de modelo inexistente
`BOT_RESPONSES_API` no `.env`	Manter `false`	O Claude retorna erro 400 no endpoint Responses da APIYI

Primeiro passo: crie um token dedicado

Na página de tokens da APIYI, api.apiyi.com/token, crie uma nova chave, defina um limite de saldo e uma data de validade e informe a finalidade como “Avaliação local do OpenBot”.
Na sua máquina, faça uma chamada com curl para GET https://api.apiyi.com/v1/models, usando o cabeçalho Authorization: Bearer sk-....

Critério de aceitação: a resposta deve retornar HTTP 200, e claude-opus-5-5 deve aparecer na lista. Testamos essa etapa em 02/11/2026 e recebemos 259 modelos, incluindo claude-opus-5-5 e claude-opus-5-5-thinking.

Criar um token separado ajuda a manter o uso dessa máquina isolado do uso em produção. Durante a fase de testes do template, o Bot fará várias tentativas, e o limite de saldo serve como proteção.

Segundo passo: altere três linhas no .env

Seguindo o guia oficial de início rápido, execute primeiro cp .env.example .env e bun install. Depois, execute, nesta ordem, npx --yes copilotkit@latest login, npx --yes copilotkit@latest project select e bun scripts/setup-learning.ts para registrar a chave de runtime e o contêiner Learning no .env. Em seguida, altere estas três linhas:

OPENAI_API_KEY=sk-seu-token-APIYI
OPENAI_BASE_URL=https://api.apiyi.com/v1
BOT_MODEL=claude-opus-5-5

Confira também quatro itens: mantenha BOT_PROVIDER no valor padrão openai; mantenha BOT_RESPONSES_API como false; gere KEY_ENCRYPTION_KEY com openssl rand -base64 32; e lembre-se de que AGENT_BOT_MODEL é usado apenas pelo agent-bot de prova de conceito. Seu valor padrão é gpt-5.5, independente de BOT_MODEL. Se você também quiser iniciar o agent-bot, confirme em /v1/models se esse nome está disponível ou altere-o para o modelo que deseja usar.

Critério de aceitação: a saída de grep OPENAI_ .env deve mostrar a chave e o endereço corretos. O endereço deve terminar em /v1, sem barras ou espaços extras. Se o contêiner precisar de uma rota diferente para acessar o mesmo endpoint, use OPENAI_CONTAINER_BASE_URL para sobrescrever o endereço. Como a APIYI tem um endereço público, normalmente essa variável não é necessária.

Terceiro passo: altere uma linha do model.yaml no pacote do tenant

Abra examples/fintech/model.yaml ou a cópia do pacote do tenant. O conteúdo atual é model.provider: openai, model.credential_secret_ref: openai-api-key e model.default_model: gpt-5.6-terra.

Altere default_model para claude-opus-5-5.
Mantenha provider como openai. A documentação oficial aceita apenas openai ou anthropic nesse campo. Para usar o endpoint compatível com OpenAI da APIYI, escolha openai.
Não substitua credential_secret_ref por uma chave em texto puro: esse campo faz referência às credenciais já armazenadas.

Critério de aceitação: depois de executar bash scripts/start.sh, todas as verificações de integridade passam e, ao abrir http://localhost:3010, você vê os dois colegas padrão, General Assistant e Knowledge.

Há um detalhe importante. Na inicialização, o servidor normalmente consulta a OpenAI ou a Anthropic para verificar se a chave pode acessar o default_model. Se não puder, ele exibe model-unavailable ou model-credential-rejected. Mas essa verificação é ignorada quando OPENAI_BASE_URL está definido. Portanto, ao usar a APIYI, um erro no nome do modelo não será detectado na inicialização: ele só aparecerá quando você enviar a primeira mensagem. Uma inicialização bem-sucedida indica apenas que o serviço está funcionando, não que o modelo esteja configurado corretamente.

Sobre as versões: diferenças entre v0.2.0 e a branch main

Vale deixar essa diferença bem clara. Na seção Unreleased do CHANGELOG da branch main, há uma mudança para os modelos openai/... do Bot integrado: quando o OPENAI_BASE_URL aponta para um endpoint que não é da OpenAI nem do Azure, eles passam a chamar /chat/completions nesse endpoint, em vez da Responses API. Segundo a explicação oficial, a maioria dos endpoints compatíveis com OpenAI oferece apenas Chat Completions. A mesma mudança também adiciona COPILOTKIT_OPENAI_API=responses|chat, permitindo forçar uma das duas opções.

Essa mudança ainda não entrou na tag oficial v0.2.0. Se você fizer checkout da v0.2.0, o Bot integrado ainda poderá chamar a Responses API ao usar uma base URL de terceiros. Considerando os testes que fizemos abaixo, essa é uma possível origem do erro 400. Há duas formas de lidar com isso: avaliar a integração com base na branch main, sabendo que ela ainda está em desenvolvimento, ou esperar que a mudança seja incluída em uma versão oficial antes de integrar.

🚀 Começo rápido: antes de mexer no OpenBot, recomendamos testar /v1/chat/completions separadamente com um token da APIYI apiyi.com. Inclua uma definição de função e confirme que finish_reason retorna tool_calls. Depois de verificar que a API está funcionando, você só precisa conferir a configuração do OpenBot ao investigar problemas.

Comece liberando apenas 3 ferramentas: limites iniciais do OpenBot

Por que não liberar tudo no OpenBot desde o início

A documentação oficial resume a questão assim: “Um modelo escolhe a ferramenta certa com confiabilidade entre cerca de dez opções, mas não entre trinta.” O código-fonte do OpenBot registra treze ferramentas de computador. Somando as ferramentas do catálogo MCP, é fácil ultrapassar esse limite já no primeiro dia.

Quando um Bot tem mais de doze ferramentas, cada execução recebe apenas as ferramentas necessárias para a skill correspondente à mensagem atual. Mas a documentação ressalta que isso apenas reduz o que fica visível: “Não é uma barreira de segurança e nunca a substitui”. Os limites reais são três: as permissões concedidas a cada Bot no Admin, a política de ações AGENT_COMPUTER_POLICY e os registros de auditoria. Outro detalhe importante: a configuração padrão de inicialização usa deny: [] e allow: ["true"], ou seja, libera tudo.

As 3 ferramentas para começar

Nome da ferramenta	Função	Na fase inicial
`computer_navigate`	Abrir um endereço no navegador	✅ Liberar
`computer_snapshot`	Obter um snapshot da página	✅ Liberar
`computer_read_file`	Ler arquivos do espaço de trabalho	✅ Liberar
`computer_click` / `computer_type` / `computer_key`	Clicar, digitar e pressionar teclas	⏸ Liberar conforme necessário após a validação
`computer_write_file`	Gravar arquivos	⏸ Liberar conforme necessário após a validação
`computer_run_command`	Executar comandos shell	⛔ Bloquear explicitamente

É importante bloquear computer_run_command separadamente. Ao ativar COMPUTER_SEPARATE_WORKSPACES no Compose, cada Bot inicia um shell na própria pasta, mas a documentação reconhece que “os comandos ainda podem ler outras pastas”. Para ter isolamento de verdade, é necessário usar computers.mode: sandbox. Na fase inicial, não vale a pena assumir esse risco.

Escrevendo a AGENT_COMPUTER_POLICY

A política é um JSON com regras em expressões CEL, que podem acessar campos como tool.name, page.host e file.path. Para começar, faça assim:

Adicione uma linha ao .env: AGENT_COMPUTER_POLICY={"mode":"enforce","deny":["tool.name == 'computer_run_command'"],"allow":["tool.name in ['computer_navigate','computer_snapshot','computer_read_file']"]}
No Admin, conceda ao General Assistant acesso apenas a essas três ferramentas.
Reinicie o serviço. Se o JSON estiver malformado, o servidor não vai iniciar, o que ajuda a identificar o problema.

Há duas regras de avaliação importantes. Primeiro, deny vem antes de allow. Então, mesmo que você amplie o allow no futuro, o shell continuará bloqueado. Segundo, o mecanismo falha de forma segura: se a política estiver ausente ou vazia, nada é permitido; uma regra deny malformada é tratada como rejeição; e uma regra allow malformada não libera o acesso. O princípio é simples: comece com acesso restrito e libere aos poucos, conforme necessário. Depois da validação, adicione clique, digitação ou gravação de arquivos um por vez e confira a auditoria a cada mudança.

Validação e solução de problemas da integração do OpenBot com a APIYI

Um teste de validação: abrir uma página, ler um arquivo e conferir a auditoria

Segundo a arquitetura oficial, uma chamada de ferramenta segue esta ordem: identifica o alvo, avalia a ação conforme a política atual, grava uma linha de auditoria e só então acessa o computador. Se a ação encaminhada falhar, uma segunda linha de auditoria é gravada. O computador em si não toma decisões de política: esse controle fica no gateway do servidor. Por isso, a validação precisa cobrir tanto a execução quanto o registro das ações:

Crie um arquivo notes.md em /workspace e escreva duas linhas quaisquer.
Peça ao General Assistant para abrir uma página pública, informar o título e depois ler o conteúdo de /workspace/notes.md.
Em seguida, peça para executar ls /. A solicitação deve ser recusada, e a resposta deve informar qual regra a bloqueou.
Abra a página Audit e confira os registros de autorização de navigate, snapshot e read_file, além do registro de recusa de run_command. Para exportar os dados, chame GET /api/admin/audit-events?format=csv. Cada exportação tem limite de 5.000 linhas.

Quanto à disponibilidade do modelo, fizemos testes práticos apenas pela APIYI. Em 2026-11-02, chamamos /v1/chat/completions com claude-opus-5-5 e uma definição da função read_file. A resposta retornou HTTP 200 em 4,06 segundos, com finish_reason igual a tool_calls e os parâmetros {"path":"/workspace/notes.md"}. O uso foi de 393 tokens de prompt e 55 tokens de completion. Ao adicionar stream: true, a resposta também retornou 200. Nos blocos SSE, foi possível ver a saída incremental do nome da função e dos parâmetros, encerrada por data: [DONE]. Isso mostra que o endpoint de chat da APIYI consegue retornar as chamadas de ferramentas do Claude no formato OpenAI — exatamente o que um agente precisa quando o modelo apenas decide qual função chamar, sem executá-la.

Tabela de diagnóstico: cinco erros comuns

Sintoma	Causa mais provável	Como resolver
400 `field messages is required`	A requisição chegou ao endpoint Responses. Em nossos testes, `claude-opus-5-5` retorna esse erro ao acessar `/v1/responses` da APIYI	Confirme que `BOT_RESPONSES_API=false`. Se estiver usando a v0.2.0, o Bot integrado ainda pode estar chamando Responses. Nesse caso, use a branch main e configure `COPILOTKIT_OPENAI_API=chat` (ainda não lançado)
401	A chave está incorreta ou expirou, ou o limite de saldo do token foi atingido	Volte à página de tokens da APIYI, confira a validade e o saldo e teste novamente `/v1/models` com curl
Modelo não existe	`default_model` ainda está definido como `gpt-5.6-terra`, ou o nome recebeu o prefixo `openai/`	Nos dois campos, use apenas o nome `claude-opus-5-5`. Como a verificação de inicialização foi ignorada, é preciso enviar uma mensagem para validar
Ferramenta não foi chamada	O modelo não oferece suporte à chamada de ferramentas, a permissão não foi concedida ou uma política bloqueou a ferramenta	Segundo a documentação oficial, um Bot sem chamada de ferramentas não consegue controlar o computador. Primeiro, procure registros de rejeição na auditoria
Inicialização recusada	Falta a configuração de Intelligence, o JSON da política está incorreto ou um fornecedor foi adicionado ao provider spec sem atualizar `PROVIDER_IDS`	Preencha os três itens de Intelligence e valide o JSON. Para conectar a APIYI, não é necessário adicionar um fornecedor: mantenha `openai`

💡 Dica de diagnóstico: quando ocorrer um erro, envie primeiro a mesma requisição diretamente para /v1/chat/completions da APIYI, em apiyi.com. Se a chamada direta funcionar, mas falhar no OpenBot, o problema está na configuração ou na versão do OpenBot. Se a chamada direta também falhar, verifique o token e o modelo. Assim, você já reduz pela metade o campo de investigação.

Referência de custos para usar Claude no OpenBot

A APIYI cobra conforme o uso, sem mensalidade fixa. Os preços consultados em 02/11/2026 para claude-opus-5-5 estão abaixo; claude-opus-5-5-thinking tem o mesmo preço:

Item de cobrança	Preço (por milhão de tokens)
Entrada	$4
Saída	$20
Leitura de cache	$0.2

Consulte a lista de modelos da plataforma para conferir os modelos e preços atuais. Na requisição com ferramentas que testamos, foram 393 tokens de entrada e 55 de saída, com um custo muito baixo por chamada. Mas, quando o bot começa a navegar e ler arquivos em várias rodadas, o contexto cresce rapidamente. Por isso, recomendamos definir um limite de saldo para o token.

Perguntas frequentes

Q1: Preciso alterar o código-fonte para conectar o OpenBot à APIYI?

Não. Basta alterar as três linhas `OPENAI_API_KEY`, `OPENAI_BASE_URL` e `BOT_MODEL` no `.env` e mudar o `default_model` no `model.yaml` do pacote do tenant. Só é necessário alterar o provider spec e `PROVIDER_IDS` ao adicionar um tipo de fornecedor totalmente novo. A APIYI usa uma interface compatível com a OpenAI, então esse não é o caso.

Q2: Por que não usar um nome com prefixo, como openai/claude-opus-5-5?

O OpenBot envia o nome do modelo exatamente como ele foi informado, então use o formato publicado pelo próprio endpoint. O `/v1/models` da APIYI apiyi.com lista o nome sem prefixo, `claude-opus-5-5`. Se você adicionar o prefixo, o modelo não será encontrado.

Q3: Posso ativar BOT_RESPONSES_API para usar a Responses API?

Ao conectar o Claude, não ative essa opção. Nos nossos testes, a chamada de `claude-opus-5-5` ao `/v1/responses` da APIYI retornou 400 `field messages is required`, enquanto `gpt-5.4-mini` retornou 200. A documentação oficial também recomenda ativar essa opção apenas quando o endpoint realmente implementar a Responses API.

Q4: Vocês colocaram todo o OpenBot para funcionar?

Não. Validamos apenas o lado da APIYI: a lista de modelos, a chamada de chat com ferramentas, a saída em streaming e o erro no endpoint Responses. Não executamos o OpenBot completo (Docker mais o projeto Intelligence) na máquina usada para escrever o artigo. As informações sobre o funcionamento interno do OpenBot foram tiradas do repositório e da documentação oficiais.

Q5: Como evitar que o bot gaste demais com uma chave cobrada conforme o uso?

Na página de tokens da APIYI apiyi.com, defina um limite de saldo e uma data de validade para essa chave e gerencie-a separadamente das chaves de produção. Combine isso com a estratégia de três ferramentas apresentada neste artigo para limitar tanto o que o bot pode fazer quanto o que ele pode gastar.

Resumo

Pontos principais para conectar o OpenBot à APIYI

O modelo não fica na interface: a configuração está em três linhas do .env e uma linha do model.yaml no pacote do tenant.
O base_url vale para toda a implantação: ao alterar OPENAI_BASE_URL, os três tipos de bot mudam juntos.
Iniciar com sucesso não garante que o modelo esteja correto: ao conectar o gateway, a verificação é ignorada. É preciso enviar a primeira mensagem para validar.
Confira a versão: a mudança para chamar /chat/completions ainda está em Unreleased na branch main e não entrou na v0.2.0.
Comece com apenas 3 ferramentas: deny tem precedência sobre allow, e o shell deve ser negado separadamente. Comece com restrições e libere o acesso aos poucos.
Comece com a cobrança por uso da APIYI: use um token dedicado com limite de saldo e informe claude-opus-5-5 sem prefixo.

A configuração do modelo no OpenBot é difícil de encontrar porque ela simplesmente não fica na interface. Ajuste os três pontos: as três linhas do .env, uma linha do model.yaml e mantenha Responses desativado. Depois, comece com uma política que permita apenas 3 ferramentas. Assim, fica mais fácil entender todo o fluxo. Na validação, confira apenas três coisas: se a página abre, se os arquivos podem ser lidos e se as ações negadas aparecem no registro de auditoria.

A recomendação é usar primeiro um token dedicado da APIYI em apiyi.com para testar o chat e a chamada de ferramentas separadamente. Depois, conecte ao OpenBot. Assim, se algo der errado, fica mais fácil identificar de que lado está o problema.

📚 Referências

Repositório CopilotKit/OpenBot: README, requisitos e início rápido
Link: github.com/CopilotKit/OpenBot
Descrição: proposta do template, pré-requisitos e informações da versão v0.2.0
Documentação de configuração do OpenBot: variáveis de ambiente do modelo, model.yaml e validação na inicialização
Link: github.com/CopilotKit/OpenBot/blob/main/docs/configuration.md
Descrição: definições originais de OPENAI_BASE_URL, BOT_MODEL e BOT_RESPONSES_API
Documentação de arquitetura do OpenBot: gateway, políticas e auditoria
Link: github.com/CopilotKit/OpenBot/blob/main/docs/architecture.md
Descrição: ordem de chamada das ferramentas e interface de exportação de auditoria
Central de documentação da APIYI: modo compatível com OpenAI, chamadas de função e lista de modelos
Link: docs.apiyi.com
Descrição: formato de base_url, formato de tools e preço do claude-opus-5-5

Autor: Equipe técnica da APIYI
Troca de experiências técnicas: Entre em contato conosco pelo site oficial da APIYI, apiyi.com. Para mais informações sobre integração, acesse a central de documentação em docs.apiyi.com

OpenBot não se conecta à APIYI? Com 3 variáveis de ambiente, seu colega de IA liga o computador sozinho