Files
CenaForge/doc/ia.md
T
MateuusandClaude Opus 5.5 ed31d52df0 IA: Claude, Codex e Gemini com login, chave de API e IA reserva; Configurações em subpáginas
- Configurações → IA (/settings/ai): um cartão por IA para instalar/atualizar a CLI pelo painel, ligar,
  entrar com a conta (OAuth pela própria CLI, num terminal) ou colar a chave de API, e testar.
  Chaves cifradas com a DPAPI do Windows em data/ai/vault.bin; só vão para a CLI no ambiente da chamada.
- Gemini CLI como terceiro agente do painel (stream-json, edição automática, shell só o liberado).
- IA reserva: execução que cai por indisponibilidade (cota, 429, login, chave, rede) pausa a IA e recomeça
  a mesma tarefa na próxima pronta da ordem; migração v10 (agent_runs.fallback_of).
- Configurações viraram subpáginas (IA, Publicação, Apps das redes, Navegador, Sobre os modos), também no
  menu lateral; links antigos apontam para a subpágina certa.
- Contrato com o Clipador em doc/ia.md; skill do CenaForge atualizada até a 1.51.0.

O login gratuito do Gemini CLI para conta pessoal foi encerrado pelo Google (IneligibleTierError): para
conta pessoal, use a chave do AI Studio.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 01:51:12 -03:00

4.7 KiB

IA do CenaForge — provedores, login e reserva

Três IAs, sempre pela CLI oficial instalada no PC (nunca SDK/HTTP direto):

Provedor CLI Instalação (Windows) Login com a conta (OAuth) Chave de API (variável)
claude Claude Code (claude) irm https://claude.ai/install.ps1 | iex claude auth login ANTHROPIC_API_KEY
codex Codex (codex) npm install -g @openai/codex@latest codex login (ChatGPT) CODEX_API_KEY (só no codex exec)
gemini Gemini CLI (gemini) npm install -g @google/gemini-cli@latest gemini interativo → "Login with Google" GEMINI_API_KEY

Gemini + OAuth (verificado em 18/11/2026, gemini-cli 0.68.0): o login gratuito "Gemini Code Assist for individuals" foi encerrado (IneligibleTierError: UNSUPPORTED_CLIENT, o Google manda migrar para o Antigravity). OAuth só funciona com plano elegível (Code Assist Standard/Enterprise, Workspace). Para conta pessoal, use a chave de API do Google AI Studio.

Quem usa: os agentes do painel (panel/src/lib/agents.ts) e o juiz do Clipador (clipper/app/judge.py). A configuração fica no painel em Configurações → IA (/settings/ai).

Arquivos compartilhados (contrato painel ↔ Clipador)

Ambos em data/ai/. Quem escreve é só o painel; o Clipador apenas lê (relê se o mtime mudar).

data/ai/settings.json (sem segredo)

{
  "version": 1,
  "providers": {
    "claude": { "enabled": true, "authMode": "oauth" },
    "codex":  { "enabled": true, "authMode": "oauth" },
    "gemini": { "enabled": false, "authMode": "apiKey" }
  },
  "order": ["claude", "codex", "gemini"],
  "fallback": { "enabled": true, "cooldownMin": 15 }
}
  • enabled: a IA pode ser usada (como principal ou reserva). Desligada, nunca é chamada.
  • authMode: "oauth" = a sessão já logada da CLI; "apiKey" = a chave guardada no cofre.
  • order: prioridade da reserva. A tarefa usa a IA escolhida (ou a preferida dela); se falhar por indisponibilidade, tenta a próxima da lista que estiver ligada e pronta.
  • fallback.enabled: liga a troca automática. cooldownMin: depois de uma falha de indisponibilidade, a IA fica "em pausa" esse tempo e é pulada (cada processo guarda a sua pausa em memória).
  • Arquivo ausente ou inválido = padrão acima, com claude e codex ligados em oauth e gemini desligado.

data/ai/vault.bin (chaves de API)

Um JSON {"claude": "sk-ant-…", "codex": "sk-…", "gemini": "AIza…"} (só as que existirem) cifrado com a DPAPI do Windows, escopo do usuário (CurrentUser), entropia b"CenaForge.AI.vault.v1". O arquivo é o blob cru da DPAPI. Só a mesma conta do Windows nesta máquina abre. A chave nunca volta para a tela: a API do painel só diz se existe e os 4 últimos caracteres.

Ambiente de cada chamada

Montado a partir do ambiente do processo, por provedor:

Provedor authMode = "oauth" authMode = "apiKey"
claude remove ANTHROPIC_API_KEY ANTHROPIC_API_KEY=<chave>
codex remove CODEX_API_KEY CODEX_API_KEY=<chave>
gemini GOOGLE_GENAI_USE_GCA=true, remove GEMINI_API_KEY GEMINI_API_KEY=<chave>, remove GOOGLE_GENAI_USE_GCA

Assim o login global de cada CLI não é tocado: o modo chave só vale para a chamada.

O que conta como "indisponível" (dispara a reserva)

Falha que não é culpa do pedido: limite de uso ou cota (rate limit, 429, quota, usage limit, credit balance), sobrecarga (overloaded, 529, 503, unavailable), login ou chave (401, 403, unauthorized, not logged in, invalid api key, IneligibleTier), rede (ECONN, ETIMEDOUT, ENOTFOUND, network), CLI que não iniciou ou não foi encontrada, e tempo esgotado. Erro de conteúdo (JSON inválido, schema) não troca de IA.

Gemini CLI em modo headless (0.68.0)

  • Agente: gemini -p <prompt> -o stream-json --approval-mode auto_edit --skip-trust [-m <modelo>] [--resume <sessão>].
  • Eventos JSONL: init {session_id, model}, message {role, content, delta} (texto do assistente chega em pedaços), tool_use {tool_name, tool_id, parameters}, tool_result {tool_id, status, output, error}, error {severity: warning|error, message}, result {status, error?, stats}.
  • Respostas estruturadas (juiz): -o json devolve {"response": "<texto>", "stats": …}; não há --output-schema, então o schema vai no prompt e o JSON é extraído do texto. Leitura somente: --approval-mode plan --skip-trust, rodando numa pasta temporária fora do repositório (o @arquivo respeita o .gitignore).
  • Modelos: gemini models -o json (não exige login).
  • No Windows o npm instala gemini.cmd; rode node <prefixo npm>/node_modules/@google/gemini-cli/bundle/gemini.js.