servio

servio e um CLI agente de codigo aberto para provedores de modelo em nuvem e local.

Use APIs compativeis com OpenAI, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, Atomic Chat e outros backends suportados mantendo um fluxo de trabalho no terminal: prompts, ferramentas, agents, MCP, comandos slash e saida em streaming.

Inicio Rapido | Guias de Configuracao | Provedores | Build do Codigo | Extensao VS Code | Comunidade

Por que o servio

• Use um CLI unico entre APIs na nuvem e backends de modelo local
• Salve perfis de provedor dentro do app com /provider
• Funcione com servicos compativeis com OpenAI, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, Atomic Chat e outros provedores suportados
• Mantenha os fluxos de trabalho do agente de codigo em um so lugar: bash, ferramentas de arquivo, grep, glob, agents, tarefas, MCP e ferramentas web
• Use a extensao VS Code incluida para integracao de inicializacao e suporte a temas

Inicio Rapido

Instalacao

npm install -g servio

Se a instalacao reportar ripgrep not found, instale o ripgrep no sistema e confirme que rg --version funciona no mesmo terminal antes de iniciar o servio.

Iniciar

servio

Dentro do servio:

• execute /provider para configuracao guiada de provedor e perfis salvos
• execute /onboard-github para onboarding do GitHub Models

Configuracao mais rapida com OpenAI

macOS / Linux:

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-sua-chave-aqui
export OPENAI_MODEL=gpt-4o

servio

Windows PowerShell:

$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_API_KEY="sk-sua-chave-aqui"
$env:OPENAI_MODEL="gpt-4o"

servio

Configuracao mais rapida com Ollama local

macOS / Linux:

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=qwen2.5-coder:7b

servio

Windows PowerShell:

$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_BASE_URL="http://localhost:11434/v1"
$env:OPENAI_MODEL="qwen2.5-coder:7b"

servio

Guias de Configuracao

Guias para iniciantes:

• Configuracao para Nao-Tecnicos
• Inicio Rapido no Windows
• Inicio Rapido no macOS / Linux

Guias avancados e build do codigo-fonte:

• Configuracao Avancada
• Instalacao no Android

Provedores Suportados

| Provedor | Caminho de Configuracao | Observacoes | | --- | --- | --- | | Compativel com OpenAI | /provider ou variaveis de ambiente | Funciona com OpenAI, OpenRouter, DeepSeek, Groq, Mistral, LM Studio e outros servidores /v1 compativeis | | Hicap | /provider ou variaveis de ambiente OpenAI | Usa autenticacao api-key, descobre modelos de /models nao autenticado e suporta modo Responses para modelos gpt- | | Gemini | /provider ou variaveis de ambiente | Suporta apenas API key | | GitHub Models | /onboard-github | Onboarding interativo com credenciais salvas | | Codex OAuth | /provider | Abre o login do ChatGPT no navegador e armazena credenciais do Codex de forma segura | | Codex | /provider | Usa autenticacao existente do Codex CLI, armazenamento seguro do servio, ou credenciais de ambiente | | Gitlawb Opengateway | /provider ou fallback zero-config | Gateway gratuito inteligente em https://opengateway.gitlawb.com/v1; roteia modelos Xiaomi MiMo e GMI Cloud por OPENAI_MODEL | | Xiaomi MiMo | /provider ou variaveis de ambiente | API compativel com OpenAI em https://api.xiaomimimo.com/v1; usa MIMO_API_KEY e padrao mimo-v2.5-pro | | Ollama | /provider ou variaveis de ambiente | Inferencia local sem API key | | Atomic Chat | /provider, variaveis de ambiente ou bun run dev:atomic-chat | Provedor de modelo local; detecta automaticamente modelos carregados | | Bedrock / Vertex / Foundry | variaveis de ambiente | Integracoes adicionais de provedor para ambientes suportados |

O que Funciona

• Fluxos de trabalho de codigo orientados a ferramentas: Bash, leitura/escrita/edicao de arquivos, grep, glob, agents, tarefas, MCP e comandos slash
• Respostas em streaming: Saida de tokens em tempo real e progresso de ferramentas
• Chamadas de ferramentas: Loops de ferramentas multi-etapa com chamadas de modelo, execucao de ferramentas e respostas de acompanhamento
• Imagens: Entradas de imagem por URL e base64 para provedores que suportam visao
• Perfis de provedor: Configuracao guiada mais suporte a perfis de provedor salvos no nivel do usuario
• Backends de modelo local e remoto: APIs na nuvem, servidores locais e inferencia local em Apple Silicon

Observacoes sobre Provedores

O servio suporta multiplos provedores, mas o comportamento nao e identico em todos eles.

• Recursos especificos do Anthropic podem nao existir em outros provedores
• A qualidade das ferramentas depende muito do modelo selecionado
• Modelos locais menores podem ter dificuldade com fluxos de ferramentas longos e multi-etapa
• Alguns provedores impoem limites de saida menores que os padroes do CLI, e o servio se adapta quando possivel
• O Gitlawb Opengateway usa uma URL base compativel com OpenAI. Alterne entre mimo-* e google/gemini-3.1-flash-lite-preview com /model; nao fixe a URL base em /v1/xiaomi-mimo.
• Xiaomi MiMo usa autenticacao via cabecalho api-key na rota compativel com OpenAI e atualmente nao suporta relatorio de /usage no servio

Para melhores resultados, use modelos com forte suporte a chamadas de ferramentas/funcoes.

Roteamento de Agents

O servio pode rotear diferentes agents para diferentes modelos atraves de roteamento baseado em configuracoes. Isso e util para otimizacao de custos ou dividir trabalho por forca do modelo.

Adicione em ~/.servio.json:

{
  "agentModels": {
    "deepseek-v4-flash": {
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "sk-sua-chave"
    },
    "gpt-4o": {
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-sua-chave"
    }
  },
  "agentRouting": {
    "Explore": "deepseek-v4-flash",
    "Plan": "gpt-4o",
    "general-purpose": "gpt-4o",
    "frontend-dev": "deepseek-v4-flash",
    "default": "gpt-4o"
  }
}

Quando nenhuma correspondencia de roteamento e encontrada, o provedor global permanece como fallback.

Nota: Valores de api_key em settings.json sao armazenados em texto puro. Mantenha este arquivo privado e nao o commite no controle de versao.

Busca e Captura na Web

Por padrao, WebSearch funciona em modelos nao-Anthropic usando DuckDuckGo. Isso da ao GPT-4o, DeepSeek, Gemini, Ollama e outros provedores compativeis com OpenAI um caminho gratuito de busca na web pronto para uso.

Nota: O fallback do DuckDuckGo funciona raspando resultados de busca e pode ser limitado em taxa, bloqueado ou sujeito aos Termos de Servico do DuckDuckGo. Se voce quiser uma opcao suportada mais confiavel, configure o Firecrawl.

Para backends nativos Anthropic e respostas Codex, o servio mantem o comportamento nativo de busca na web do provedor.

WebFetch funciona, mas seu caminho basico de HTTP mais conversao de HTML para markdown ainda pode falhar em sites renderizados por JavaScript ou sites que bloqueiam requisicoes HTTP simples.

Defina uma chave de API do Firecrawl se quiser comportamento de busca/captura com Firecrawl:

export FIRECRAWL_API_KEY=sua-chave-aqui

Com o Firecrawl habilitado:

• WebSearch pode usar a API de busca do Firecrawl enquanto DuckDuckGo permanece como caminho gratuito padrao para modelos nao-Claude
• WebFetch usa o endpoint de scraping do Firecrawl em vez de HTTP bruto, lidando corretamente com paginas renderizadas por JS

Plano gratuito em firecrawl.dev inclui 500 creditos. A chave e opcional.

Servidor gRPC Headless

O servio pode ser executado como um servico gRPC headless, permitindo integrar suas capacidades agentic (ferramentas, bash, edicao de arquivos) em outros aplicativos, pipelines de CI/CD ou interfaces de usuario personalizadas. O servidor usa streaming bidirecional para enviar chunks de texto em tempo real, chamadas de ferramentas e requisitar permissoes para comandos sensiveis.

1. Iniciar o Servidor gRPC

Inicie o motor principal como um servico gRPC em localhost:50051:

npm run dev:grpc

Configuracao

| Variavel | Padrao | Descricao | |-----------|-------------|------------------------------------------------| | GRPC_PORT | 50051 | Porta em que o servidor gRPC escuta | | GRPC_HOST | localhost | Endereco de vinculacao. Use 0.0.0.0 para expor em todas as interfaces (nao recomendado sem autenticacao) |

2. Executar o Cliente CLI de Teste

Fornecemos um cliente CLI leve que se comunica exclusivamente via gRPC. Ele funciona como o CLI interativo principal, renderizando cores, streaming de tokens e solicitando permissoes de ferramentas (s/n) via evento action_required do gRPC.

Em um terminal separado, execute:

npm run dev:grpc:cli

Nota: As definicoes gRPC estao localizadas em src/proto/servio.proto. Voce pode usar este arquivo para gerar clientes em Python, Go, Rust ou qualquer outra linguagem.

Build e Desenvolvimento Local

bun install
bun run build
node dist/cli.mjs

Comandos uteis:

• bun run dev
• bun test
• bun run test:coverage
• bun run security:pr-scan -- --base origin/main
• bun run smoke
• bun run doctor:runtime
• bun run verify:privacy
• bun test ... focado nas areas que voce alterou

Testes e Cobertura

O servio usa o test runner integrado do Bun para testes unitarios.

Execute a suite completa de testes unitarios:

bun test

Gere cobertura de testes unitarios:

bun run test:coverage

Abra o relatorio visual de cobertura:

open coverage/index.html

Se voce ja tem coverage/lcov.info e so quer reconstruir a UI:

bun run test:coverage:ui

Use execucoes de teste focadas quando alterar apenas uma area:

• bun run test:provider
• bun run test:provider-recommendation
• bun test caminho/para/arquivo.test.ts

Validacao recomendada para contribuidores antes de abrir um PR:

• bun run build
• bun run smoke
• bun run test:coverage para cobertura unitaria mais ampla quando sua alteracao afeta logica de runtime ou provedor compartilhada
• bun test ... focado nos arquivos e fluxos que voce alterou

A saida de cobertura e gravada em coverage/lcov.info, e o servio tambem gera um mapa de calor estilo atividade-git em coverage/index.html.

Estrutura do Repositorio

• src/ - CLI/runtime principal
• scripts/ - scripts de build, verificacao e manutencao
• docs/ - documentacao de configuracao, contribuidores e projeto
• python/ - auxiliares Python independentes e seus testes
• vscode-extension/servio-vscode/ - extensao VS Code
• .github/ - automacao do repositorio, templates e configuracao de CI
• bin/ - pontos de entrada do launcher do CLI

Extensao VS Code

O repositorio inclui uma extensao VS Code em vscode-extension/servio-vscode para integracao de inicializacao do servio, UI de centro de controle com suporte a provedor e suporte a temas.

Seguranca

Se voce acredita que encontrou um problema de seguranca, consulte SECURITY.md.

Comunidade

• Use GitHub Discussions para perguntas e respostas, ideias e conversa da comunidade
• Use GitHub Issues para bugs confirmados e trabalho de funcionalidades acionaveis

Contribuicoes

Contribuicoes sao bem-vindas.

Para alteracoes maiores, abra uma issue primeiro para que o escopo esteja claro antes da implementacao. Comandos de validacao uteis incluem:

• bun run build
• bun run test:coverage
• bun run smoke
• bun test ... focado nos arquivos e fluxos que voce alterou

Aviso Legal

O servio e um projeto comunitario independente e nao e afiliado, endossado ou patrocinado pela Anthropic.

O servio teve origem no codebase do Claude Code e desde entao foi substancialmente modificado para suportar multiplos provedores e uso aberto. "Claude" e "Claude Code" sao marcas registradas da Anthropic PBC. Consulte LICENSE para detalhes.

Licenca

Consulte LICENSE.