Guia do OpenRouter Shell Tool e da Files API (Beta)

O fluxo de shell do OpenRouter é útil quando um modelo precisa ler um arquivo, executar código, investigar um erro e devolver um artefato pronto. Mas há um ponto importante: openrouter:shell, os contêineres e a Files API ainda estão em beta. Por isso, comece com uma tarefa bem delimitada, não com uma etapa crítica de produção.

Em resumo: quando vale a pena usar o shell do OpenRouter

O openrouter:shell oferece ao modelo com suporte a chamadas de ferramentas um ambiente Linux hospedado. O modelo pode executar comandos, receber stdout, stderr e o código de saída, e então corrigir o que for necessário. A Files API funciona como a camada de transporte para entradas e saídas.

Use essa combinação quando você precisar de:

• Um agente independente de modelo capaz de executar código longe do servidor da sua aplicação.
• Um processamento de arquivos repetível, como análise de CSV, extração de dados de PDFs ou geração de relatórios.
• Execução de ferramentas no servidor sem precisar construir seu próprio sandbox antes.

Não pense nele como um substituto direto para um shell local. A rede vem desativada por padrão, os contêineres não são persistentes automaticamente e a API pode mudar durante o beta.

A arquitetura que realmente importa

O openrouter:bash é a alternativa compatível com Anthropic. Por padrão, ele pede que a aplicação execute os comandos localmente; defina engine: "openrouter" quando precisar de execução remota, conforme descrito no anúncio do shell.

O caminho de um arquivo pelo sistema

1. Faça o upload e anexe o arquivo de entrada

Envie o arquivo para POST /api/v1/files como dados de formulário multipart. A referência de upload documenta o limite máximo de 100 MB por arquivo e um parâmetro de consulta opcional chamado workspace_id.

curl -X POST https://openrouter.ai/api/v1/files \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -F "file=@data/sales.csv"

A resposta traz metadados como ID do arquivo, nome, tipo MIME, tamanho em bytes, horário de criação e um indicador downloadable. Use o ID retornado no array file_ids do ambiente do shell.

Os arquivos anexados são copiados para o contêiner como cópias graváveis. Cada contêiner pode receber até 20 arquivos anexados, segundo o anúncio do shell. Alterar essa cópia não modifica o arquivo original no workspace.

Um desenvolvedor destacou especificamente a chegada do suporte à Files API depois de relatar dificuldades anteriores com PDF e OCR. É um sinal pequeno, mas concreto, de que o tratamento de arquivos era um problema real de integração (post).

2. Execute, inspecione e repita

O modelo envia um lote de comandos para o contêiner. Cada chamada devolve a saída e o status de encerramento, permitindo que o modelo corrija um script que falhou em vez de tentar adivinhar o problema a partir do prompt original (anúncio do shell).

A política de rede padrão é negar tudo. Se a tarefa precisar baixar pacotes ou fazer requisições externas, configure uma lista de permissões ao criar o contêiner. O OpenRouter documenta as portas 80 e 443 para hosts permitidos; essa política não pode ser alterada depois da inicialização. Requisições para domínios fora da lista podem falhar com HTTP 520 (anúncio do shell).

Apenas os arquivos dentro de /workspace/home são capturados nos resultados do shell. Portanto, grave o artefato nesse diretório se quiser que a API o informe. Arquivos criados ou alterados pelo shell recebem identificadores cfile_ (anúncio do shell).

3. Baixe ou promova o resultado

Um arquivo produzido pelo shell pode ser recuperado pelo endpoint de conteúdo de arquivos do contêiner:

GET /api/v1/containers/{container_id}/files/{file_id}/content

O identificador cfile_ pertence ao contêiner. Se o artefato precisar sobreviver ao ciclo de vida do contêiner, promova-o para o armazenamento do workspace. A promoção cria um novo identificador or_file_, que pode ser anexado a uma execução posterior (anúncio do shell).

Os arquivos do contêiner são mantidos por 30 dias. Promova tudo o que precisar ser conservado por mais tempo (anúncio do shell). O endpoint geral de download de arquivos devolve os bytes brutos e documenta HTTP 400 para arquivos enviados pelo usuário. Na prática, trate um upload direto como entrada, não como um objeto genérico de armazenamento.

Custos e limites que afetam o projeto

O anúncio do shell do OpenRouter informa que o tempo ativo do sandbox custa $0.0001 por segundo. Um contêiner iniciado a frio tem um mínimo de 30 segundos, o que resulta em uma cobrança mínima de sandbox de $0.003. O uso de tokens é cobrado separadamente.

Reutilize um contêiner aquecido em etapas relacionadas, evite loops desnecessários entre modelo e ferramenta e registre o custo de tokens separadamente do custo do sandbox. O anúncio informa que a área Logs exibe a atividade do modelo e a execução do sandbox em linhas separadas na timeline.

Estrutura básica da requisição

O schema exato do ambiente pode mudar durante o beta, mas o fluxo documentado é este: faça o upload primeiro e depois passe o ID retornado para uma requisição com shell habilitado. Mantenha o adaptador da requisição pequeno para facilitar atualizações caso o schema do beta mude.

{
  "model": "your/tool-capable-model",
  "tools": [
    {
      "type": "openrouter:shell",
      "environment": {
        "type": "container_auto",
        "file_ids": ["or_file_your_uploaded_file_id"]
      }
    }
  ],
  "input": "Analyze the attached CSV and write a summary to /workspace/home/report.md"
}

Envie essa estrutura para o endpoint Responses documentado no anúncio. Antes de usar em produção, confira o schema atual da requisição e os campos da resposta na documentação de server tools disponível no servidor.

Para começar a integração, siga esta sequência:

1. Envie um arquivo de entrada pequeno e anote o ID retornado.
2. Crie uma requisição para um modelo compatível com ferramentas, incluindo openrouter:shell em tools.
3. Anexe o arquivo explicitamente por meio de file_ids.
4. Peça ao modelo que grave as saídas abaixo de /workspace/home.
5. Verifique o código de saída e a lista de arquivos antes de considerar a tarefa concluída.
6. Baixe o artefato do contêiner ou promova-o se ele precisar ser reutilizado.
7. Registre o uso de tokens e a duração do sandbox em campos de custo separados.

Em um fluxo com várias requisições, passe um session_id ou uma referência explícita ao contêiner. Caso contrário, a requisição seguinte pode receber um contêiner novo, sem nenhum estado anterior.

O que costuma dar errado — e como contornar

Perguntas frequentes sobre o OpenRouter shell e a Files API

O OpenRouter shell executa comandos no meu computador?

Não. O openrouter:shell foi projetado para executar comandos em um sandbox hospedado pelo OpenRouter. O openrouter:bash, compatível com Anthropic, tem padrões diferentes; use engine: "openrouter" para execução remota (anúncio do shell).

Como mantenho os arquivos entre as requisições?

Reutilize uma sessão ou uma referência de contêiner. Sem esse caminho explícito de reutilização, uma requisição posterior pode iniciar um contêiner novo.

Qual é a diferença entre or_file_ e cfile_?

or_file_ identifica um objeto da Files API no workspace. cfile_ identifica um arquivo criado ou alterado dentro de um contêiner. A promoção transforma um artefato do contêiner em um novo ID de arquivo do workspace.

A Files API cobra uma taxa de uso separada?

O anúncio do shell informa que o uso da Files API não tem uma cobrança de uso separada, enquanto o armazenamento do workspace é limitado a 10 GiB. O tempo de sandbox do shell e o uso de tokens do modelo continuam sendo cobrados conforme suas respectivas tarifas.

O shell tool está pronto para produção?

Ele é documentado como beta, e o anúncio alerta que a API pode mudar. Antes de colocá-lo em um fluxo de produção sem supervisão, use limites explícitos, comandos delimitados, restrições no nível da aplicação e um caminho alternativo.

Use se o seu fluxo realmente produzir um artefato

O shell e a Files API do OpenRouter fazem sentido em um pipeline por etapas que gere um CSV tratado, um relatório, uma imagem transformada ou um artefato compilado. Trabalhe com IDs de arquivo explícitos, uma política de rede definida antes da execução, reutilização de contêineres e promoção para saídas que precisam persistir.

Se a tarefa for apenas responder em texto, o custo adicional do sandbox e o gerenciamento do ciclo de vida não se justificam. Se ela exigir credenciais locais, acesso irrestrito à rede ou garantias rígidas de produção, mantenha a execução na infraestrutura que você controla até que o beta esteja maduro o suficiente para esse nível de risco.

Fontes: anúncio do shell e da Files API do OpenRouter, referência de upload da Files API, referência de download do conteúdo de arquivos.