# Configuración {#configuration}

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

## Ubicaciones de configuración {#configuration-locations}

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

```text
~/.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:

```text
.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 {#precedence}

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 {#edit-settings-safely}

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 {#core-settings}

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.

```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.                                       |

::: warning 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 {#increase-run-budget-and-iteration-limits}

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 {#increase-the-default-run-budget}

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:

```json
{
  "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:

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

### Aumenta las iteraciones de un agente {#increase-an-agent-s-iteration-limit}

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:

```md
---
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 {#raise-a-host-ceiling}

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:

```bash
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](/es-ES/reference/environment-variables).

## Recarga los cambios {#reload-changes}

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 {#prompt-and-memory-control}

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

### Política editorial de memoria {#memory-editorial-policy}

Indica qué conocimiento merece guardarse con Markdown:

```text
~/.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:

```md
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 {#command-review-judge}

Escribe la política completa en Markdown:

```text
<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 {#context-compaction}

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

```md
---
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 {#see-also}

- [Extension Profiles](/es-ES/guide/extension-profiles)
- [Variables de entorno](/es-ES/reference/environment-variables)
- [Ámbitos y confianza](/es-ES/explanation/scopes-and-trust)
- [Proveedores y modelos](/es-ES/guide/providers-and-models)
- [Planes](/es-ES/guide/plans)
- [Seguridad y control](/es-ES/guide/safety)
- [Agentes](/es-ES/guide/agents)
- [Servidores MCP](/es-ES/guide/mcp-servers)
- [Hooks](/es-ES/guide/hooks)

---

[HTML canónico](https://clarvis.dev/es-ES/reference/configuration)

[Índice de documentación](https://clarvis.dev/es-ES/llms.txt)