> 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/resolucion-de-problemas.md).

# Resolución de problemas

## `kiwi: command not found` después de instalar

El directorio de instalación no está en tu `PATH`. El instalador imprime la línea exacta al terminar; si la perdiste, para `~/.local/bin`:

```sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
```

Abre una terminal nueva después.

## macOS bloquea el binario

Solo pasa si lo descargaste **con el navegador**: la cuarentena la pone el navegador, no el sistema.

```sh
xattr -d com.apple.quarantine ./kiwi
```

Con `curl` o con `brew` no ocurre. Kiwi no está firmado con una cuenta de desarrollador de Apple, que es de pago; está documentado en vez de fingir que el problema no existe.

## Tengo dos versiones instaladas

Si instalaste con `go install` y luego con Homebrew, tienes dos binarios y gana el que esté antes en el `PATH`:

```sh
which -a kiwi
```

Borra el que no quieras — normalmente `rm ~/go/bin/kiwi`.

## En Windows fallan todos los comandos

La herramienta `bash` ejecuta `bash -c`, así que necesitas **Git Bash o WSL** en el `PATH`. Sin ellos la interfaz funciona pero el agente no puede ejecutar nada.

## `kiwi update` dice que no puede actualizar

Es lo esperado si lo instaló un gestor de paquetes: el binario es suyo, y Kiwi no lo sobrescribe a sus espaldas. El propio comando te dice cuál usar — `brew upgrade kiwi`, `scoop update kiwi`.

## No puedo seleccionar texto con el ratón

Kiwi recibe los eventos del ratón para que la rueda desplace la conversación. Mantén **Option** (iTerm2, Ghostty) o **Fn** (Terminal.app) mientras arrastras y la terminal selecciona como siempre. Al salir de Kiwi la conversación se imprime en el scroll normal, y desde ahí se copia sin nada especial.

## `web_search` falla con DuckDuckGo

Sin clave, la búsqueda va por DuckDuckGo, que a veces responde con una comprobación anti-bots en vez de resultados. Añade `EXA_API_KEY` o `JINA_API_KEY` con `/config` y Kiwi usará ese proveedor. `kiwi doctor` confirma cuál está activo.

## El agente no puede leer una web

Si la página se construye con JavaScript, la descarga normal vuelve casi vacía. El agente puede repetirla con el modo lector (`reader: true`), que la renderiza en Jina Reader. Ver [Herramientas](/kiwi-docs/herramientas.md#web_fetch-y-el-modo-lector).

## El agente no hace nada, solo mira

Probablemente estás en modo **plan**, donde escribir está bloqueado a propósito. `/work` para aplicar cambios, `/ask` si prefieres confirmarlos uno a uno.

## Se queda sin contexto en conversaciones largas

`/context` para ver qué lo llena y `/compact` para resumir y seguir. Si el problema es un fichero gigante leído una vez, `/clear` y volver a empezar suele salir más barato.

## Un servidor que lancé sigue ocupando el puerto

No debería: al salir de Kiwi se paran los procesos en segundo plano y sus hijos. Si sospechas que uno sobrevivió, `kill_shell` lo para desde dentro de la sesión, y `/status` enseña lo que sigue corriendo.

## Dónde mirar

* Código y issues: [github.com/oscar1223/kiwi](https://github.com/oscar1223/kiwi)
* Releases y binarios: [github.com/oscar1223/kiwi/releases](https://github.com/oscar1223/kiwi/releases)


---

# 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 following URL with the `ask` and `goal` query parameters:

```
GET https://kiwi-8.gitbook.io/kiwi-docs/resolucion-de-problemas.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

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.