Codex CLI — Configuration with OmniRoute (Português (Portugal))

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

Guia completo para utilizar a CLI do Codex com o OmniRoute como backend compatível com a OpenAI.

TOML é o único formato eficaz. As versões modernas do Codex leem exclusivamente ~/.codex/config.toml (verificado com codex-cli 0.147.0: codex --help documenta que as substituições de -c/--config são «carregadas a partir de ~/.codex/config.toml»). O antigo ~/.codex/config.yaml pertencia à CLI npm legada e é silenciosamente ignorado. O gerador do painel (/api/cli-tools/apply, ferramenta codex) escreve TOML com uma integração conservadora — as chaves existentes e os blocos de outros fornecedores são preservados, a chave da API permanece em OMNIROUTE_API_KEY (nunca no ficheiro) e qualquer config.yaml legado remanescente é indicado numa nota de migração sem ser alterado.

config.toml pronto a colar

Substitua <YOUR_HOST> e <YOUR_KEY> pelos seus valores:

# ~/.codex/config.toml
model                          = "cx/gpt-5.5"
model_provider                 = "omniroute"
model_reasoning_effort         = "xhigh"
model_context_window           = 400000
model_auto_compact_token_limit = 350000
tool_output_token_limit        = 32768    # limite de armazenamento no histórico por chamada de ferramenta

[model_providers.omniroute]
name                 = "OmniRoute"
base_url             = "http://<YOUR_HOST>:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false
wire_api             = "responses"

# ~/.bashrc ou ~/.zshrc — valor real da chave, nunca em config.toml
export OMNIROUTE_API_KEY="<YOUR_KEY>"

macOS: Codex incluído na aplicação ChatGPT

Se instalou o Codex através da aplicação ChatGPT para computador, o binário codex poderá existir apenas no pacote da aplicação e ainda não estar no PATH da sua shell. Adicione o diretório de recursos ao ficheiro de inicialização da sua shell:

export PATH="/Applications/ChatGPT.app/Contents/Resources:$PATH"

Abra uma nova shell e, em seguida, confirme:

command -v codex
codex --version

OmniRoute local sem autenticação: uma chave de marcador é suficiente

O Codex valida se a variável de ambiente indicada por env_key existe antes de o primeiro pedido sair da CLI. Se a sua instância local do OmniRoute não exigir autenticação, qualquer marcador não vazio funciona:

export OMNIROUTE_API_KEY="${OMNIROUTE_API_KEY:-local}"

Utilize uma chave real se o seu servidor OmniRoute estiver protegido ou for remoto.

Opções de anfitrião comuns

Acesso URL

Rede local http://192.168.0.1:20128/v1

Tailscale http://100.x.x.x:20128/v1

Loopback http://localhost:20128/v1

Acesso	URL
Rede local	`http://192.168.0.1:20128/v1`
Tailscale	`http://100.x.x.x:20128/v1`
Loopback	`http://localhost:20128/v1`

`wire_api = "responses"` — por que motivo funciona com todos os modelos

A CLI do Codex descontinuou wire_api = "chat" (Chat Completions) em fevereiro de 2026 e agora exige wire_api = "responses" (API Responses da OpenAI). Definir wire_api = "chat" provoca uma falha imediata no arranque desde a v0.138.

Muitos fornecedores, incluindo GLM e Kimi, continuam a disponibilizar apenas um endpoint de Chat Completions. O DeepSeek V4 disponibiliza agora uma API Responses nativa, bem como um endpoint compatível com a Anthropic; o OmniRoute utiliza Responses por predefinição e permite que cada ligação ao DeepSeek selecione a compatibilidade com a Anthropic.

O OmniRoute resolve esta questão de forma transparente:

CLI do Codex
  → wire_api = "responses"
  → POST /v1/responses (OmniRoute)
    → O OmniRoute seleciona o protocolo nativo do fornecedor e traduz quando necessário
    → POST /responses (DeepSeek V4) ou /chat/completions (Mistral / GLM / Kimi / outros)

Nunca precisa de um proxy de tradução separado ao utilizar o OmniRoute. Todos os modelos utilizam wire_api = "responses" — o OmniRoute trata do resto.

wire_api é a predefinição — o campo utiliza "responses" por predefinição e pode ser completamente omitido de config.toml. Defina-o explicitamente apenas se estiver a documentar a intenção.

Janela de contexto e compactação

Campos de configuração de tokens

Campo	Descrição
`model_context_window`	Orçamento total de tokens para o modelo ativo. Defina-o com o limite anunciado do modelo.
`model_auto_compact_token_limit`	Limiar que aciona a compactação automática do histórico. Máximo: 90% de `model_context_window` — os valores acima de 90% são silenciosamente ignorados.
`tool_output_token_limit`	Limite de tokens armazenados no histórico por resultado de chamada de ferramenta. Impede que uma única resposta extensa de uma ferramenta preencha a janela. Não é o limite máximo de saída — é um limite de armazenamento no histórico.
`compact_prompt`	Substituição inline do prompt de sistema utilizado durante a compactação (v0.138+).

Nota sobre model_max_output_tokens: Este campo não faz parte do esquema de configuração da Codex CLI (está ausente da base de código Rust do Codex). Se for definido, é silenciosamente ignorado. Não dependa dele — utilize tool_output_token_limit para controlar a quantidade de resultados de ferramentas armazenada no histórico.

Janelas de contexto por modelo

Modelo	ID do OmniRoute	Janela de contexto	`auto_compact`	`tool_output_limit`
GPT-5.5	`cx/gpt-5.5`	400k fiável (máx. 1M)	350,000	32,768
Kimi K2.7 (raciocínio)	`kmc/kimi-k2.7`	131,072	112,000	32,768
Kimi K2.6	`kmc/kimi-k2.6`	131,072	112,000	32,768
GLM-5.2 / 5.2-max (raciocínio)	`glm/glm-5.2`	131,072	112,000	32,768
MiMo V2.5 Pro (raciocínio)	`opencode-go/mimo-v2.5-pro`	131,072	112,000	32,768
Qwen 3.7 Plus (raciocínio)	`opencode-go/qwen3.7-plus`	32,768	28,000	16,384
DeepSeek V4 Pro (OllamaCloud)	`ollamacloud/deepseek-v4-pro`	131,072	112,000	32,768
DeepSeek V4 Pro	`ds/deepseek-v4-pro`	1,000,000	900,000	65,536
MiMo V2.5	`opencode-go/mimo-v2.5`	131,072	112,000	32,768
Gemma 4 31B (OllamaCloud)	`ollamacloud/gemma4:31b`	32,768	28,000	16,384
Nemotron 3 Super (OllamaCloud)	`ollamacloud/nemotron-3-super`	32,768	28,000	16,384
GPT-OSS 20B (OllamaCloud)	`ollamacloud/gpt-oss:20b`	32,768	28,000	16,384
DeepSeek V4 Flash (OllamaCloud)	`ollamacloud/deepseek-v4-flash`	65,536	56,000	16,384
Gemini 3 Flash Preview (OllamaCloud)	`ollamacloud/gemini-3-flash-preview`	1,000,000	850,000	32,768
GLM-5 Turbo	`glm/glm-5-turbo`	131,072	112,000	16,384
GLM-4.7 Flash	`glm/glm-4.7-flash`	131,072	112,000	16,384
Mistral Large Latest	`mistral/mistral-large-latest`	262,144	220,000	16,384

Fórmula de compactação: effective_window = model_context_window - min(tool_output_token_limit, 20000). Os valores acima de 20k não alteram o acionamento da compactação.

Regra geral: defina model_auto_compact_token_limit como 85–88% de model_context_window. Nunca ultrapasse 90% — será silenciosamente ignorado.

Prefixo dos modelos: `cx/`

Todos os modelos Codex no OmniRoute usam o prefixo cx/:

Nome no Codex CLI	Modelo OmniRoute
`cx/gpt-5.5`	GPT-5.5 padrão
`cx/gpt-5.4`	GPT-5.4 padrão
`cx/gpt-5.4-mini`	GPT-5.4 mini
`cx/gpt-5.1-codex-mini`	GPT-5.1 Codex mini

Os outros fornecedores usam o seu próprio prefixo (kmc/, glm/, ds/, ollamacloud/, opencode-go/, mistral/) — o prefixo corresponde ao alias do fornecedor no OmniRoute.

Esforço de raciocínio

Controla quanto o modelo «pensa» antes de responder.

Valor	Utilizar para
`none`	Sem raciocínio — resposta direta
`low`	Tarefas triviais (mudar nomes, formatar)
`medium`	Predefinição do servidor quando não indicado
`high`	Tarefas intermédias (refatoração, depuração)
`xhigh`	Arquitetura, análise aprofundada, problemas complexos

# Substituição por invocação
codex -c model_reasoning_effort=low "mudar o nome da variável x para count"
codex -c model_reasoning_effort=xhigh "conceber o módulo de autenticação"

Defina também um resumo do raciocínio para que o Desktop possa apresentar o texto do pensamento (e não apenas blocos encriptados):

# ~/.codex/config.toml
model_reasoning_effort = "xhigh"   # ou ultra, quando suportado
model_reasoning_summary = "detailed"  # auto | concise | detailed | none

Orçamento de pensamento do OmniRoute (definição do servidor)

No anfitrião do OmniRoute, Settings → AI → Thinking Budget tem de estar definido como passthrough para que o esforço/resumo do Codex chegue ao fornecedor a montante. O modo auto remove todos os campos reasoning / reasoning_effort do cliente e deixa os painéis de pensamento vazios, mesmo quando o Codex está configurado corretamente.

Guia completo: THINKING_BUDGET.md.

A compressão e a cache de pedidos são independentes e continuam a funcionar com passthrough.

Perfis — configurações com nome por modelo/fluxo de trabalho

Os perfis permitem alternar entre modelo + janela de contexto com uma única opção. Cada perfil é um ficheiro simples ~/.codex/<name>.config.toml que se sobrepõe ao config.toml base.

Regra de nomenclatura (Codex CLI v0.137+): o ficheiro tem de ser ~/.codex/<name>.config.toml — sem o prefixo profile-. A CLI resolve -p kimi-k27 como ~/.codex/kimi-k27.config.toml. Se o ficheiro não for encontrado, a predefinição é aplicada silenciosamente.

codex --profile kimi-k27 "analisar 10 mil linhas desta base de código"
codex -p glm52 "revisão da arquitetura"
codex --profile deepseek-flash "mudar o nome da variável"   # rápido, económico

Perfis de esforço (o mesmo modelo, diferentes níveis de esforço)

codex -p low      # cx/gpt-5.5, esforço=low
codex -p medium   # cx/gpt-5.5, esforço=medium
codex -p high     # cx/gpt-5.5, esforço=high
codex -p xhigh    # cx/gpt-5.5, esforço=xhigh (predefinição)
codex -p chat     # cx/gpt-5.5, sem esforço definido (predefinição do servidor)

Modelos de pensamento (alto pensamento) — xhigh + resumo detalhado

Perfil	Modelo	Contexto	Utilizar para
`kimi-k27`	`kmc/kimi-k2.7`	128k	Melhor qualidade de pensamento (Kimi)
`glm52`	`glm/glm-5.2`	128k	Pensamento GLM
`glm52max`	`glm/glm-5.2-max`	128k	Pensamento GLM máximo
`mimo-pro`	`opencode-go/mimo-v2.5-pro`	128k	Pensamento MiMo
`qwen37plus`	`opencode-go/qwen3.7-plus`	32k	Pensamento Qwen

Bons modelos (bons) — esforço elevado

Perfil	Modelo	Contexto	Utilizar para
`kimi-k26`	`kmc/kimi-k2.6`	128k	Uso geral (Kimi)
`deepseek-pro`	`ollamacloud/deepseek-v4-pro`	128k	DeepSeek Pro através do OllamaCloud
`deepseek`	`ds/deepseek-v4-pro`	1M	DeepSeek Pro direto, contexto muito extenso
`mimo`	`opencode-go/mimo-v2.5`	128k	MiMo para uso geral

Modelos simples (simples) — sem esforço de raciocínio

Perfil	Modelo	Contexto	Utilizar para
`gemma4`	`ollamacloud/gemma4:31b`	32k	Económico e competente
`nemotron`	`ollamacloud/nemotron-3-super`	32k	NVIDIA Nemotron
`gptoss`	`ollamacloud/gpt-oss:20b`	32k	GPT de código aberto

Modelos rápidos — esforço reduzido

Perfil	Modelo	Contexto	Utilizar para
`deepseek-flash`	`ollamacloud/deepseek-v4-flash`	64k	Tarefas rápidas
`gemini-flash`	`ollamacloud/gemini-3-flash-preview`	1M	Muito rápido, contexto muito extenso
`glm5turbo`	`glm/glm-5-turbo`	128k	GLM Turbo
`glm47flash`	`glm/glm-4.7-flash`	128k	GLM Flash
`mistral`	`mistral/mistral-large-latest`	256k	Mistral Large

Tabela de decisão rápida

Tarefa	Perfil recomendado
Renomeação, formatação, código repetitivo	`--profile deepseek-flash` ou `-p low`
Explicação, revisão ligeira	`-p chat` ou `-p gemini-flash`
Depuração, refatoração moderada	`-p medium` ou `-p kimi-k26`
Nova funcionalidade, testes complexos	`-p high` ou `-p mimo`
Arquitetura, análise aprofundada	`-p kimi-k27` ou `-p glm52` ou `-p xhigh`
Análise da base de código (requer 1M de ctx)	`--profile deepseek` ou `--profile gemini-flash`
Qualidade máxima de raciocínio	`-p glm52max` ou `-p mimo-pro`
Económico	`-p gemma4` ou `-p gptoss`

Gerar perfis automaticamente com `omniroute setup-codex`

Se executar o OmniRoute num VPS, pode gerar automaticamente ficheiros de perfil a partir do catálogo de modelos ativo:

# A partir de um VPS (utiliza o OmniRoute local na porta 20128)
omniroute setup-codex

# A partir de qualquer máquina — aponte para o seu VPS
omniroute setup-codex --remote http://100.x.x.x:20128 --api-key sk-xxx

# Pré-visualizar sem escrever ficheiros
omniroute setup-codex --remote http://100.x.x.x:20128 --dry-run

# Gerar apenas perfis GLM e Kimi
omniroute setup-codex --only glm,kimi

# Escrever num diretório personalizado
omniroute setup-codex --codex-home /path/to/.codex

O comando obtém /v1/models, utiliza perfis otimizados para modelos conhecidos, recorre aos metadados do catálogo para outros modelos de texto compatíveis e escreve ~/.codex/<name>.config.toml para cada um. É idempotente — pode ser executado novamente em segurança.

O OmniRoute também pode sincronizar automaticamente estes mesmos ficheiros de perfil depois de uma deteção/importação bem-sucedida dos modelos do fornecedor alterar o catálogo ativo. Esta opção é facultativa e está desativada por predefinição: ative-a no painel CLI Code ("Sincronização automática de perfis CLI" → Codex) ou defina OMNIROUTE_AUTO_SYNC_CODEX_PROFILES=true (também respeita CLI_ALLOW_CONFIG_WRITES, que está ativado por predefinição). Quando ativada, apenas escreve ficheiros de perfil ~/.codex/*.config.toml separados; nunca altera o ficheiro ativo/predefinido ~/.codex/config.toml, as definições do Codex-lb, a autenticação ou a seleção do fornecedor.

Iniciar o Codex com `omniroute launch-codex`

Verifica o estado da sua instância do OmniRoute antes de iniciar o Codex:

# Iniciar com o OmniRoute local (porta predefinida 20128)
omniroute launch-codex

# Iniciar com um perfil específico
omniroute launch-codex --profile kimi-k27

# Iniciar com um VPS remoto
omniroute launch-codex --remote http://100.x.x.x:20128/v1 --api-key sk-xxx

# Passar argumentos adicionais ao codex
omniroute launch-codex --profile glm52 -- --yolo "corrigir este erro"

O Codex é também um destino dos dois pontos de entrada genéricos orientados por manifesto (bin/cli/cli-manifest.mjs):

# Seletor interativo de modelos → escreve ~/.codex/<name>.config.toml (TOML, env_key)
omniroute configure codex

# Iniciar o codex com o fornecedor omniroute injetado através de flags -c (sem escrever configuração)
omniroute run codex

Novas funcionalidades da CLI do Codex (v0.138–v0.141)

Versão	Funcionalidade
v0.138	Transferência para a aplicação de computador (`/app`), tokens de acesso pessoal v2, `--profile` como seletor de perfil exclusivo (as tabelas `[profiles]` legadas no ficheiro provocam uma falha no arranque)
v0.139	`web_search = "live"` — pesquisa nativa na Web a partir do modo de código; `oneOf`/`allOf` nos esquemas de ferramentas MCP; diagnóstico de ambiente com `codex doctor`
v0.140	Vista de tokens `/usage` durante a sessão; `/import` a partir de sessões do Claude Code; subcomando `codex delete <SESSION_ID>`; autenticação do Amazon Bedrock através do objeto `aws` na configuração do fornecedor
v0.141	Relay Noise com encriptação ponto a ponto para executores remotos; correção do WAL do SQLite; suporte para TLS P-521

Novos campos de `config.toml` (posteriores à v0.137)

# Pesquisa nativa na Web (v0.139)
web_search = "live"   # "disabled" | "cached" | "live"

# Prompt de sistema separado para o programador (v0.138)
developer_instructions = "Preferir sempre um estilo funcional."

# Prompt de compactação personalizado
compact_prompt = "Resumir o conteúdo acima em tópicos."

# Encaminhar /review para um modelo mais económico
review_model = "glm/glm-5-turbo"

# Nível de serviço da OpenAI
service_tier = "fast"   # "fast" | "flex"

Novos campos de `[model_providers.<id>]`

[model_providers.omniroute]
base_url             = "http://100.x.x.x:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false

# Cabeçalhos adicionais estáticos em todos os pedidos
[model_providers.omniroute.http_headers]
"X-Custom-Header" = "value"

# Cabeçalhos lidos a partir de variáveis de ambiente
[model_providers.omniroute.env_http_headers]
"X-Trace-Id" = "TRACE_ID"

# Parâmetros adicionais de consulta do URL (úteis para api-version do Azure)
[model_providers.omniroute.query_params]
"api-version" = "2024-12-01-preview"

Autenticação do Amazon Bedrock (v0.140)

[model_providers.bedrock]
base_url = "https://bedrock-runtime.us-east-1.amazonaws.com"

[model_providers.bedrock.aws]
profile = "default"   # perfil de ~/.aws/credentials
region  = "us-east-1"

Vários servidores

[model_providers.omniroute-main]
base_url = "http://192.168.0.1:20128/v1"
env_key  = "OMNIROUTE_API_KEY"

[model_providers.omniroute-tailscale]
base_url = "http://100.x.x.x:20128/v1"
env_key  = "OMNIROUTE_API_KEY"

Claude Code — configuração equivalente

Codex CLI (`config.toml`)	Claude Code (variável de ambiente)	Efeito
`tool_output_token_limit = 32768`	(não disponibilizado diretamente)	Limite de histórico por ferramenta
`model_context_window = 400000`	(determinado pelo modelo)	Janela de contexto
—	`CLAUDE_CODE_MAX_OUTPUT_TOKENS=65536`	Máximo de tokens por resposta

# ~/.bashrc — limite de tokens do Claude Code
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=65536

Referência rápida — opções da CLI

Opção	Forma abreviada	Efeito
`--model <id>`	`-m`	Substitui `model` nesta invocação
`--profile <name>`	`-p`	Carrega `~/.codex/<name>.config.toml`
`--config key=value`	`-c`	Substitui qualquer campo de config.toml (pode ser repetida)
`--enable <feature>`	—	Ativa explicitamente uma flag de funcionalidade
`--disable <feature>`	—	Desativa explicitamente uma flag de funcionalidade
`--search`	—	Ativa a pesquisa web em tempo real nesta invocação

Novidades na v0.140:

codex delete <SESSION_ID>          # eliminar uma sessão
codex delete <SESSION_ID> --force  # ignorar a confirmação
codex debug models --bundled       # listar o catálogo de modelos incluído como JSON

Dentro de uma sessão interativa:

Comando	Efeito
`/model`	Abre o seletor de modelos
`/usage`	Mostra a utilização de tokens nesta sessão (v0.140)
`/app`	Transfere para a aplicação de ambiente de trabalho (v0.138)
`/import`	Importa uma sessão do Claude Code (v0.140)
`/help`	Lista todos os comandos com barra

Tarefas de longa duração

Duas predefinições do OmniRoute podem comprometer silenciosamente sessões do Codex CLI com várias horas de duração. Nenhuma delas é uma definição do Codex CLI — ambas pertencem ao OmniRoute. Os utilizadores que migram uma configuração de proxies a montante que fixam contas e desativam os limites de inatividade deparam-se frequentemente com ambas e concluem que o OmniRoute «não consegue manter uma sessão longa».

Sintoma	Causa provável	Parâmetro
A sessão continua a trocar de conta / a continuidade da cache de prompts perde-se entre interações	O TTL da afinidade de sessão é `0` (desativado)	`sessionAffinityTtlMs`
A ligação termina durante o raciocínio sem qualquer aviso apresentado ao cliente	O supervisor de inatividade do fluxo foi acionado após 10 minutos sem qualquer bloco a montante	`STREAM_IDLE_TIMEOUT_MS`

Discussões relacionadas: #7126 (interrupções de tarefas longas), #5718 (motivo pelo qual a afinidade está desativada por predefinição). Acompanhamento: #7287.

1. Afinidade de sessão — fixar uma conversa a uma conta

Predefinição: sessionAffinityTtlMs = 0 (desativado).

Onde configurar

Painel → Definições → Encaminhamento → Afinidade de sessão → TTL da afinidade (segundos) (ComboDefaultsTab)
Ou aplique PATCH às definições com sessionAffinityTtlMs em milissegundos (intervalo Zod de 0–86_400_000, ou seja, até 24 horas)

Renomeado em #7274 a partir do codexSessionAffinityTtlMs, exclusivo do Codex. A chave legada continua a ser aceite como um alias só de leitura; as novas configurações devem utilizar sessionAffinityTtlMs. A afinidade aplica-se agora a qualquer fornecedor quando o TTL é superior a 0, e não apenas ao Codex — consulte docs/architecture/RESILIENCE_GUIDE.md → Afinidade de sessão.

O que deixa de funcionar quando permanece em 0

Cada interação de uma conversa com várias interações no Codex é encaminhada de forma independente pela estratégia de combinação ativa e pode acabar numa conta diferente em cada interação. Isso interrompe a continuidade da sessão/cache de prompts a montante. O OmniRoute apenas consulta os cabeçalhos de sessão do Codex (x-codex-session-id / x-session-id / x-omniroute-session) e campos do corpo, como prompt_cache_key / session_id, quando o TTL é superior a 0 (extractSessionAffinityKey em src/sse/services/auth.ts).

Recomendação para uma única tarefa com várias horas de duração

Defina o TTL para um valor superior à duração real prevista da tarefa (o máximo da IU é 86400 segundos = 24 horas):

Duração prevista da tarefa	TTL da afinidade (IU, segundos)	`sessionAffinityTtlMs`
Algumas horas	`14400` (4 h)	`14400000`
Durante a noite / ~12 h	`43200` (12 h)	`43200000`
Dia inteiro	`86400` (24 h, máximo)	`86400000`

A adesão é deliberada: desativar a afinidade favorece o balanceamento de carga entre contas; ativá-la favorece a continuidade de uma sessão longa de um agente. Este guia não altera a predefinição — os operadores que executam tarefas longas do Codex têm de aderir explicitamente.

2. Tempo limite de inatividade do fluxo — não interromper interações de raciocínio silenciosas

Predefinição: STREAM_IDLE_TIMEOUT_MS = 600000 (10 minutos). Quando não está definido, herda de REQUEST_TIMEOUT_MS; o valor base partilhado também é 600000. Consulte docs/guides/SETUP_GUIDE.md → Tempos limite.

O que deixa de funcionar com a predefinição

Um turno de raciocínio / utilização de ferramenta do Codex que permaneça silencioso durante mais de 10 minutos sem qualquer bloco real a montante é encerrado à força pelo mecanismo de vigilância de inatividade SSE (open-sse/utils/stream.ts). Frequentemente, o cliente vê apenas uma interrupção abrupta da ligação — o que corresponde a «parou automaticamente sem qualquer notificação».

Detalhe crítico: o heartbeat SSE sintético do OmniRoute não reinicia o temporizador de inatividade. Apenas um bloco real do corpo da resposta a montante atualiza lastChunkTime. Para o mecanismo de vigilância, um modelo silencioso que ainda está «a pensar» parece exatamente igual a uma ligação a montante bloqueada.

Inatividade relacionada do corpo no Undici: FETCH_BODY_TIMEOUT_MS (também assume, por predefinição, o mesmo valor de referência de 10 minutos; 0 desativa-o). Para streaming, FETCH_TIMEOUT_MS abrange apenas o estabelecimento da ligação / os primeiros cabeçalhos — assim que o stream fica ativo, os bloqueios são controlados por STREAM_IDLE_TIMEOUT_MS e FETCH_BODY_TIMEOUT_MS.

Recomendação para uma única tarefa com várias horas de duração

No ambiente do processo do OmniRoute (.env / compose / systemd):

# Desativar os limites de inatividade do stream e do corpo para turnos de raciocínio prolongados
STREAM_IDLE_TIMEOUT_MS=0
FETCH_BODY_TIMEOUT_MS=0

Em alternativa, aumente-os para valores superiores ao maior intervalo de silêncio previsto (os valores são em milissegundos):

# Exemplo: permitir até 2 horas de silêncio entre blocos a montante
STREAM_IDLE_TIMEOUT_MS=7200000
FETCH_BODY_TIMEOUT_MS=7200000

Reinicie o OmniRoute depois de alterar estas variáveis de ambiente.

Procedimento concreto — tarefa do Codex com várias horas de duração

Fixe a conta: Painel → Definições → Encaminhamento → Afinidade de sessão → TTL da afinidade = 43200 (12 h) ou 86400 (máximo de 24 h).
Aumente / desative os limites de inatividade no ambiente do OmniRoute:

STREAM_IDLE_TIMEOUT_MS=0
FETCH_BODY_TIMEOUT_MS=0

Mantenha o config.toml habitual do Codex (wire_api = "responses", base_url correto, OMNIROUTE_API_KEY) — não existem opções de afinidade/inatividade no lado do Codex para estes dois comportamentos.
Reinicie o OmniRoute e, em seguida, inicie a tarefa prolongada do Codex.

Decisão sobre os valores predefinidos (#7287)

Opção	Valor predefinido	Alterar neste guia?
`sessionAffinityTtlMs`	`0` (desativado)	Não — continua a ser opcional (balanceamento de carga vs. continuidade; consulte a Discussão #5718)
`STREAM_IDLE_TIMEOUT_MS`	`600000` (10 min)	Não — mantém-se em 10 minutos para tráfego geral; os operadores de tarefas prolongadas do Codex aumentam-no ou desativam-no

Alterar globalmente qualquer um dos valores predefinidos mudaria o comportamento para todos os clientes de uma instância, não apenas para o Codex. Documente as opções; mantenha os valores predefinidos inalterados até que uma decisão explícita do operador determine o contrário.

Diagnosticar interrupções por inatividade

Quando o mecanismo de vigilância de inatividade é acionado, o OmniRoute regista uma linha com este formato:

[STREAM] Idle timeout: no data from codex for 600000ms (model: cx/gpt-5.5)

Procure por Idle timeout: no data from com grep (ou pelo código stream_idle_timeout / nome do erro StreamIdleTimeoutError). O segmento do fornecedor corresponde ao que o OmniRoute utilizou nesse pedido (codex, outro ID de fornecedor ou provider caso seja desconhecido) — nem sempre é a cadeia literal codex.

Resolução de problemas

Error: wire_api = "chat" is no longer supported Remova wire_api = "chat" da sua configuração. Defina wire_api = "responses" ou omita o campo (a predefinição é "responses" desde a v0.138).

Error: model not found Verifique se o modelo existe no OmniRoute com o prefixo correto. Utilize omniroute models list ou abra /dashboard/providers/<provider>.

Authentication error Confirme que OMNIROUTE_API_KEY foi exportada: echo $OMNIROUTE_API_KEY.

ERROR: Missing environment variable: OMNIROUTE_API_KEY O Codex valida se a variável de ambiente existe antes de efetuar o primeiro pedido. Exporte uma chave real para servidores protegidos ou um marcador de posição não vazio, como OMNIROUTE_API_KEY=local, quando a sua instância local do OmniRoute não exigir autenticação. Reinicie a shell se a tiver adicionado a ~/.bashrc ou ~/.zshrc.

Connection refused Verifique se o OmniRoute está em execução e se o anfitrião/porta de base_url está correto para a sua rede (local, Tailscale ou VPS).

A sessão termina inesperadamente perto do limite de contexto Defina explicitamente model_context_window e model_auto_compact_token_limit. Consulte a tabela da janela de contexto acima.

A compactação é acionada demasiado tarde Reduza model_auto_compact_token_limit para 80–85% da janela. Nunca o defina acima de 90%.

O perfil não é carregado (-p <name> é silenciosamente ignorado) Confirme que o ficheiro existe em ~/.codex/<name>.config.toml (sem o prefixo profile-). Execute ls ~/.codex/*.config.toml.

Uma tarefa prolongada do Codex é interrompida a meio da execução/muda de conta entre interações Consulte Tarefas de longa duração. Ative a afinidade de sessão (TTL superior à duração da tarefa) e aumente ou desative STREAM_IDLE_TIMEOUT_MS / FETCH_BODY_TIMEOUT_MS. Pesquise Idle timeout: no data from nos registos do OmniRoute.

Navigation Menu

Repository navigation

CODEX-CLI-CONFIGURATION.md

CODEX-CLI-CONFIGURATION.md

Codex CLI — Configuration with OmniRoute (Português (Portugal))

config.toml pronto a colar

macOS: Codex incluído na aplicação ChatGPT

OmniRoute local sem autenticação: uma chave de marcador é suficiente

`wire_api = "responses"` — por que motivo funciona com todos os modelos

Janela de contexto e compactação

Campos de configuração de tokens

Janelas de contexto por modelo

Prefixo dos modelos: `cx/`

Esforço de raciocínio

Orçamento de pensamento do OmniRoute (definição do servidor)

Perfis — configurações com nome por modelo/fluxo de trabalho

Perfis de esforço (o mesmo modelo, diferentes níveis de esforço)

Modelos de pensamento (alto pensamento) — xhigh + resumo detalhado

Bons modelos (bons) — esforço elevado

Modelos simples (simples) — sem esforço de raciocínio

Modelos rápidos — esforço reduzido

Tabela de decisão rápida

Gerar perfis automaticamente com `omniroute setup-codex`

Iniciar o Codex com `omniroute launch-codex`

Novas funcionalidades da CLI do Codex (v0.138–v0.141)

Novos campos de `config.toml` (posteriores à v0.137)

Novos campos de `[model_providers.<id>]`

Autenticação do Amazon Bedrock (v0.140)

Vários servidores

Claude Code — configuração equivalente

Referência rápida — opções da CLI

Tarefas de longa duração

1. Afinidade de sessão — fixar uma conversa a uma conta

2. Tempo limite de inatividade do fluxo — não interromper interações de raciocínio silenciosas

Procedimento concreto — tarefa do Codex com várias horas de duração

Decisão sobre os valores predefinidos (#7287)

Diagnosticar interrupções por inatividade

Resolução de problemas

FilesExpand file tree

CODEX-CLI-CONFIGURATION.md

Latest commit

History

CODEX-CLI-CONFIGURATION.md

File metadata and controls

Codex CLI — Configuration with OmniRoute (Português (Portugal))

config.toml pronto a colar

macOS: Codex incluído na aplicação ChatGPT

OmniRoute local sem autenticação: uma chave de marcador é suficiente

wire_api = "responses" — por que motivo funciona com todos os modelos

Janela de contexto e compactação

Campos de configuração de tokens

Janelas de contexto por modelo

Prefixo dos modelos: cx/

Esforço de raciocínio

Orçamento de pensamento do OmniRoute (definição do servidor)

Perfis — configurações com nome por modelo/fluxo de trabalho

Perfis de esforço (o mesmo modelo, diferentes níveis de esforço)

Modelos de pensamento (alto pensamento) — xhigh + resumo detalhado

Bons modelos (bons) — esforço elevado

Modelos simples (simples) — sem esforço de raciocínio

Modelos rápidos — esforço reduzido

Tabela de decisão rápida

Gerar perfis automaticamente com omniroute setup-codex

Iniciar o Codex com omniroute launch-codex

Novas funcionalidades da CLI do Codex (v0.138–v0.141)

Novos campos de config.toml (posteriores à v0.137)

Novos campos de [model_providers.<id>]

Autenticação do Amazon Bedrock (v0.140)

Vários servidores

Claude Code — configuração equivalente

Referência rápida — opções da CLI

Tarefas de longa duração

1. Afinidade de sessão — fixar uma conversa a uma conta

2. Tempo limite de inatividade do fluxo — não interromper interações de raciocínio silenciosas

Procedimento concreto — tarefa do Codex com várias horas de duração

Decisão sobre os valores predefinidos (#7287)

Diagnosticar interrupções por inatividade

Resolução de problemas

`wire_api = "responses"` — por que motivo funciona com todos os modelos

Prefixo dos modelos: `cx/`

Gerar perfis automaticamente com `omniroute setup-codex`

Iniciar o Codex com `omniroute launch-codex`

Novos campos de `config.toml` (posteriores à v0.137)

Novos campos de `[model_providers.<id>]`