Configuración

Consulta los archivos, ajustes disponibles y reglas de configuración global y por proyecto.

Ubicaciones de configuración

La configuración global se aplica a todos los espacios:

~/.clarvis/
├── settings.json
├── guard-judge.md
├── memory-policy.md
├── agents/
├── extension-profiles/
├── skills/
└── workflows/

Define $CLARVIS_HOME para sustituir ~/.clarvis. La configuración del espacio se guarda dentro del proyecto:

.clarvis/
├── settings.json
├── guard-judge.md
├── memory-policy.md
├── agents/
├── extension-profiles/
├── skills/
└── workflows/

Las sesiones, trazas, credenciales, cachés y diagnósticos se guardan aparte de estos archivos editables. Usa /storage para inspeccionar y limpiar los datos prescindibles admitidos.

Prioridad

El orden general es: valores integrados, aportaciones de plugins seleccionados por el perfil, configuración global y configuración del espacio. Los ámbitos posteriores prevalecen.

• Los valores simples y la mayoría de los bloques de funciones usan el ámbito más cercano que los defina.
• Proveedores y MCP se combinan por nombre; un ámbito superior sustituye una entrada homónima.
• Las referencias exactas de enabledPlugins y los marketplaces se combinan sin duplicados. Solo builtin:default usa enabledPlugins para activar.
• Los hooks se combinan por orden de ámbito.
• Agentes y flujos se resuelven por nombre; el espacio prevalece sobre el global.

El sandbox se combina por campo. Los valores simples y toolchains.include usan el valor definido más cercano. pass_env, toolchains.exclude y toolchains.extra_paths se unen entre ámbitos; toolchains.excluded_paths elimina rutas adicionales heredadas. Por tanto, una lista local vacía no borra un campo combinado por unión.

La configuración ejecutable y los perfiles ejecutables del espacio quedan retenidos hasta aprobar su huella actual.

Edita los ajustes con seguridad

Para cambios habituales, usa las vistas integradas:

• /settings/providers: proveedores y credenciales.
• /model: modelo por defecto.
• /effort: esfuerzo de razonamiento por defecto.
• /settings/agents: archivos de agentes.
• /settings/defaults: visión y presupuestos por defecto.
• /settings/memory: memoria de ejecución.
• /settings/sandbox: aislamiento nativo de comandos.
• /settings/controls: seguridad, revisión, memoria y retención de planes.
• /extensions: extensiones.
• Desde /extensions, e: selección exacta del conjunto para nuevas ejecuciones.

settings.json exige JSON estricto. Claves desconocidas, comentarios, comas finales o valores anidados inválidos invalidan ese ámbito. /doctor informa del problema y puede ofrecer una reparación que comprueba que el archivo no haya cambiado.

Ajustes principales

Este ejemplo muestra una configuración válida de seguridad y flujos. Combínala con el objeto superior existente en lugar de crear otro documento JSON.

{
  "default_reasoning_effort": "high",
  "guard": {
    "type": "shell",
    "mode": "on",
    "allowed_commands": ["git status", "bun test"],
    "denied_commands": ["git push --force*", "rm -rf /*"]
  },
  "sandbox": {
    "type": "native",
    "enabled": true,
    "availability": "required",
    "filesystem": "workspace-write",
    "network": "host",
    "toolchains": {
      "mode": "auto"
    }
  },
  "plans": {
    "mode": "review",
    "retention": "keep",
    "pending_task_nudges": 3
  },
  "workflows": {
    "max_concurrency": 4,
    "max_total_leaders": 32,
    "budget_tokens": 640000000
  }
}

Claves habituales de nivel superior:

Clave	Finalidad
providers	Conexiones de proveedores con nombre.
default_model	Modelo principal en formato provider/model.
default_vision_model	Modelo opcional para imágenes si el seleccionado no puede leerlas.
default_reasoning_effort	Esfuerzo del principal, de off a max.
budget	Tokens, tiempo y comportamiento al alcanzar límites de ejecución.
agents	Límites de subagentes activos y conservados y de su salida almacenada.
guard	Permisos, denegaciones y revisión de comandos.
sandbox	Disponibilidad nativa, archivos, red y entorno.
memory	Activación, modelo, presupuestos y proveedor de memoria.
plans	Modo de planificación, retención y proveedor.
tasks	Proveedor externo y escrituras, desactivadas por defecto.
workflows	Concurrencia, líderes acumulados y presupuesto conjunto de tokens.
hooks	Comandos del ciclo de vida.
mcpServers	Declaraciones de servidores MCP externos.
enabledPlugins	Lista exacta de activación usada solo por builtin:default.
marketplaces	URL Git de catálogos de plugins.

Atención

No guardes claves de API ni tokens de suscripción en settings.json. Usa el flujo de credenciales de Providers o una referencia al entorno.

El type del sandbox es literalmente "native": Bubblewrap en Linux y Seatbelt en macOS. La inspección resuelve rutas de herramientas de forma pasiva, sin ejecutar binarios para obtener versiones.

Aumenta presupuesto e iteraciones

Clarvis no ofrece un único presupuesto de tokens para toda la sesión. Cada ejecución tiene el suyo; una sesión puede contener muchas. Para gastar más tokens en una tarea, cambia el presupuesto por defecto. Para permitir más turnos de modelo, cambia el iteration_limit del agente.

Aumenta el presupuesto por defecto

Abre /settings/defaults, elige ámbito con Ctrl+T y edita:

• When budget is exceeded: escalate pregunta si quieres continuar; stop detiene al alcanzar el límite.
• Total token limit: entrada y salida acumuladas en toda la ejecución, no en una sola respuesta.

Pulsa Ctrl+S. Se aplica a la siguiente ejecución. Este ejemplo eleva el umbral flexible a 180 millones de tokens:

{
  "budget": {
    "on_exceed": "escalate",
    "total_token_limit": 180000000
  }
}

El valor del producto es 160 millones por ejecución y el máximo del anfitrión por defecto es 200 millones. Un agente puede declarar budget; cuando actúa como agente de entrada, sustituye todo el presupuesto superior. No se combinan campo a campo.

timeout_ms y max_escalations son válidos, pero no aparecen en Defaults. El primero mide inactividad, no duración total. max_escalations solo se admite en escalate; stop lo prohíbe y exige total_token_limit. Añade esos campos manualmente si los necesitas:

{
  "budget": {
    "on_exceed": "escalate",
    "total_token_limit": 180000000,
    "timeout_ms": 600000,
    "max_escalations": 8
  }
}

Aumenta las iteraciones de un agente

Abre /settings/agents, elige ámbito con Ctrl+T, abre el agente, edita Iteration limit y guarda con Ctrl+S. Para cambiar solo este campo de Marshall en el espacio:

---
iteration_limit: 75
---

Guárdalo como .clarvis/agents/marshall.md. El cuerpo vacío conserva el prompt integrado; solo cambia el límite. Los agentes nuevos usan el mismo campo. El valor de respaldo y el máximo por defecto del anfitrión son 200 iteraciones; un perfil puede declarar menos. En escalate, el límite del agente de entrada es un punto de revisión que permite pedir continuidad. Es estricto para subagentes y también en modo stop.

Eleva un límite máximo del anfitrión

Se rechazan los valores que superen el máximo. Si necesitas ampliarlo deliberadamente, defínelo en el entorno que inicia Clarvis y mantén el ajuste correspondiente dentro del nuevo máximo:

CLARVIS_TOKEN_CEILING=400000000 \
CLARVIS_ITERATION_CEILING=400 \
clarvis

Estas variables afectan a ese proceso. Configúralas de forma persistente en el intérprete o lanzador si tus archivos dependen de esos valores tras reiniciar. Elevar el máximo no aumenta por sí solo el presupuesto o las iteraciones activos.

Los otros máximos por defecto son 600.000 ms para timeout_ms y 20 para max_escalations; sus variables son CLARVIS_TIMEOUT_CEILING_MS y CLARVIS_ESCALATION_CEILING.

Consulta el contrato completo de variables de proceso, incluidos reintentos, compactación, concurrencia, MCP, registros, trazas, instalación y diagnóstico, en Variables de entorno.

Recarga los cambios

Muchos ajustes se aplican a la siguiente ejecución. Usa /reconnect cuando Clarvis indique que un cambio de proveedor, plugin o backend necesita recarga. Editar agentes desde la interfaz actualiza la lista disponible.

Control de prompts y memoria

Estos controles tienen finalidades y prioridades distintas. Elige el más específico para el comportamiento que quieras cambiar.

Política editorial de memoria

Indica qué conocimiento merece guardarse con Markdown:

~/.clarvis/memory-policy.md
<workspace>/.clarvis/memory-policy.md

La política global se aplica en todas partes y la del espacio la concreta para un proyecto. Si existen ambas, se usa primero la global y después la local; una no sustituye a la otra. Los cambios afectan al siguiente indexado sin reiniciar.

Escribe criterios editoriales, no instrucciones de almacenamiento:

Keep exact commands when a non-obvious flag is the point of the note.
Record why a workaround exists, not only the workaround.
Do not record customer names or fixture contents from this workspace.

La política decide qué recordar. Clarvis sigue controlando la estructura y el almacenamiento.

Evaluador de comandos

Escribe la política completa en Markdown:

<workspace>/.clarvis/guard-judge.md
~/.clarvis/guard-judge.md

Prevalece el archivo no vacío del espacio, después el global y después el prompt integrado. Se sustituyen entre sí; nunca se concatenan.

Compactación del contexto

Los prompts de compactación pertenecen al archivo de agente, no a settings.json ni a un Markdown independiente:

---
compaction:
  prompt: |
    Preserve accepted decisions, concrete file paths, validation evidence, unresolved risks, and the
    exact next action.
---

Primero se resuelve el agente: archivo aprobado del espacio, global o integrado. Su compaction.prompt sustituye el prompt de resumen; omitirlo conserva el integrado. compaction.prompt_mode: none selecciona el descarte mecánico y no puede combinarse con un prompt propio.

Consulta también

• Extension Profiles
• Variables de entorno
• Ámbitos y confianza
• Proveedores y modelos
• Planes
• Seguridad y control
• Agentes
• Servidores MCP
• Hooks