Arquivos de configuração

O Jarvis Code CLI grava todas as preferências de longo prazo — qual modelo usar, qual chave de API preencher, quantos passos um agente pode executar por turno — em arquivos TOML (um formato de configuração em texto puro com estrutura clara). Altere uma vez e a mudança vale em toda inicialização. Configurações de agente e de execução ficam no config.toml; preferências de interface de terminal e de cliente (tema, editor, notificações, atualização automática) ficam em um tui.toml companheiro.

Local padrão: ~/.jarvis-code/config.toml, criado automaticamente na primeira execução.

Local do arquivo de configuração

O CLI lê a configuração de ~/.jarvis-code/config.toml. Para realocar o diretório de dados, sobrescreva-o com a variável de ambiente JARVIS_CODE_HOME:

export JARVIS_CODE_HOME=/caminho/para/jarvis-code-home

O caminho do arquivo de configuração passa a ser $JARVIS_CODE_HOME/config.toml. Independentemente de onde o diretório esteja, o nome do arquivo é sempre config.toml.

TIP

Nomes de campo TOML sempre usam snake_case, por exemplo default_model e max_context_size. Se uma chave contém ., você precisa colocá-la entre aspas — por exemplo [models."gpt-4.1"] — caso contrário o TOML trata o . como separador de tabela aninhada.

Exemplo completo

O exemplo a seguir cobre os campos de configuração mais usados. Você pode copiá-lo e ajustar conforme necessário:

default_model = "jarvis-code/k3"
default_permission_mode = "manual"
default_plan_mode = false
merge_all_available_skills = true
telemetry = false

[providers."managed:jarvis-code"]
type = "kimi"
base_url = "https://api.kimi.com/coding/v1"
api_key = ""

[models."jarvis-code/k3"]
provider = "managed:jarvis-code"
model = "k3"
max_context_size = 1048576
capabilities = [ "thinking", "always_thinking", "image_in", "video_in", "tool_use" ]
display_name = "K3"
support_efforts = [ "low", "high", "max" ]
default_effort = "max"

[models."jarvis-code/kimi-for-coding"]
provider = "managed:jarvis-code"
model = "kimi-for-coding"
max_context_size = 262144
capabilities = [ "thinking", "always_thinking", "image_in", "video_in", "tool_use" ]

[models."jarvis-code/kimi-for-coding-highspeed"]
provider = "managed:jarvis-code"
model = "kimi-for-coding-highspeed"
max_context_size = 262144
capabilities = [ "thinking", "always_thinking", "image_in", "video_in", "tool_use" ]

[thinking]
enabled = true
effort = "high"
keep = "all"

[loop_control]
max_attempts_per_step = 10
reserved_context_size = 50000

[background]
max_running_tasks = 4
keep_alive_on_exit = false

[services.moonshot_search]
base_url = "https://api.kimi.com/coding/v1/search"
api_key = ""

[services.moonshot_fetch]
base_url = "https://api.kimi.com/coding/v1/fetch"
api_key = ""

[[permission.rules]]
decision = "allow"
pattern = "Read"

[[permission.rules]]
decision = "deny"
pattern = "Bash(rm -rf*)"

[[hooks]]
event = "PreToolUse"
matcher = "Bash"
command = "node ~/.jarvis-code/hooks/check-bash.mjs"
timeout = 5

Campos de nível superior

Os campos do arquivo de configuração se dividem em duas categorias: escalares de nível superior, que controlam diretamente o comportamento padrão, e tabelas aninhadas (providers, models, thinking etc.), cada uma com sua própria estrutura, descrita nas seções abaixo.

Campo	Tipo	Padrão	Descrição
default_model	string	—	Alias do modelo padrão; precisa estar definido em models
default_permission_mode	string	manual	Modo de permissão padrão de novas sessões; um entre manual (pergunta a cada vez), yolo (aprova ações de ferramenta automaticamente, mas o agente ainda pode fazer perguntas) ou auto (totalmente autônomo — o agente decide tudo sem perguntar)
default_plan_mode	boolean	false	Se novas sessões começam no Plan mode (produzir um plano antes de executar) por padrão
merge_all_available_skills	boolean	true	Se deve combinar Agent Skills de todos os diretórios disponíveis
extra_skill_dirs	array<string>	—	Diretórios extras de busca de skills, sobrepostos aos diretórios padrão
extra_agent_dirs	array<string>	—	Diretórios extras de busca de agentes personalizados, sobrepostos aos diretórios padrão
builtin_product_skills	boolean	true	Se as skills embutidas que documentam o próprio Jarvis Code são oferecidas ao modelo: update-config, custom-theme, mcp-config, check-jarvis-code-docs e import-from-cc-codex. Desligá-las remove seus nomes e descrições do system prompt, ao custo dos fluxos guiados dessas tarefas. Lido pelo engine padrão agent-core-v2; ignorado quando JARVIS_CODE_LEGACY_FLAG=1 seleciona o engine legado
telemetry	boolean	false	Se a telemetria anônima está habilitada; permanece desabilitada a menos que definida explicitamente como true
providers	table	{}	Tabela de provedores de API → providers
models	table	—	Tabela de aliases de modelo → models
thinking	table	—	Parâmetros padrão do modo de raciocínio → thinking
loop_control	table	—	Parâmetros de controle do loop do agente → loop_control
background	table	—	Parâmetros de execução de tarefas em segundo plano → background
task	table	—	Nome atual das configurações de tarefa em segundo plano; é mesclado sobre [background] quando ambos existem → task
subagent	table	—	Limites de subagente Agent → subagent
swarm	table	—	Limites de subagente AgentSwarm → swarm
secondary_model	table	—	Pool de modelos de subagente → secondary_model
visual_model	table	—	Modelo usado para inspecionar mídia em modelos somente texto → visual_model
workflows	table	—	Limites e diretórios de workflow dinâmico → workflows
mcp	table	—	Tempos limite globais de MCP → mcp
token_counting	table	—	Estratégia de relato do tamanho de contexto → token_counting
tools	table	—	Interruptor global de ferramentas → tools
image	table	—	Parâmetros de compressão de imagem → image
memory	table	—	Limites de memória persistente → memory
services	table	—	Configuração de serviços externos embutidos → services
permission	table	—	Regras iniciais de permissão → permission
hooks	array<table>	—	Hooks de ciclo de vida; veja Hooks
identity	table	—	Identidade personalizada do agente → identity
model_catalog	table	—	Configurações de atualização do catálogo de modelos do provedor → model_catalog
cron	table	—	Configurações de execução de tarefas agendadas → cron
experimental	table<string, boolean>	{}	Sobrescritas por flag de recursos experimentais → experimental

As seções a seguir cobrem cada tabela aninhada por vez.

Nota

O engine lê o config.toml por um registro por seção: uma chave de nível superior desconhecida é repassada intacta em vez de rejeitada, e o jarvis doctor a reporta como aviso. Uma seção registrada que falha no próprio esquema é um erro.

providers

Cada entrada da tabela providers define um provedor de API, identificado por um nome único. O CLI lê credenciais apenas daqui — ele não recorre automaticamente a variáveis de ambiente do shell. Executar export JARVIS_API_KEY no terminal não entrega a chave a provedor nenhum; você precisa escrevê-la explicitamente no arquivo de configuração (veja Sobrescritas de configuração).

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo de provedor: kimi, anthropic, openai, openai_responses, google-genai, vertexai
model_source	"static" | "discover" | "oauth-catalog"	Não	Como o provedor fornece seus modelos
api_key	string	Não	Chave de API, escrita em texto puro no arquivo de configuração
base_url	string	Não	Base URL da API
default_model	string	Não	Identificador de modelo padrão do provedor
oauth	table	Não	Referência de credencial OAuth (campos storage e key); injetada automaticamente pelo fluxo de login — normalmente não é preciso escrevê-la à mão
env	table<string, string>	Não	Fonte de fallback das credenciais do provedor; veja abaixo
custom_headers	table<string, string>	Não	Cabeçalhos HTTP personalizados anexados a cada requisição
source	table<string, unknown>	Não	Metadados de origem do provedor mantidos por importações de catálogo

Subtabela env: você pode escrever os nomes de chave convencionais do provedor (como JARVIS_API_KEY) dentro de [providers.<name>.env] como fonte de fallback para api_key e base_url. Essa subtabela é lida apenas do arquivo de configuração e não modifica o ambiente do shell:

[providers.kimi.env]
JARVIS_API_KEY = "sk-xxx"
JARVIS_BASE_URL = "https://api.moonshot.ai/v1"

Prioridade: campo api_key > chave da subtabela env > se ambos estiverem ausentes, a inicialização falha com erro.

models

Cada entrada da tabela models define um alias de modelo (o nome usado em default_model ou na flag -m), identificado por um nome único.

Campo	Tipo	Obrigatório	Descrição
provider	string	Sim	Nome do provedor a usar; precisa estar definido em providers
model	string	Sim	Identificador de modelo enviado ao servidor ao chamar a API
provider_id	string	Não	Identificador do provedor no catálogo
name	string	Não	Nome do modelo no catálogo
aliases	array<string>	Não	Aliases adicionais do modelo
api_key	string	Não	Chave de API por modelo
oauth	table	Não	Referência de credencial OAuth por modelo
protocol	string	Não	Sobrescrita de protocolo por modelo
max_context_size	integer	Sim	Tamanho máximo de contexto em tokens; precisa ser pelo menos 1
max_input_size	integer	Não	Limite de entrada por requisição declarado quando ele fica abaixo da janela total (por exemplo, gpt-5: janela de 400k, entrada de 272k). Compactação, verificações de estouro de contexto e proporções de uso o preferem; o orçamento de conclusão mantém a janela total. A resolução o limita a max_context_size
max_output_size	integer	Não	Teto de tokens de saída por requisição (mapeia para max_tokens). Hoje apenas o provedor anthropic o respeita. Quando definido para um modelo Claude, este valor explícito supera o máximo embutido do servidor
capabilities	array<string>	Não	Tags de capacidade adicionadas explicitamente: thinking, always_thinking, image_in, video_in, audio_in, tool_use. Unidas às capacidades detectadas automaticamente pelo provedor — entradas só podem ser adicionadas, nunca removidas
support_efforts	array<string>	Não	Níveis de esforço de raciocínio que o modelo aceita. Em kimi, escolher outro valor em execução falha; quando a resolução de modelo carrega um valor configurado ou anterior não suportado, a sessão recorre ao default_effort do modelo alvo e reporta esse valor efetivo à interface. Um modelo Kimi capaz de raciocínio sem este campo usa booleano on / off. Outros provedores repassam valores concretos sem alteração quando o protocolo tem um campo nativo de esforço; protocolos que expõem apenas níveis ou orçamentos de token fazem a conversão necessária. Atualizações de catálogo gerenciado e de plataforma aberta podem reescrever este campo; para fixá-lo manualmente, use [models."<alias>".overrides] support_efforts
default_effort	string	Não	Esforço de raciocínio padrão do modelo. Atualizações de catálogo gerenciado e de plataforma aberta podem reescrever este campo; para fixá-lo manualmente, use [models."<alias>".overrides] default_effort
off_effort	string	Não	Valor de esforço enviado no protocolo para desativar o raciocínio (por exemplo, none no xai grok). Só faz sentido em modelos que declaram essa codificação (importações de catálogo a definem): desligar o raciocínio passa a enviar este valor em vez de omitir o campo de esforço — a única forma de realmente parar o raciocínio em modelos que raciocinam por padrão
base_url	string	Não	Sobrescrita de endpoint por modelo (escrita por importações de catálogo em modelos de gateway servidos fora do padrão do provedor). A resolução a prefere ao base_url do provedor; só vale em conjunto com protocol
display_name	string	Não	Nome exibido na interface; recorre a model quando não definido
reasoning_key	string	Não	Somente provedor openai. Sobrescreve o nome do campo usado para o conteúdo de raciocínio quando o gateway o devolve com um nome fora do padrão; por padrão, reasoning_content, reasoning_details e reasoning são detectados automaticamente
adaptive_thinking	boolean	Não	Somente provedor anthropic. Força o raciocínio adaptativo ligado ou desligado, sobrescrevendo a inferência de versão pelo nome do modelo. Omita para inferir automaticamente (Claude ≥ 4.6 usa adaptativo)
beta_api	boolean	Não	Se este modelo usa a superfície de API beta do provedor

Quando um alias contém ., use uma chave entre aspas:

[models."gpt-4.1"]
provider = "openai"
model = "gpt-4.1"
max_context_size = 1047576

Sobrescritas de modelo

Use [models."<alias>".overrides] para sobrescritas de usuário que precisam sobreviver às atualizações de modelos do provedor. Os consumidores em execução leem o valor efetivo: a sobrescrita quando presente, senão o campo de nível superior.

[models."jarvis-code/kimi-for-coding"]
provider = "managed:jarvis-code"
model = "kimi-for-coding"
max_context_size = 262144

[models."jarvis-code/kimi-for-coding".overrides]
max_context_size = 131072
display_name = "Kimi for Coding (custom)"

O [models."<alias>".overrides] aceita campos comuns de modelo, como max_context_size, max_input_size, max_output_size, capabilities, display_name, reasoning_key, adaptive_thinking, support_efforts, default_effort e off_effort. Ele não aceita campos de identidade e roteamento: provider, model, protocol, beta_api e base_url.

Você também pode trocar de modelo temporariamente sem mexer no arquivo de configuração — definindo variáveis JARVIS_MODEL_*, o CLI sintetiza um provedor temporário em memória que não persiste após reiniciar. Veja Definir um modelo por variáveis de ambiente.

secondary_model

Subagentes herdam por padrão o modelo em que o agente principal roda. A seção [secondary_model] torna isso configurável: ela oferece aos subagentes um pool de modelos candidatos mais um vínculo padrão — tipicamente um modelo mais barato para subtarefas que não precisam da capacidade do modelo principal.

Pool de modelos de subagente

Este recurso é experimental e vem desabilitado por padrão. Habilite-o com JARVIS_CODE_EXPERIMENTAL_SECONDARY_MODEL=1, ou com o mestre JARVIS_CODE_EXPERIMENTAL_FLAG=1; ele vale em todos os modos de inicialização, inclusive na TUI interativa. Com o experimento desligado, as chaves do pool ficam inertes: subagentes herdam o modelo de quem chamou e a inicialização da sessão pula a validação do pool.

A configuração mínima é uma linha — um default_model isolado é um pool de uma entrada só:

[secondary_model]
default_model = "jarvis-code/kimi-for-coding-highspeed"

Campo	Tipo	Padrão	Descrição
default_model	string	—	O modelo padrão dos subagentes
models	table<string, string>	—	Pool de modelos de subagente. Cada chave é o alias de uma entrada [models] configurada; cada valor é a dica de seleção mostrada ao agente principal
force	boolean	false	Fixa todo subagente em default_model, tirando a escolha do agente principal
default_effort	string	—	O esforço de raciocínio que todo subagente criado usa; supera o default_effort da entrada de modelo vinculada

Restrições entre os campos:

• default_model: obrigatório quando uma tabela models está configurada, e precisa ser uma das chaves dela.
• models: os valores podem estar em qualquer idioma; uma string vazia lista o alias sem dica.
• force: exige default_model e não pode ser combinado com uma tabela models — a tabela existe para oferecer escolha, e o force a remove.
• default_effort vale para a seção inteira: toda criação o adota, independentemente da entrada de pool escolhida (ou do modelo forçado). Para esforços por entrada, deixe-o sem definir e use variantes de modelo (veja abaixo).
• primary é um alias reservado (veja abaixo) e não pode ser chave de pool.

Na TUI interativa, o comando /secondary-model (alias /subagent-model) abre um seletor de modelos: a escolha é escrita em default_model (quando existe uma tabela de modelos e o alias escolhido não está nela, uma entrada com descrição vazia é adicionada), e subagentes recém-criados adotam o novo padrão imediatamente — sem reiniciar a sessão.

Um pool configurado — uma tabela models explícita ou um default_model isolado — habilita a seleção de modelo: as ferramentas Agent e AgentSwarm ganham um parâmetro model, e a descrição da ferramenta lista o pool (o padrão marcado com [default]) para o agente principal escolher a cada criação. Chaves de pool só podem referenciar entradas [models] configuradas — os aliases jarvis-code/* abaixo são provisionados pelo /login:

[secondary_model]
default_model = "jarvis-code/kimi-for-coding-highspeed"
[secondary_model.models]
"jarvis-code/k3" = "Escolha para problemas difíceis. Forte em raciocínio complexo, desenho de algoritmos, depuração profunda, matemática e desafios sistemáticos."
"jarvis-code/kimi-for-coding-highspeed" = "Rápido, mas com preço mais alto. Bom para tarefas sensíveis a latência: refatoração diária, explicação de código, pequenas edições e resumos."
"jarvis-code/kimi-for-coding" = "Um cavalo de batalha equilibrado para código. Bom para a maior parte do desenvolvimento de funcionalidades e das tarefas de mudança de código."

Uma criação resolve o modelo do subagente nesta ordem:

1. Um model explícito passado na chamada de ferramenta
2. default_model

Regras do parâmetro model:

• Ele aceita qualquer alias do pool, ou "primary" — o modelo em que o próprio chamador roda, sempre válido mesmo fora do pool.
• Quando nem default_model nem models estão configurados, o parâmetro não é anunciado e subagentes herdam o modelo de quem chamou.
• Vincular um alias do pool não herda o esforço de raciocínio de quem chamou. O default_effort da seção vence quando definido. Caso contrário, [thinking].enabled = false mantém o raciocínio desligado; quando o raciocínio está habilitado, a resolução continua pelo default_effort da entrada de modelo vinculada, pelo [thinking].effort global e então pelo meio de support_efforts do modelo vinculado.
• "primary" herda tanto o modelo quanto o nível de esforço de quem chamou.
• Um valor que não seja um alias do pool nem "primary" faz a criação falhar com um erro listando as opções disponíveis.

Para tirar a escolha do agente principal e rodar todo subagente em um modelo fixo, adicione force = true:

[secondary_model]
default_model = "jarvis-code/kimi-for-coding-highspeed"
force = true

Com force definido, o parâmetro model não é anunciado (como quando nada está configurado) e toda criação vincula default_model; um argumento model explícito, incluindo "primary", é recusado com erro.

Esforços de raciocínio diferentes por entrada do pool

Vincular um alias do pool coloca o subagente no esforço padrão do modelo vinculado. Você pode explorar isso registrando uma entrada "variante" do mesmo modelo subjacente, para o agente principal escolher o nível de raciocínio junto com o alias:

1. Registre uma segunda entrada para o mesmo modelo subjacente em [models], sobrescrevendo apenas default_effort por [models."<alias>".overrides].
2. Liste no pool tanto o alias original quanto o alias da variante.

# "jarvis-code/k3" é provisionado pelo /login (padrão: high); isto registra
# uma variante de esforço máximo do mesmo modelo
[models.k3-max]
provider = "managed:jarvis-code"
model = "k3"
max_context_size = 1048576
capabilities = [ "thinking", "always_thinking", "image_in", "video_in", "tool_use" ]
support_efforts = [ "low", "high", "max" ]

[models.k3-max.overrides]
default_effort = "max"

[secondary_model]
default_model = "jarvis-code/k3"
[secondary_model.models]
"jarvis-code/k3" = "Esforço high por padrão. Bom para a maior parte das tarefas de implementação, análise e interação multiturno."
k3-max = "O mesmo modelo com esforço máximo de raciocínio. Bom para as subtarefas mais difíceis."

Dois pré-requisitos:

• O modelo subjacente precisa declarar support_efforts (em managed:jarvis-code, hoje apenas a família k3 declara níveis de esforço).
• A variante é uma entrada independente e não herda campos da entrada para a qual aponta — copie capabilities, support_efforts e os demais metadados por completo, senão o default_effort não tem efeito (ele precisa ser membro de support_efforts).

Note a assimetria entre o agente principal e subagentes vinculados ao pool: para o agente principal, um [thinking].effort global configurado supera o default_effort da variante; para subagentes, o default_effort da variante vence o valor global, e apenas o [secondary_model].default_effort o supera. Regras de valor e de fallback seguem o default_effort da entrada [models].

Nota

Erros de configuração falham de forma visível em vez de recorrer silenciosamente a um fallback. Criação, retomada e bifurcação de sessão falham na inicialização quando:

• default_model está ausente, não é uma chave do pool, ou uma chave do pool não resolve para uma entrada [models] configurada;
• force está definido sem default_model, ou combinado com uma tabela models.

visual_model

O modelo visual é uma configuração de modelo companheiro para trabalho exclusivamente visual — tipicamente um modelo com visão que você fixa para tarefas de inspeção de imagem, captura de tela e vídeo poderem rodar mesmo quando seu modelo principal de código é somente texto. É um vínculo padrão, não forçado: o resolvedor vincula o modelo visual configurado por padrão, e ferramentas que fazem trabalho visual podem expor um parâmetro model aceitando os valores simbólicos "visual" (o modelo visual configurado) e "primary" (o modelo de quem chamou) — o mesmo formato da escolha de modelo de subagente. Quando não definido, tarefas visuais usam o modelo de quem chamou.

Quando definido, o vínculo é ativo: um modelo principal somente texto mantém a ferramenta ReadMediaFile, que delega a inspeção de imagem e vídeo ao modelo visual, e partes de imagem ou vídeo coladas diretamente em uma mensagem são substituídas por uma dica de texto apontando o modelo visual, em vez de fazer a requisição falhar. A interface de terminal aceita mídia colada sempre que o modelo atual a trata diretamente ou há um modelo visual configurado.

Campo	Tipo	Padrão	Descrição
model	string	—	O alias de uma entrada [models] configurada, por exemplo jarvis-code/kimi-vision (qualquer provedor, não apenas modelos Kimi). Deve ser uma entrada com visão (image_in e/ou video_in listados em capabilities)
default_effort	string	—	Esforço de raciocínio aplicado quando tarefas visuais usam o modelo visual. Sem definição, o esforço é resolvido naturalmente (configuração global [thinking] → esforço padrão do modelo vinculado) em vez de herdar o esforço de quem chamou. Segue a semântica de esforço do modelo principal: modelos com validação estrita de esforço (por exemplo, modelos Kimi) recorrem ao esforço padrão em valores não suportados; outros provedores recebem o valor como está
Outros campos	—	—	Aceita todo campo de [models."<alias>".overrides] (max_context_size, max_output_size, support_efforts, …) como um patch de modelo aplicado apenas a tarefas visuais

[visual_model]
model = "jarvis-code/kimi-vision"
default_effort = "low"
max_output_size = 8192

model e default_effort podem ser sobrescritos pelas variáveis de ambiente JARVIS_VISUAL_MODEL e JARVIS_VISUAL_EFFORT, que têm prioridade sobre o config.toml. Enquanto uma sobrescrita de ambiente está definida, ela nunca vaza para o config.toml — escritas restauram o valor bruto sem o ambiente.

Erros de configuração falham de forma visível em vez de recorrer a um fallback silencioso: criação, retomada e bifurcação de sessão falham na inicialização quando model está definido mas não resolve para uma entrada [models] configurada.

thinking

O thinking define o comportamento padrão global do modo de raciocínio.

Campo	Tipo	Padrão	Descrição
enabled	boolean	true	Se o raciocínio vem habilitado por padrão em novas sessões; defina false para forçá-lo desligado
effort	string	—	Nível de esforço de raciocínio (por exemplo low, medium, high, xhigh, max). Provedores que não são Kimi não remapeiam valores concretos de esforço quando o protocolo os aceita; se o provedor recusar o valor, escolha um que o modelo suporte. Protocolos que expõem apenas níveis ou orçamentos de token ainda exigem conversão de formato. Modelos Kimi com support_efforts recorrem ao padrão do modelo quando este valor configurado não está listado; modelos Kimi sem essa lista tratam todo valor habilitado como booleano on
keep	string	"all"	Repasse de raciocínio preservado. Em kimi é enviado como thinking.keep; em anthropic (Claude e o modo compatível com Anthropic do Kimi) é enviado como uma edição context_management clear_thinking_20251015 (habilitar o keep roteia requisições Anthropic para a API Messages beta; um valor de desligamento desativa o keep e volta ao endpoint padrão). "all" preserva o raciocínio de turnos anteriores (reasoning_content / blocos de raciocínio da Anthropic); defina um valor de desligamento (false/0/no/off/none/null) para desativar. Sobrescrito por JARVIS_MODEL_THINKING_KEEP; só é injetado com o raciocínio ligado

Campos depreciados

Campo	Depreciado em	Descrição
default_thinking	0.21.0	Booleano de nível superior, substituído por [thinking] enabled. Migre default_thinking = true para enabled = true, e default_thinking = false para enabled = false.
thinking.mode	0.21.0	Um entre auto / on / off, substituído por [thinking] enabled. mode = "off" vira enabled = false; mode = "on" e mode = "auto" equivalem a enabled = true (o padrão) e podem ser removidos.
loop_control.max_retries_per_step	0.32.0	Substituído por loop_control.max_attempts_per_step (o valor sempre foi um limite de tentativas totais, incluindo a primeira). A chave antiga é ignorada e gera um aviso na inicialização; renomeie-a no config.toml.
loop_control.max_steps_per_run	0.32.0	Substituído por loop_control.max_steps_per_turn. A chave antiga é ignorada e gera um aviso na inicialização; renomeie-a no config.toml.

loop_control

O loop_control rege o limite de passos, o limite de tentativas por passo e o limiar que dispara a compactação automática de contexto no loop de execução do agente.

Campo	Tipo	Padrão	Descrição
max_steps_per_turn	integer	—	Máximo de passos por turno; sem definição ou 0 significa ilimitado
max_attempts_per_step	integer	10	Máximo de tentativas totais de um passo que falha, incluindo a primeira
reserved_context_size	integer	—	Quantidade de tokens reservada para a saída do modelo; a compactação automática é disparada quando a janela de contexto restante cai abaixo deste valor

O max_steps_per_turn pode ser sobrescrito pela variável de ambiente JARVIS_LOOP_MAX_STEPS_PER_TURN, e o max_attempts_per_step por JARVIS_LOOP_MAX_ATTEMPTS_PER_STEP; ambas têm prioridade sobre o arquivo de configuração. A antiga variável JARVIS_LOOP_MAX_RETRIES_PER_STEP está depreciada, mas ainda é honrada (com aviso na inicialização) quando a nova não está definida.

As tentativas só se aplicam a falhas transitórias — erros de conexão, tempos limite, limites de taxa HTTP 429 e erros 5xx de servidor. Um 429 causado por cota esgotada ou saldo insuficiente na conta não é repetido e falha imediatamente, já que não pode ter sucesso até a conta ser recarregada.

token_counting

O token_counting seleciona qual contagem de tokens de contexto é reportada externamente — o valor por trás da exibição de tamanho de contexto. A lógica interna (disparos de compactação automática, orçamentos e recuo por estouro) sempre usa tanto o uso reportado pelo provedor quanto estimativas, independentemente deste ajuste.

Campo	Tipo	Padrão	Descrição
strategy	"measured+estimated" | "measured" | "estimated"	"measured+estimated"	measured+estimated reporta o tamanho ao vivo — o uso reportado pelo provedor em cada troca mais uma estimativa da cauda ainda não medida — com piso no último total medido; measured reporta apenas o uso do provedor, então a exibição só se move quando uma troca termina; estimated reporta uma estimativa pura, ignorando o uso do provedor — o recurso para provedores que não reportam uso ou o reportam de forma não confiável

O strategy pode ser sobrescrito pela variável de ambiente JARVIS_TOKEN_COUNTING_STRATEGY, que tem prioridade sobre o config.toml.

background

O background controla o comportamento de concorrência das tarefas em segundo plano (lançadas pela ferramenta Bash ou pelo parâmetro run_in_background=true da ferramenta Agent).

Alterado

Esta seção agora se chama task. O background continua funcionando e mantém os mesmos campos; quando as duas tabelas existem, o [task] vence chave por chave.

Campo	Tipo	Padrão	Descrição
max_running_tasks	integer	—	Número máximo de tarefas em segundo plano rodando ao mesmo tempo
keep_alive_on_exit	boolean	false	Se deve manter tarefas em segundo plano ainda em execução quando a sessão fecha. Por padrão, o Jarvis Code pede que todas as tarefas parem antes de o processo sair; defina como true apenas quando quiser que as tarefas sobrevivam à sessão. No modo de prompt (jarvis -p), este é apenas um fallback legado usado quando print_background_mode não está definido: true equivale a print_background_mode = "drain"
kill_grace_period_ms	integer	5000	Período de tolerância em milissegundos depois que o fechamento da sessão, uma parada manual ou o tempo limite de uma tarefa pedem encerramento gracioso. Se a tarefa ainda estiver rodando depois desse período, o Jarvis Code tenta encerrá-la à força
bash_auto_background_on_timeout	boolean	true	Quando um comando Bash em primeiro plano atinge o tempo limite, move-o para uma tarefa em segundo plano em vez de encerrá-lo — o agente é notificado quando ele termina, e o comando movido fica limitado pelo tempo padrão de bash_task_timeout_s. Defina false para encerrar comandos em primeiro plano no tempo limite
bash_task_timeout_s	integer	600	Tempo limite padrão (segundos) de tarefas Bash em segundo plano quando a chamada omite timeout; também usado ao rearmar comandos de primeiro plano movidos para segundo plano no tempo limite. 0 significa sem tempo limite — a tarefa roda até sair ou o modelo pará-la. Valores explícitos de timeout por chamada não são afetados. No modo de prompt (jarvis -p) o padrão é 0, a menos que definido explicitamente
print_background_mode	"exit" | "drain" | "steer"	"steer"	Somente modo de prompt (jarvis -p). Rege como as tarefas em segundo plano pendentes são tratadas quando o turno do agente principal termina: "exit" sai imediatamente; "drain" espera toda tarefa em segundo plano atingir um estado terminal antes de sair (os resultados não voltam ao agente principal); "steer" mantém o processo vivo para que uma tarefa concluída — como um subagente em segundo plano — injete uma mensagem de usuário sintética que direciona o agente principal a um novo turno, repetindo até um turno terminar sem tarefas pendentes ou um limite ser atingido. Tem precedência sobre o fallback de impressão de keep_alive_on_exit
print_wait_ceiling_s	integer	2147483	No modo de prompt (jarvis -p), o teto de relógio (segundos) do laço de espera/direção quando print_background_mode é "drain" ou "steer" (o padrão é cerca de 24,8 dias — efetivamente ilimitado). Não tem efeito fora do modo de prompt nem quando o valor é "exit"
print_max_turns	integer	100000	No modo de prompt (jarvis -p) com print_background_mode = "steer", o número máximo de novos turnos que conclusões de tarefa em segundo plano podem disparar, para manter o laço de direção limitado (o padrão é efetivamente ilimitado)

O keep_alive_on_exit pode ser sobrescrito pela variável de ambiente JARVIS_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT, e o max_running_tasks por JARVIS_CODE_BACKGROUND_MAX_RUNNING_TASKS; ambas têm prioridade sobre o config.toml.

No modo de prompt (jarvis -p "<prompt>"), o Jarvis Code permanece vivo depois do turno do agente principal enquanto houver tarefas em segundo plano pendentes: cada conclusão volta ao agente principal como mensagem de usuário sintética, direcionando-o a um novo turno (print_background_mode = "steer" por padrão), e a execução termina quando um turno acaba sem nada pendente. O laço é limitado por print_wait_ceiling_s e print_max_turns, ambos efetivamente ilimitados por padrão. O trabalho em segundo plano também nunca é encerrado por um teto de relógio no modo de prompt: tarefas Bash em segundo plano têm padrão sem tempo limite (bash_task_timeout_s = 0), e subagentes rodam sem tempo limite ([subagent] timeout_ms e [swarm] timeout_ms ambos com padrão 0, a menos que definidos explicitamente).

task

O task é o nome atual da seção de tarefas em segundo plano. Ele aceita exatamente os mesmos campos de background; o background é mantido como alias depreciado para os arquivos de configuração existentes continuarem funcionando.

Quando as duas tabelas existem, elas são mescladas com o [task] vencendo chave por chave:

[background]
max_running_tasks = 4
kill_grace_period_ms = 5000

[task]
kill_grace_period_ms = 10000

A configuração efetiva acima é max_running_tasks = 4 e kill_grace_period_ms = 10000. Prefira escrever apenas [task] em arquivos de configuração novos.

subagent

O subagent controla como rodam os subagentes criados pela ferramenta Agent.

Campo	Tipo	Padrão	Descrição
timeout_ms	integer	7200000 (2 horas)	Tempo máximo de relógio (milissegundos) que um subagente Agent pode rodar antes de ser encerrado como timed_out. 0 significa sem tempo limite — o subagente roda até terminar ou o modelo pará-lo. Este é o tempo limite por tarefa do gerenciador de tarefas em segundo plano para cada tarefa de subagente, então vale tanto em primeiro plano quanto em segundo plano. No modo de prompt (jarvis -p) o padrão é 0, a menos que definido explicitamente. Observação: qualquer valor acima de 2147483647 (cerca de 24,8 dias) é limitado pelo runtime a aproximadamente 24,8 dias

O timeout_ms pode ser sobrescrito pela variável de ambiente JARVIS_SUBAGENT_TIMEOUT_MS, que tem prioridade sobre o config.toml.

workflows

O workflows ajusta os limites de execução dos workflows dinâmicos e declara diretórios extras de workflow.

Campo	Tipo	Padrão	Descrição
max_concurrency	integer	4	Número máximo de subagentes que um workflow executa concorrentemente (1–16)
max_agent_calls	integer	50	Número máximo de chamadas de agent() que uma execução de workflow pode fazer
max_duration_ms	integer	1800000 (30 minutos)	Tempo máximo de relógio (milissegundos) de uma execução de workflow
max_script_bytes	integer	262144 (256 KB)	Tamanho máximo em bytes de um arquivo de script de workflow; arquivos maiores são ignorados na descoberta
extra_workflow_dirs	array<string>	—	Diretórios adicionais de workflow, varridos no escopo extra (entre a precedência de usuário e a de embutidos)

swarm

O swarm controla como rodam os subagentes lançados pela ferramenta AgentSwarm, de forma independente de [subagent].

Campo	Tipo	Padrão	Descrição
timeout_ms	integer	7200000 (2 horas)	Tempo máximo de relógio (milissegundos) que um subagente AgentSwarm pode rodar. No tempo limite, aquele subagente é abortado e marcado como falho no relatório agregado (Subagent timed out.); os demais não são afetados. 0 significa sem tempo limite — o subagente roda até terminar ou o modelo pará-lo. No modo de prompt (jarvis -p) o padrão é 0, a menos que definido explicitamente. Observação: qualquer valor acima de 2147483647 (cerca de 24,8 dias) é limitado pelo runtime a aproximadamente 24,8 dias

O timeout_ms pode ser sobrescrito pela variável de ambiente JARVIS_CODE_SWARM_TIMEOUT_MS, que tem prioridade sobre o config.toml.

model_catalog

O model_catalog controla com que frequência o CLI atualiza a lista de modelos dos provedores que publicam uma (provedores gerenciados e importações de registro).

Campo	Tipo	Padrão	Descrição
refresh_interval_ms	integer	—	Intervalo mínimo em milissegundos entre duas atualizações de catálogo. 0 desativa a verificação de intervalo, então toda inicialização elegível atualiza
refresh_on_start	boolean	—	Se deve atualizar o catálogo quando o engine inicia

cron

O cron controla o agendador por trás das ferramentas de tarefa agendada. Todo campo também está ligado a uma variável de ambiente, que tem prioridade sobre o arquivo de configuração.

Campo	Tipo	Padrão	Variável de ambiente	Descrição
disabled	boolean	false	JARVIS_DISABLE_CRON	Desativa completamente as tarefas agendadas; as ferramentas CronCreate, CronList e CronDelete param de disparar
no_jitter	boolean	false	JARVIS_CRON_NO_JITTER	Dispara exatamente na expressão cron em vez de aplicar o deslocamento determinístico que distribui a carga
no_stale	boolean	false	JARVIS_CRON_NO_STALE	Nunca marca uma tarefa recorrente de vida longa como obsoleta, de modo que ela não é apagada automaticamente após 7 dias
debug	boolean	false	JARVIS_CRON_DEBUG	Emite log de depuração do agendador
manual_tick	boolean	false	JARVIS_CRON_MANUAL_TICK	Interrompe o laço automático de consulta; os ticks precisam ser acionados manualmente. Voltado a testes
clock	string	—	JARVIS_CRON_CLOCK	Sobrescreve o relógio do agendador. Voltado a testes
poll_interval_ms	integer | null	—	JARVIS_CRON_POLL_INTERVAL_MS	Intervalo de consulta em milissegundos; null desativa a consulta

As variáveis de ambiente booleanas desta seção são interruptores estritos: 1 habilita, qualquer outra coisa deixa o valor sem definição.

mcp

Campo	Tipo	Padrão	Descrição
startup_timeout_ms	integer	30000 (30 segundos)	Tempo limite global padrão de conexão (inicialização mais descoberta de ferramentas) em milissegundos para todos os servidores MCP. Aceita de 1 a 2147483647. Um startupTimeoutMs por servidor no mcp.json sempre vence esta seção e a variável de ambiente; quando nenhum está definido, o padrão se aplica
tool_timeout_ms	integer	60000 (60 segundos)	Tempo limite global padrão de uma chamada de ferramenta em milissegundos para todos os servidores MCP. Aceita de 1 a 2147483647. Um toolTimeoutMs por servidor no mcp.json sempre vence esta seção e a variável de ambiente; quando nenhum está definido, o padrão embutido do cliente se aplica

O startup_timeout_ms e o tool_timeout_ms podem ser sobrescritos pelas variáveis de ambiente JARVIS_MCP_STARTUP_TIMEOUT_MS e JARVIS_MCP_TOOL_TIMEOUT_MS, respectivamente, que têm prioridade sobre o config.toml. Veja MCP para a configuração completa de servidores MCP.

identity

Personaliza como o agente se identifica. Deixe sem definir e nada muda.

Campo	Tipo	Padrão	Descrição
name	string	—	Nome de exibição pelo qual o agente se identifica no system prompt (preenche o espaço ${product_name}, inclusive no seu próprio SYSTEM.md e nos arquivos de agente)
slug	string	derivado de name	Identificador de máquina usado em campos de protocolo: o token de produto do User-Agent enviado a provedores de terceiros e o nome de cliente anunciado a servidores MCP. Derivado de name quando omitido: em minúsculas, com toda sequência de caracteres não alfanuméricos virando -

[identity]
name = "Acme Dev Agent"
slug = "acme-dev"        # opcional

Os dois campos podem ser definidos pelas variáveis de ambiente JARVIS_CODE_IDENTITY_NAME e JARVIS_CODE_IDENTITY_SLUG, que têm prioridade sobre o config.toml e nunca são escritas de volta nele — conveniente para contêineres e CI, onde escrever um arquivo de configuração é incômodo.

Um nome sem letras ou dígitos ASCII não deixa nada para derivar um slug e recorre a agent; escreva slug explicitamente se você precisa de um token de protocolo específico.

A identidade é resolvida uma vez na inicialização e vale por toda a vida do processo — ela é anunciada a servidores MCP e provedores quando as conexões são feitas, então não pode mudar no meio. Edições nesta seção valem na próxima inicialização, para sessões novas: uma sessão retomada mantém o system prompt com que foi registrada, já que seus turnos anteriores já falam sob aquela identidade. Do mesmo modo, uma autorização OAuth de MCP mantém o registro de cliente sob o qual foi concedida; redefina a autenticação daquele servidor para registrar sob a nova identidade.

Esta seção é lida pelo engine padrão agent-core-v2. Ela é ignorada pelo caminho legado de jarvis e jarvis -p selecionado com JARVIS_CODE_LEGACY_FLAG=1; o jarvis server sempre usa o agent-core-v2.

tools

O tools é o interruptor global de ferramentas: ele vale para todo agente em todas as sessões e se intersecta com a política tools / disallowedTools de cada agente.

Campo	Tipo	Padrão	Descrição
enabled	array<string>	—	Lista global de permitidas: quando não vazia, apenas as ferramentas listadas ficam disponíveis; omitir o campo ou usar um array vazio não impõe restrição
disabled	array<string>	—	Lista global de bloqueadas, aplicada depois de enabled

A correspondência de nomes segue as mesmas regras dos campos homônimos de um arquivo de agente: ferramentas embutidas casam por nome exato (como Read) e ferramentas MCP casam por globs (como mcp__github__*). Três formatos de entrada nunca correspondem a nada e são reportados com um aviso: um curinga fora de um padrão mcp__ (enabled = ["*"] desabilita todas as ferramentas, disabled = ["*"] não desabilita nenhuma), um literal mcp__ sem o segmento de ferramenta (mcp__github — use mcp__github__* para um servidor inteiro) e um nome que nenhuma ferramenta registrada ou embutida possui (a correspondência diferencia maiúsculas).

[tools]
disabled = ["EnterPlanMode", "ExitPlanMode", "mcp__github__*"]

Nota

Como os campos tools / disallowedTools de um arquivo de agente, esta seção molda as ferramentas mostradas ao modelo e é aplicada novamente antes da execução. As regras de permissão continuam sendo um controle separado para operações que exigem aprovação.

image

O image controla como as imagens são comprimidas antes de serem enviadas ao modelo, em todos os pontos de entrada (imagens coladas, leituras de ReadMediaFile, imagens em resultados de ferramenta MCP e assim por diante).

Campo	Tipo	Padrão	Descrição
max_edge_px	integer	2000	Teto do lado maior em pixels. Imagens maiores são reduzidas proporcionalmente para caber; aumentá-lo preserva mais detalhe ao custo de corpos de requisição maiores
read_byte_budget	integer	262144 (256 KB)	Orçamento de bytes por imagem nas imagens que o próprio modelo lê (leituras padrão de ReadMediaFile). Ele limita o tamanho acumulado do corpo de requisição quando o modelo fica capturando e lendo imagens; o detalhe fino continua acessível pelo parâmetro region, que lê um recorte em fidelidade total (region e full_resolution não estão sujeitos a este orçamento)

O max_edge_px pode ser sobrescrito pela variável de ambiente JARVIS_IMAGE_MAX_EDGE_PX e o read_byte_budget por JARVIS_IMAGE_READ_BYTE_BUDGET; ambas têm prioridade sobre o config.toml.

memory

A tabela [memory] contém os limites usados pela memória persistente no engine v2 e o interruptor da extração automática. A memória persistente é uma capacidade nativa do engine v2 sempre ligada; não há um campo enabled para a capacidade em si, mas o extraction_enabled abaixo controla a extração automática (ligada por padrão).

Campo	Tipo	Padrão	Descrição
recall_max_entries	integer	5	Máximo de entradas de memória selecionadas em uma recuperação
recall_max_bytes_per_entry	integer	4096	Máximo de bytes UTF-8 renderizados do corpo de uma entrada recuperada
recall_max_session_bytes	integer	61440	Máximo de bytes UTF-8 do envelope completo de memória recuperada em uma injeção
extraction_max_turns	integer	5	Máximo de turnos recentes do usuário incluídos em uma execução de extração automática
extraction_enabled	boolean	true	Se a extração automática de memória está habilitada (ao fim de um turno e ao fim da execução ou da sessão); quando false, nenhuma extração roda e nenhum rascunho é escrito, e reabilitar retoma de onde parou

[memory]
recall_max_entries = 5
recall_max_bytes_per_entry = 4096
recall_max_session_bytes = 61440
extraction_max_turns = 5
extraction_enabled = true

A extração automática é uma capacidade nativa do engine v2 que roda após cada turno concluído — tanto para o agente principal quanto para subagentes — e de novo ao fim da execução e quando a sessão fecha, para nada deixado pelo último turno se perder. Memórias extraídas nunca vão para o escopo user: o escopo é normalizado para project quando o workspace é confiável e para workspace caso contrário, e subagentes só podem persistir em workspace ou project. A ferramenta Memory explícita não é afetada e mantém os três escopos.

Ela sanitiza rascunhos seguros e os persiste automaticamente, excluindo duplicatas já visíveis no catálogo de memória e duplicatas dentro da mesma execução. Um turno em que o agente já escreveu memória com sucesso pela ferramenta Memory é pulado em vez de extraído. Falhas transitórias de persistência mantêm os rascunhos afetados para nova tentativa após um turno concluído posterior; erros terminais de memória (como escritas de projeto em workspace não confiável) são descartados em vez de repetidos. Essa deduplicação não fornece idempotência atômica entre processos. A extração nunca envia ao modelo conteúdo de transcrição com formato de credencial, e os rascunhos são censurados e recusados de novo antes da persistência.

experimental

O experimental guarda sobrescritas persistentes, por flag, de recursos experimentais. Cada chave é um id de flag e cada valor é um booleano; a tabela é livre, então uma flag que esta versão não registra é simplesmente ignorada.

[experimental]
tower = true
search_worker = false

A ordem de resolução de uma flag é: a variável de ambiente dela > esta seção > o padrão registrado da flag. O interruptor mestre JARVIS_CODE_EXPERIMENTAL_FLAG=1 habilita todas as flags registradas no processo.

O painel /experiments da TUI escreve nesta seção, então raramente é preciso editá-la à mão. Para o inventário de flags, os ids, as variáveis de ambiente e os padrões, veja Flags experimentais.

services

O services configura a busca web embutida, a busca de página e o reordenamento opcional de resultados. As tabelas reconhecidas são:

• moonshot_search: backend de busca web da Moonshot.
• moonshot_fetch: backend de busca de página da Moonshot.
• langsearch: backend de busca web da LangSearch.
• brave: backend de busca web do Brave Search.
• rerank: reordenador semântico opcional que pode reordenar resultados de qualquer backend de busca.

Junto das tabelas de backend, o campo active_search_provider de [services] seleciona qual backend serve o WebSearch: brave, langsearch ou moonshot.

O Brave Search não é selecionado automaticamente: configure uma chave de API em [services.brave] e selecione o Brave explicitamente com active_search_provider = "brave" ou jarvis search set brave. A busca web da LangSearch funciona do mesmo jeito: configure uma chave de API em [services.langsearch] e selecione-a explicitamente com active_search_provider = "langsearch" ou jarvis search set langsearch. A busca da Moonshot continua disponível quando nenhuma das duas é o provedor ativo. No engine padrão agent-core-v2, selecionar um provedor de busca é atômico: o backend selecionado precisa ter uma chave de API válida, ou sua implementação de WebSearch e suas ferramentas especializadas ficam indisponíveis; não há fallback para outro backend.

Quando active_search_provider indica um backend, aquele backend serve o WebSearch sem fallback: se as credenciais dele estiverem ausentes, a busca web simplesmente fica indisponível. Quando active_search_provider está ausente, o runtime mantém a precedência legada — LangSearch configurada primeiro, depois Moonshot configurada, depois o serviço gerenciado de busca por OAuth do Jarvis Code. Executar jarvis search set brave ou jarvis search set langsearch configura e seleciona o backend (escreve active_search_provider), migrando configurações antigas para a seleção explícita.

Na TUI, Settings → Web Search mostra os provedores atuais de busca e de rerank no topo. O Web search provider apenas configura ou edita Moonshot, LangSearch ou Brave — ele preserva a seleção atual e não troca o backend ativo. Use o Active web search provider para trocar explicitamente qual backend configurado serve o WebSearch, e o Rerank provider para configurar, habilitar, desabilitar, editar ou remover o reordenamento semântico de forma independente. Configurar o Moonshot pode reaproveitar o login OAuth atual do Jarvis Code ou configurar uma chave de API para a região de API da China ou Global.

Serviços Moonshot

O moonshot_search e o moonshot_fetch aceitam os mesmos campos:

Campo	Tipo	Obrigatório	Descrição
base_url	string	Não	URL da API do serviço
api_key	string	Não	Chave de API
oauth	table	Não	Referência de credencial OAuth, mesma estrutura de providers.*.oauth
custom_headers	table<string, string>	Não	Cabeçalhos HTTP personalizados anexados a cada requisição

O base_url e o api_key também podem vir de variáveis de ambiente, que têm prioridade sobre o arquivo de configuração: JARVIS_WEB_SEARCH_BASE_URL / JARVIS_WEB_SEARCH_API_KEY para moonshot_search, e JARVIS_WEB_FETCH_BASE_URL / JARVIS_WEB_FETCH_API_KEY para moonshot_fetch. Uma base URL vinda do ambiente define um endpoint de serviço separado, então a chave de API persistida, a referência OAuth e os cabeçalhos personalizados não são encaminhados a ele; defina a chave de API de ambiente correspondente quando esse endpoint exigir autenticação. Uma chave de API de ambiente sem base URL de ambiente mantém o endpoint configurado e os cabeçalhos personalizados, mas substitui as duas formas de credencial configuradas. Definir a base URL e a chave de API por ambiente sem nenhuma seção de configuração também habilita o serviço.

[services.moonshot_search]
base_url = "https://api.moonshot.cn/v1/search"
api_key = "sk-xxx"

[services.moonshot_fetch]
base_url = "https://api.moonshot.cn/v1/fetch"
api_key = "sk-xxx"

Busca web da LangSearch

O langsearch chama a LangSearch Web Search API. Configure-o em Settings → Web Search na TUI, com jarvis search set langsearch, ou editando o config.toml.

Campo	Tipo	Padrão	Descrição
api_key	string	—	Chave de API da LangSearch; obrigatória para ativar este backend
base_url	string	https://api.langsearch.com	Base URL da API
tier	string	free	Camada de limite de taxa: free, tier1, tier2 ou tier3
freshness	string	noLimit	Filtro de idade dos resultados enviado à LangSearch: oneDay, oneWeek, oneMonth, oneYear ou noLimit
summary	boolean	true	Solicita resumos gerados e os usa como trechos de resultado quando disponíveis
count	integer	10	Número de resultados por requisição, de 1 a 10
custom_headers	table<string, string>	—	Cabeçalhos HTTP personalizados anexados a cada requisição

Brave search

O brave chama a Brave Search API. Ele exige seleção explícita e uma chave de API válida. Configure-o em Settings → Web Search na TUI, com jarvis search set brave, ou editando o config.toml. Executar jarvis search set brave também o seleciona (active_search_provider = "brave"); na TUI, configure-o primeiro em Web search provider e então troque para ele com Active web search provider.

Campo	Tipo	Padrão	Descrição
api_key	string	—	Chave de API do Brave Search; obrigatória para ativar este backend
base_url	string	https://api.search.brave.com/res/v1	Base URL da API
custom_headers	table<string, string>	—	Cabeçalhos HTTP personalizados anexados a cada requisição

[services]
active_search_provider = "brave"

[services.brave]
api_key = "YOUR_API_KEY"

Quando o Brave é o backend ativo e sua chave de API é válida, o WebSearch é servido pelo Brave, e o engine v2 também disponibiliza um conjunto de ferramentas Brave especializadas. Veja Ferramentas do Brave search para a lista. Obtenha uma chave de API e consulte os limites de taxa por endpoint no painel oficial da Brave Search API; preços e cotas são definidos pelo Brave, não pelo Jarvis Code.

Reordenamento semântico

O rerank é independente do backend de busca selecionado. Quando habilitado, ele envia os resultados de busca ao reordenador semântico configurado depois que o backend ativo (Brave, LangSearch ou Moonshot) os devolve. O reordenamento é feito na medida do possível: se a requisição de rerank falha, a ordem original dos resultados é preservada.

Campo	Tipo	Padrão	Descrição
enabled	boolean	true	Se deve reordenar os resultados de busca
provider	string	—	Provedor de rerank; hoje apenas langsearch é suportado
api_key	string	—	Chave de API do rerank; quando omitida, reaproveita services.langsearch.api_key
base_url	string	https://api.langsearch.com	Base URL da API de rerank
custom_headers	table<string, string>	—	Cabeçalhos HTTP personalizados anexados a cada requisição

O exemplo a seguir ativa a busca da LangSearch e a LangSearch Semantic Rerank API:

[services.langsearch]
api_key = "YOUR_API_KEY"
tier = "free"
count = 10

[services.rerank]
enabled = true
provider = "langsearch"
# api_key = "YOUR_RERANK_API_KEY" # Omita para reaproveitar services.langsearch.api_key

Use jarvis search status para inspecionar a configuração atual, jarvis search use <provider> para trocar o backend ativo, jarvis search clear langsearch / jarvis search clear brave para remover um backend, e jarvis search clear rerank para remover as configurações de rerank. Esses comandos atualizam o config.toml diretamente.

permission

O permission define regras de permissão carregadas automaticamente quando uma sessão começa, controlando se o agente precisa de confirmação do usuário antes de chamar uma ferramenta. As regras são escritas como um array de tabelas [[permission.rules]], avaliadas em ordem — a primeira regra que casa vale.

Campo	Tipo	Obrigatório	Descrição
decision	string	Sim	Ação ao casar: allow (permite imediatamente), deny (rejeita imediatamente), ask (pergunta a cada vez)
scope	string	Não	Escopo da regra: turn-override, session-runtime, project, user; o padrão é user
pattern	string	Sim	Padrão de correspondência na forma ToolName ou ToolName(arg-pattern), por exemplo Read ou Bash(rm -rf*)
reason	string	Não	Descrição da regra, para depuração e auditoria

Os nomes de ferramentas embutidas estão em Ferramentas integradas. A maioria das ferramentas embutidas que aceitam argumentos de regra define seu próprio sujeito de correspondência, como Bash(command-pattern) ou Read(path-pattern). O AgentSwarm, as ferramentas MCP e as ferramentas personalizadas só podem ser correspondidos por nome de ferramenta — padrões de argumento não são suportados para eles.

[[permission.rules]]
decision = "allow"
pattern = "Read"

[[permission.rules]]
decision = "allow"
pattern = "Grep"

[[permission.rules]]
decision = "deny"
pattern = "Bash(rm -rf*)"

[[permission.rules]]
decision = "ask"
pattern = "Bash"

TIP

Declarações de servidor MCP são configuradas em ~/.jarvis-code/mcp.json ou no .jarvis-code/mcp.json local do projeto, não no config.toml. O ponto de entrada de configuração interativa é o /mcp-config; veja Model Context Protocol.

tui.toml

Ao lado do config.toml, o CLI mantém preferências de interface de terminal e de cliente em um tui.toml companheiro, no mesmo diretório (~/.jarvis-code/tui.toml, ou $JARVIS_CODE_HOME/tui.toml quando sobrescrito). Ele é criado com valores padrão na primeira execução, e os comandos interativos /config, /theme e /editor escrevem nele por você — então raramente é preciso editá-lo à mão. Se o arquivo estiver malformado, o CLI recorre aos padrões e mostra um aviso, em vez de falhar ao iniciar.

Campo	Tipo	Padrão	Descrição
theme	string	auto	Tema de cores: auto (segue o terminal), dark, light, ou o nome de um tema personalizado
render_latex	boolean	true	Renderiza expressões matemáticas LaTeX ($…$, $$…$$) em mensagens Markdown como texto Unicode; false mantém o código-fonte bruto
disable_paste_burst	boolean	false	Desativa o fallback de colagem em rajada não delimitada, que evita que colagens rápidas de várias linhas sejam enviadas linha a linha
cache_expiry_hint	boolean	true	Mostra um diálogo ao retomar uma sessão parada há muito tempo ou ao enviar após uma longa inatividade, avisando que o cache de contexto provavelmente expirou e oferecendo compactar ou iniciar uma nova sessão (apenas engine v2)
banner	boolean	false	Mostra o banner promocional remoto abaixo do painel de boas-vindas na inicialização
[editor].command	string	""	Comando de editor externo para compor entradas longas; vazio recorre a $VISUAL / $EDITOR
[notifications].enabled	boolean	true	Se notificações de desktop são enviadas
[notifications].notification_condition	string	unfocused	Quando notificar: unfocused (apenas quando o terminal não está em foco) ou always
[upgrade].auto_install	boolean	true	Se novas versões são instaladas automaticamente
[status_line].items	string[]	[]	Espaços embutidos a exibir na primeira linha do rodapé e sua ordem: mode, goal, model, tasks, cwd, git, tips. Sem definição, mantém o layout padrão; ids desconhecidos são pulados com um aviso
[status_line].command	string	""	Comando de linha de status personalizada. A primeira linha do stdout dele substitui a primeira linha do rodapé, com um instantâneo JSON (modelo, cwd, branch git, modo de permissão, Plan mode, uso de contexto, id de sessão, versão) passado no stdin. As execuções são limitadas a 300ms e reguladas a uma por segundo; falhas recorrem ao layout embutido

# ~/.jarvis-code/tui.toml
theme = "auto" # "auto" | "dark" | "light" | nome de tema personalizado
render_latex = true # false mantém a matemática LaTeX das mensagens como código-fonte bruto
disable_paste_burst = false # true desativa o fallback de colagem em rajada não delimitada
cache_expiry_hint = true # false desativa o diálogo de "cache expirado" ao retomar ou enviar após inatividade
banner = false # true mostra o banner promocional remoto abaixo do painel de boas-vindas

[editor]
command = "" # vazio usa $VISUAL / $EDITOR

[notifications]
enabled = true
notification_condition = "unfocused" # "unfocused" | "always"

[upgrade]
auto_install = true

# [status_line]
# items = ["mode", "goal", "model", "tasks", "cwd", "git", "tips"]
# command = "~/.jarvis-code/statusline.sh"

As mudanças valem na próxima inicialização, ou imediatamente com /reload-tui (que recarrega apenas o tui.toml); o /reload recarrega tanto o config.toml quanto o tui.toml.

Configuração local do projeto

Além dos arquivos de nível de usuário em ~/.jarvis-code, o Jarvis Code lê um arquivo de configuração local do projeto em <raiz-do-projeto>/.jarvis-code/local.toml. Ele guarda ajustes específicos de uma cópia de trabalho do projeto e que normalmente não devem ser compartilhados com o time.

O arquivo é criado automaticamente quando você adiciona um diretório de workspace extra com /add-dir e escolhe lembrá-lo para o projeto. Raramente é preciso editá-lo à mão.

[workspace]

A tabela [workspace] agrupa configurações de workspace no nível de projeto:

Campo	Tipo	Obrigatório	Descrição
additional_dir	array<string>	Não	Diretórios de workspace adicionais, guardados como caminhos absolutos. Escrito automaticamente quando você confirma "lembrar este diretório" em /add-dir; lido na inicialização para os diretórios ficarem disponíveis em toda sessão deste projeto

[workspace]
additional_dir = ["/caminho/absoluto/para/compartilhado"]

Como os diretórios são guardados como caminhos absolutos, específicos da sua máquina, recomendamos adicionar .jarvis-code/local.toml ao .gitignore do projeto para ele não ser versionado.

Próximos passos

• Provedores e modelos — exemplos de conexão para cada tipo de provedor (Kimi, Claude, OpenAI, Gemini)
• Sobrescritas de configuração — regras de prioridade entre opções de CLI, arquivo de configuração e variáveis de ambiente
• Variáveis de ambiente — lista completa de variáveis de execução, como JARVIS_CODE_HOME