> For the complete documentation index, see [llms.txt](https://kiwi-8.gitbook.io/kiwi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kiwi-8.gitbook.io/kiwi-docs/configuracion.md).

# Configuración

## Dónde vive

| Qué               | Dónde                      |
| ----------------- | -------------------------- |
| Configuración     | `~/.config/kiwi/kiwi.json` |
| Servidores MCP    | `~/.config/kiwi/mcp.json`  |
| Skills            | `~/.config/kiwi/skills/`   |
| Memoria           | `~/.config/kiwi/memory/`   |
| Sesiones y estado | `~/.local/share/kiwi/`     |

Todas respetan `XDG_CONFIG_HOME` y `XDG_DATA_HOME` si los tienes definidos, y ninguna vive dentro de tu repositorio.

Casi todo se toca desde la interfaz —`/settings`, `/model`, `/reasoning`, `/theme`, `/config`, `/mcp`, `/skill`— pero los ficheros son JSON y Markdown normales, y editarlos a mano es perfectamente válido. Skills y MCP tienen su propia página: [Skills y MCP](/kiwi-docs/skills-y-mcp.md).

## Perfiles de modelo

Un perfil es un nombre corto para una combinación de proveedor y modelo. `current` dice cuál está activo.

```json
{
  "current": "sonnet",
  "profiles": {
    "sonnet": {
      "provider": "anthropic",
      "model": "claude-sonnet-5",
      "api_key_env": "ANTHROPIC_API_KEY"
    },
    "local": {
      "provider": "openai",
      "model": "qwen3-coder",
      "base_url": "http://localhost:11434/v1"
    }
  }
}
```

Para cambiar de perfil, `/model` dentro de la interfaz, o `--model` al arrancar:

```sh
kiwi --model opus
```

### Campos

| Campo         | Para qué                                                      |
| ------------- | ------------------------------------------------------------- |
| `provider`    | una de las cinco integraciones nativas (abajo)                |
| `model`       | el identificador del modelo, tal como lo espera ese proveedor |
| `base_url`    | endpoint alternativo — obligatorio para modelos locales       |
| `api_key_env` | **nombre** de la variable de entorno con la clave             |
| `reasoning`   | cuánto piensa el modelo (ver [Razonamiento](#razonamiento))   |

## Razonamiento

Muchos modelos piensan antes de responder, y cada proveedor decide por defecto cuánto: GLM 5.2 por OpenRouter, por ejemplo, razona con esfuerzo `high` si no se le dice otra cosa. El campo `reasoning` de un perfil lo fija:

| Valor     | Qué significa                                            |
| --------- | -------------------------------------------------------- |
| *(vacío)* | lo que decida el proveedor                               |
| `off`     | responder sin razonar: lo más rápido y barato            |
| `low`     | un poco                                                  |
| `medium`  | equilibrio entre velocidad y profundidad                 |
| `high`    | pensarlo bien                                            |
| `xhigh`   | pensar a fondo; buena opción para código y tareas largas |
| `max`     | todo lo que pueda: lo más lento y caro                   |

```json
"glm": {
  "provider": "openai",
  "model": "z-ai/glm-5.2",
  "base_url": "https://openrouter.ai/api/v1",
  "api_key_env": "OPENROUTER_API_KEY",
  "reasoning": "off"
}
```

No hace falta editarlo a mano: `/reasoning` lo cambia en vivo y lo guarda en el perfil activo. Un valor que Kiwi no reconoce da error al usar el perfil, en vez de ignorarse.

### Cómo llega a cada proveedor

| Proveedor                  | Qué se envía                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------- |
| OpenRouter                 | `reasoning: {effort}`, o `{enabled: false}` con `off`                                 |
| Z.ai (GLM directo)         | `thinking: {type}`: solo encendido o apagado                                          |
| OpenAI y compatibles       | `reasoning_effort` (`off` se envía como `none`)                                       |
| Anthropic, Bedrock, Vertex | thinking adaptativo con `effort`; en Haiku 4.5 y anteriores, un presupuesto de tokens |

Algunos modelos de Claude (Opus 5.5, Fable) no dejan apagar el razonamiento: ahí `off` es el esfuerzo mínimo. Cuando el modelo usa herramientas, Kiwi le devuelve lo que pensó en el paso anterior, que algunas APIs exigen; solo al mismo modelo que lo produjo.

## Las claves nunca se guardan aquí

`api_key_env` guarda el *nombre* de una variable de entorno, no su contenido. Kiwi lee la clave del entorno en tiempo de ejecución, así que tu `kiwi.json` se puede compartir, versionar o pegar en un issue sin filtrar nada.

```sh
export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
```

## Cinco integraciones, veinte perfiles

Por dentro hay **cinco** tipos de proveedor: `anthropic`, `openai`, `azure-openai`, `vertex` y `bedrock`. Sobre ellos, Kiwi trae **veinte perfiles ya escritos** — casi todos son un `base_url` distinto sobre el formato chat-completions de OpenAI, que es lo que hoy habla casi todo el mundo.

| Perfil                       | Destino                     | Clave                |
| ---------------------------- | --------------------------- | -------------------- |
| `sonnet`, `opus`             | Anthropic                   | `ANTHROPIC_API_KEY`  |
| `gpt`                        | OpenAI                      | `OPENAI_API_KEY`     |
| `local`                      | Ollama en `localhost:11434` | ninguna              |
| `openrouter`                 | OpenRouter                  | `OPENROUTER_API_KEY` |
| `groq`                       | Groq                        | `GROQ_API_KEY`       |
| `cerebras`                   | Cerebras                    | `CEREBRAS_API_KEY`   |
| `together`                   | Together                    | `TOGETHER_API_KEY`   |
| `fireworks`                  | Fireworks                   | `FIREWORKS_API_KEY`  |
| `deepinfra`                  | DeepInfra                   | `DEEPINFRA_API_KEY`  |
| `deepseek`                   | DeepSeek                    | `DEEPSEEK_API_KEY`   |
| `mistral`                    | Mistral                     | `MISTRAL_API_KEY`    |
| `xai`                        | xAI                         | `XAI_API_KEY`        |
| `moonshot`                   | Moonshot                    | `MOONSHOT_API_KEY`   |
| `zhipu`                      | Zhipu (GLM)                 | `ZHIPU_API_KEY`      |
| `gemini`                     | Google Gemini               | `GEMINI_API_KEY`     |
| `perplexity`                 | Perplexity                  | `PERPLEXITY_API_KEY` |
| `azure`, `vertex`, `bedrock` | las tres nubes              | ver abajo            |

El perfil `local` apunta al puerto por defecto de Ollama: si ya tienes un modelo servido ahí, `kiwi --model local` funciona sin configurar nada más y sin que salga una sola petición de tu máquina.

Añadir uno nuevo es añadir una entrada en `profiles` con su `base_url` y su `api_key_env`.

### Las nubes usan sus propias credenciales

| Proveedor     | Credenciales                                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Azure OpenAI  | `AZURE_API_KEY` y `AZURE_RESOURCE_NAME`                                                                                                    |
| Google Vertex | `GOOGLE_VERTEX_PROJECT` y `GOOGLE_VERTEX_LOCATION`, con las credenciales de Google de tu máquina (`gcloud auth application-default login`) |
| AWS Bedrock   | la cadena de credenciales estándar de AWS: variables `AWS_*`, `~/.aws/` o el rol de la máquina                                             |

Si faltan, el perfil da un error normal al usarlo en vez de tumbar Kiwi.

## Búsqueda web

`web_search` funciona sin configurar nada, a través de DuckDuckGo. Con una de estas claves usa un proveedor mejor:

| Variable       | Proveedor                                                                             |
| -------------- | ------------------------------------------------------------------------------------- |
| `EXA_API_KEY`  | [Exa](https://exa.ai) (tiene prioridad)                                               |
| `JINA_API_KEY` | [Jina Search](https://jina.ai); también sube el límite del modo lector de `web_fetch` |

Se añaden con `/config` o en el entorno. `kiwi doctor` dice cuál está en uso.

## La primera vez

Si al arrancar no hay ninguna clave configurada, Kiwi abre un onboarding que te pregunta proveedor, modelo y clave, en vez de fallar con un error.

## Tema

```json
{ "theme": "kiwi-dark" }
```

O `/theme` en la interfaz, que los enseña y los cambia en vivo.

## Otras variables de entorno

| Variable                 | Qué hace                                                                                              |
| ------------------------ | ----------------------------------------------------------------------------------------------------- |
| `KIWI_NO_UPDATE_CHECK=1` | desactiva el aviso de versión nueva (ver [`kiwi update`](/kiwi-docs/comandos-del-cli.md#kiwi-update)) |
| `VISUAL` / `EDITOR`      | el editor que abre `ctrl+e`                                                                           |

## Observabilidad

Si quieres trazas de lo que hace el agente, Kiwi exporta a OpenTelemetry y a Langfuse mediante variables de entorno: `OTEL_EXPORTER_OTLP_ENDPOINT` (o `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, solo para trazas), y `LANGFUSE_HOST` con `LANGFUSE_PUBLIC_KEY` y `LANGFUSE_SECRET_KEY`. Sin ellas no sale ninguna traza: no hay telemetría por defecto.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://kiwi-8.gitbook.io/kiwi-docs/configuracion.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.