chore(i18n): refresh es translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
4e5172c84f
commit
15a646380b
@ -1,21 +1,21 @@
|
||||
---
|
||||
read_when:
|
||||
- Tienes problemas de conectividad/autenticación y quieres correcciones guiadas
|
||||
- Tienes problemas de conectividad/autenticación y quieres soluciones guiadas
|
||||
- Has actualizado y quieres una comprobación rápida
|
||||
summary: Referencia de CLI para `openclaw doctor` (comprobaciones de estado + reparaciones guiadas)
|
||||
title: Diagnóstico
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T05:33:40Z"
|
||||
generated_at: "2026-04-30T20:05:33Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 9985c84d23861dd9468a4659ee00519573fe6d540c436548da0a68067dbabc4c
|
||||
source_hash: 265d82a10da086cf89687886e491be018a720b70021e0b26bd8f39b25a907e14
|
||||
source_path: cli/doctor.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# `openclaw doctor`
|
||||
|
||||
Comprobaciones de estado + correcciones rápidas para el Gateway y los canales.
|
||||
Comprobaciones de salud y correcciones rápidas para el Gateway y los canales.
|
||||
|
||||
Relacionado:
|
||||
|
||||
@ -34,39 +34,40 @@ openclaw doctor --generate-gateway-token
|
||||
|
||||
## Opciones
|
||||
|
||||
- `--no-workspace-suggestions`: deshabilita las sugerencias de memoria/búsqueda del espacio de trabajo
|
||||
- `--no-workspace-suggestions`: desactiva las sugerencias de memoria/búsqueda del espacio de trabajo
|
||||
- `--yes`: acepta los valores predeterminados sin solicitar confirmación
|
||||
- `--repair`: aplica las reparaciones recomendadas sin solicitar confirmación
|
||||
- `--fix`: alias de `--repair`
|
||||
- `--force`: aplica reparaciones agresivas, incluida la sobrescritura de la configuración personalizada del servicio cuando sea necesario
|
||||
- `--non-interactive`: ejecuta sin solicitudes; solo migraciones seguras
|
||||
- `--generate-gateway-token`: genera y configura un token de Gateway
|
||||
- `--deep`: escanea los servicios del sistema en busca de instalaciones adicionales del Gateway
|
||||
- `--deep`: analiza los servicios del sistema para detectar instalaciones adicionales del Gateway
|
||||
|
||||
Notas:
|
||||
|
||||
- Las solicitudes interactivas (como correcciones de llavero/OAuth) solo se ejecutan cuando stdin es un TTY y `--non-interactive` **no** está establecido. Las ejecuciones sin interfaz (cron, Telegram, sin terminal) omitirán las solicitudes.
|
||||
- Rendimiento: las ejecuciones no interactivas de `doctor` omiten la carga anticipada de plugins para que las comprobaciones de estado sin interfaz sigan siendo rápidas. Las sesiones interactivas siguen cargando completamente los plugins cuando una comprobación necesita su contribución.
|
||||
- `--fix` (alias de `--repair`) escribe una copia de seguridad en `~/.openclaw/openclaw.json.bak` y descarta claves de configuración desconocidas, listando cada eliminación.
|
||||
- Las solicitudes interactivas (como correcciones de llavero/OAuth) solo se ejecutan cuando stdin es una TTY y `--non-interactive` **no** está establecido. Las ejecuciones sin interfaz (cron, Telegram, sin terminal) omitirán las solicitudes.
|
||||
- Rendimiento: las ejecuciones no interactivas de `doctor` omiten la carga anticipada de Plugin para que las comprobaciones de salud sin interfaz sigan siendo rápidas. Las sesiones interactivas siguen cargando por completo los Plugins cuando una comprobación necesita su contribución.
|
||||
- `--fix` (alias de `--repair`) escribe una copia de seguridad en `~/.openclaw/openclaw.json.bak` y descarta las claves de configuración desconocidas, enumerando cada eliminación.
|
||||
- Las comprobaciones de integridad de estado ahora detectan archivos de transcripción huérfanos en el directorio de sesiones. Archivarlos como `.deleted.<timestamp>` requiere una confirmación interactiva; `--fix`, `--yes` y las ejecuciones sin interfaz los dejan en su lugar.
|
||||
- Doctor también escanea `~/.openclaw/cron/jobs.json` (o `cron.store`) en busca de formas heredadas de trabajos cron y puede reescribirlas en el lugar antes de que el programador tenga que normalizarlas automáticamente en tiempo de ejecución.
|
||||
- Doctor repara dependencias de runtime faltantes de plugins incluidos sin escribir en instalaciones globales empaquetadas. Para instalaciones npm propiedad de root o unidades systemd endurecidas, establece `OPENCLAW_PLUGIN_STAGE_DIR` en un directorio escribible, como `/var/lib/openclaw/plugin-runtime-deps`; también puede ser una lista de rutas, como `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps`, donde las raíces anteriores son capas de búsqueda de solo lectura y la raíz final es el destino de reparación.
|
||||
- Doctor repara configuración obsoleta de plugins eliminando ids de plugins faltantes de `plugins.allow`/`plugins.entries`, además de la configuración de canal colgante coincidente, destinos de Heartbeat y anulaciones de modelo de canal cuando el descubrimiento de plugins está sano.
|
||||
- Doctor pone en cuarentena configuración inválida de plugins deshabilitando la entrada `plugins.entries.<id>` afectada y eliminando su carga `config` inválida. El arranque del Gateway ya omite solo ese plugin defectuoso para que otros plugins y canales puedan seguir ejecutándose.
|
||||
- Establece `OPENCLAW_SERVICE_REPAIR_POLICY=external` cuando otro supervisor posee el ciclo de vida del Gateway. Doctor sigue informando el estado del Gateway/servicio y aplica reparaciones que no son de servicio, pero omite instalación/inicio/reinicio/bootstrap del servicio y limpieza de servicios heredados.
|
||||
- En Linux, doctor ignora unidades systemd adicionales inactivas similares al Gateway y no reescribe metadatos de comando/punto de entrada para un servicio de Gateway systemd en ejecución durante la reparación. Detén primero el servicio o usa `openclaw gateway install --force` cuando quieras reemplazar intencionadamente el lanzador activo.
|
||||
- Doctor migra automáticamente la configuración plana heredada de Talk (`talk.voiceId`, `talk.modelId` y similares) a `talk.provider` + `talk.providers.<provider>`.
|
||||
- Las ejecuciones repetidas de `doctor --fix` ya no informan/aplican normalización de Talk cuando la única diferencia es el orden de las claves del objeto.
|
||||
- Doctor incluye una comprobación de preparación de búsqueda en memoria y puede recomendar `openclaw configure --section model` cuando faltan credenciales de embeddings.
|
||||
- Doctor advierte cuando no hay ningún propietario de comandos configurado. El propietario de comandos es la cuenta del operador humano autorizada para ejecutar comandos exclusivos del propietario y aprobar acciones peligrosas. El emparejamiento por DM solo permite que alguien hable con el bot; si aprobaste un remitente antes de que existiera el bootstrap del primer propietario, establece `commands.ownerAllowFrom` explícitamente.
|
||||
- Si el modo sandbox está habilitado pero Docker no está disponible, doctor informa una advertencia de alta señal con remediación (`install Docker` u `openclaw config set agents.defaults.sandbox.mode off`).
|
||||
- Si `gateway.auth.token`/`gateway.auth.password` están gestionados por SecretRef y no están disponibles en la ruta de comando actual, doctor informa una advertencia de solo lectura y no escribe credenciales alternativas en texto plano.
|
||||
- Doctor también analiza `~/.openclaw/cron/jobs.json` (o `cron.store`) en busca de formas heredadas de trabajos Cron y puede reescribirlas en su lugar antes de que el planificador tenga que normalizarlas automáticamente en tiempo de ejecución.
|
||||
- Doctor repara las dependencias de runtime faltantes de los Plugins incluidos sin escribir en instalaciones globales empaquetadas. Para instalaciones npm propiedad de root o unidades systemd reforzadas, establece `OPENCLAW_PLUGIN_STAGE_DIR` en un directorio escribible como `/var/lib/openclaw/plugin-runtime-deps`; también puede ser una lista de rutas como `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps`, donde las raíces anteriores son capas de búsqueda de solo lectura y la raíz final es el destino de reparación.
|
||||
- Doctor repara la configuración obsoleta de Plugins eliminando los ids de Plugin faltantes de `plugins.allow`/`plugins.entries`, además de la configuración de canal colgante correspondiente, los destinos de Heartbeat y las anulaciones de modelo de canal cuando la detección de Plugins está sana.
|
||||
- Doctor pone en cuarentena la configuración inválida de Plugins desactivando la entrada `plugins.entries.<id>` afectada y eliminando su payload `config` inválido. El arranque del Gateway ya omite solo ese Plugin defectuoso para que otros Plugins y canales puedan seguir ejecutándose.
|
||||
- Establece `OPENCLAW_SERVICE_REPAIR_POLICY=external` cuando otro supervisor sea propietario del ciclo de vida del Gateway. Doctor sigue informando sobre la salud del Gateway/servicio y aplica reparaciones no relacionadas con el servicio, pero omite la instalación/inicio/reinicio/bootstrap del servicio y la limpieza de servicios heredados.
|
||||
- En Linux, doctor ignora las unidades systemd adicionales inactivas similares al Gateway y no reescribe los metadatos de comando/entrypoint de un servicio Gateway systemd en ejecución durante la reparación. Detén primero el servicio o usa `openclaw gateway install --force` cuando quieras reemplazar intencionalmente el lanzador activo.
|
||||
- Doctor migra automáticamente la configuración Talk plana heredada (`talk.voiceId`, `talk.modelId` y relacionadas) a `talk.provider` + `talk.providers.<provider>`.
|
||||
- Las ejecuciones repetidas de `doctor --fix` ya no informan/aplican la normalización de Talk cuando la única diferencia es el orden de las claves del objeto.
|
||||
- Doctor incluye una comprobación de preparación de búsqueda en memoria y puede recomendar `openclaw configure --section model` cuando faltan credenciales de embedding.
|
||||
- Doctor advierte cuando no hay un propietario de comandos configurado. El propietario de comandos es la cuenta del operador humano autorizada para ejecutar comandos exclusivos del propietario y aprobar acciones peligrosas. El emparejamiento por DM solo permite que alguien hable con el bot; si aprobaste un remitente antes de que existiera el bootstrap del primer propietario, establece `commands.ownerAllowFrom` explícitamente.
|
||||
- Doctor advierte cuando hay agentes en modo Codex configurados y existen assets personales de la CLI de Codex en el home de Codex del operador. Los lanzamientos locales del app-server de Codex usan homes aislados por agente, así que usa `openclaw migrate codex --dry-run` para inventariar los assets que deberían promocionarse deliberadamente.
|
||||
- Si el modo sandbox está activado pero Docker no está disponible, doctor informa una advertencia de alta señal con una corrección (`install Docker` o `openclaw config set agents.defaults.sandbox.mode off`).
|
||||
- Si `gateway.auth.token`/`gateway.auth.password` están gestionados por SecretRef y no están disponibles en la ruta del comando actual, doctor informa una advertencia de solo lectura y no escribe credenciales alternativas en texto plano.
|
||||
- Si la inspección de SecretRef de canal falla en una ruta de corrección, doctor continúa e informa una advertencia en lugar de salir antes de tiempo.
|
||||
- La resolución automática de nombres de usuario `allowFrom` de Telegram (`doctor --fix`) requiere un token de Telegram resoluble en la ruta de comando actual. Si la inspección del token no está disponible, doctor informa una advertencia y omite la resolución automática para esa pasada.
|
||||
- La resolución automática de nombre de usuario de `allowFrom` de Telegram (`doctor --fix`) requiere un token de Telegram resoluble en la ruta del comando actual. Si la inspección del token no está disponible, doctor informa una advertencia y omite la resolución automática en esa pasada.
|
||||
|
||||
## macOS: anulaciones de entorno de `launchctl`
|
||||
|
||||
Si ejecutaste anteriormente `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (o `...PASSWORD`), ese valor anula tu archivo de configuración y puede causar errores persistentes de “no autorizado”.
|
||||
Si anteriormente ejecutaste `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (o `...PASSWORD`), ese valor anula tu archivo de configuración y puede causar errores persistentes de “no autorizado”.
|
||||
|
||||
```bash
|
||||
launchctl getenv OPENCLAW_GATEWAY_TOKEN
|
||||
@ -78,5 +79,5 @@ launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Referencia de CLI](/es/cli)
|
||||
- [Gateway doctor](/es/gateway/doctor)
|
||||
- [Referencia de la CLI](/es/cli)
|
||||
- [Doctor de Gateway](/es/gateway/doctor)
|
||||
|
||||
@ -1,21 +1,21 @@
|
||||
---
|
||||
read_when:
|
||||
- Quieres migrar de Hermes u otro sistema de agentes a OpenClaw
|
||||
- Quieres migrar desde Hermes u otro sistema de agentes a OpenClaw
|
||||
- Estás agregando un proveedor de migración propiedad del Plugin
|
||||
summary: Referencia de la CLI para `openclaw migrate` (importar estado desde otro sistema de agentes)
|
||||
summary: Referencia de CLI para `openclaw migrate` (importar el estado desde otro sistema de agentes)
|
||||
title: Migrar
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T05:34:43Z"
|
||||
generated_at: "2026-04-30T20:05:36Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d3db14c16b8f9dcbf86a4f12558cf4e8555aa9a255637034fb804148996a225e
|
||||
source_hash: ffcd9e874bdaa0a5195e712d4fccd7b3d53034cb362c7f7462e9c7df72477b1a
|
||||
source_path: cli/migrate.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# `openclaw migrate`
|
||||
|
||||
Importa el estado desde otro sistema de agente mediante un proveedor de migración propiedad de un Plugin. Los proveedores incluidos cubren [Claude](/es/install/migrating-claude) y [Hermes](/es/install/migrating-hermes); los plugins de terceros pueden registrar proveedores adicionales.
|
||||
Importa el estado desde otro sistema de agentes mediante un proveedor de migración propiedad de un plugin. Los proveedores incluidos cubren el estado de Codex CLI, [Claude](/es/install/migrating-claude) y [Hermes](/es/install/migrating-hermes); los plugins de terceros pueden registrar proveedores adicionales.
|
||||
|
||||
<Tip>
|
||||
Para guías paso a paso orientadas al usuario, consulta [Migrar desde Claude](/es/install/migrating-claude) y [Migrar desde Hermes](/es/install/migrating-hermes). El [centro de migración](/es/install/migrating) enumera todas las rutas.
|
||||
@ -26,8 +26,12 @@ Para guías paso a paso orientadas al usuario, consulta [Migrar desde Claude](/e
|
||||
```bash
|
||||
openclaw migrate list
|
||||
openclaw migrate claude --dry-run
|
||||
openclaw migrate codex --dry-run
|
||||
openclaw migrate codex --skill gog-vault77-google-workspace
|
||||
openclaw migrate hermes --dry-run
|
||||
openclaw migrate hermes
|
||||
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
|
||||
openclaw migrate apply codex --yes
|
||||
openclaw migrate apply claude --yes
|
||||
openclaw migrate apply hermes --yes
|
||||
openclaw migrate apply hermes --include-secrets --yes
|
||||
@ -40,28 +44,31 @@ openclaw onboard --import-from hermes --import-source ~/.hermes
|
||||
Nombre de un proveedor de migración registrado, por ejemplo `hermes`. Ejecuta `openclaw migrate list` para ver los proveedores instalados.
|
||||
</ParamField>
|
||||
<ParamField path="--dry-run" type="boolean">
|
||||
Crea el plan y sale sin cambiar el estado.
|
||||
Construye el plan y sale sin cambiar el estado.
|
||||
</ParamField>
|
||||
<ParamField path="--from <path>" type="string">
|
||||
Anula el directorio de estado de origen. Hermes usa `~/.hermes` de forma predeterminada.
|
||||
Sobrescribe el directorio de estado de origen. Hermes usa `~/.hermes` de forma predeterminada.
|
||||
</ParamField>
|
||||
<ParamField path="--include-secrets" type="boolean">
|
||||
Importa credenciales compatibles. Desactivado de forma predeterminada.
|
||||
</ParamField>
|
||||
<ParamField path="--overwrite" type="boolean">
|
||||
Permite que la aplicación sustituya destinos existentes cuando el plan informa conflictos.
|
||||
Permite que la aplicación reemplace destinos existentes cuando el plan informa conflictos.
|
||||
</ParamField>
|
||||
<ParamField path="--yes" type="boolean">
|
||||
Omite la solicitud de confirmación. Obligatorio en modo no interactivo.
|
||||
Omite el mensaje de confirmación. Obligatorio en modo no interactivo.
|
||||
</ParamField>
|
||||
<ParamField path="--skill <name>" type="string">
|
||||
Selecciona un elemento de copia de skill por nombre de skill o id de elemento. Repite la marca para migrar varios skills. Cuando se omite, las migraciones interactivas de Codex muestran un selector de casillas y las migraciones no interactivas conservan todos los skills planificados.
|
||||
</ParamField>
|
||||
<ParamField path="--no-backup" type="boolean">
|
||||
Omite la copia de seguridad previa a la aplicación. Requiere `--force` cuando existe estado local de OpenClaw.
|
||||
</ParamField>
|
||||
<ParamField path="--force" type="boolean">
|
||||
Obligatorio junto con `--no-backup` cuando la aplicación de otro modo se negaría a omitir la copia de seguridad.
|
||||
Obligatorio junto con `--no-backup` cuando la aplicación se negaría de otro modo a omitir la copia de seguridad.
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
Imprime el plan o el resultado de la aplicación como JSON. Con `--json` y sin `--yes`, apply imprime el plan y no modifica el estado.
|
||||
Imprime el plan o el resultado de la aplicación como JSON. Con `--json` y sin `--yes`, la aplicación imprime el plan y no muta el estado.
|
||||
</ParamField>
|
||||
|
||||
## Modelo de seguridad
|
||||
@ -70,16 +77,16 @@ openclaw onboard --import-from hermes --import-source ~/.hermes
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Vista previa antes de aplicar">
|
||||
El proveedor devuelve un plan detallado antes de que cambie nada, incluidos conflictos, elementos omitidos y elementos sensibles. Los planes JSON, la salida de aplicación y los informes de migración redactan claves anidadas con apariencia de secreto, como claves de API, tokens, encabezados de autorización, cookies y contraseñas.
|
||||
El proveedor devuelve un plan detallado antes de que cambie nada, incluidos conflictos, elementos omitidos y elementos sensibles. Los planes JSON, la salida de aplicación y los informes de migración redactan claves anidadas con aspecto de secreto, como claves de API, tokens, encabezados de autorización, cookies y contraseñas.
|
||||
|
||||
`openclaw migrate apply <provider>` muestra una vista previa del plan y solicita confirmación antes de cambiar el estado, salvo que se establezca `--yes`. En modo no interactivo, apply requiere `--yes`.
|
||||
`openclaw migrate apply <provider>` muestra una vista previa del plan y solicita confirmación antes de cambiar el estado, salvo que se establezca `--yes`. En modo no interactivo, la aplicación requiere `--yes`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Copias de seguridad">
|
||||
Apply crea y verifica una copia de seguridad de OpenClaw antes de aplicar la migración. Si aún no existe estado local de OpenClaw, se omite el paso de copia de seguridad y la migración puede continuar. Para omitir una copia de seguridad cuando existe estado, pasa tanto `--no-backup` como `--force`.
|
||||
La aplicación crea y verifica una copia de seguridad de OpenClaw antes de aplicar la migración. Si todavía no existe estado local de OpenClaw, el paso de copia de seguridad se omite y la migración puede continuar. Para omitir una copia de seguridad cuando existe estado, pasa tanto `--no-backup` como `--force`.
|
||||
</Accordion>
|
||||
<Accordion title="Conflictos">
|
||||
Apply se niega a continuar cuando el plan tiene conflictos. Revisa el plan y luego vuelve a ejecutarlo con `--overwrite` si sustituir destinos existentes es intencional. Los proveedores aún pueden escribir copias de seguridad a nivel de elemento para archivos sobrescritos en el directorio del informe de migración.
|
||||
La aplicación se niega a continuar cuando el plan tiene conflictos. Revisa el plan y luego vuelve a ejecutarlo con `--overwrite` si reemplazar destinos existentes es intencional. Los proveedores aún pueden escribir copias de seguridad a nivel de elemento para archivos sobrescritos en el directorio del informe de migración.
|
||||
</Accordion>
|
||||
<Accordion title="Secretos">
|
||||
Los secretos nunca se importan de forma predeterminada. Usa `--include-secrets` para importar credenciales compatibles.
|
||||
@ -97,14 +104,51 @@ Para una guía paso a paso orientada al usuario, consulta [Migrar desde Claude](
|
||||
### Qué importa Claude
|
||||
|
||||
- `CLAUDE.md` del proyecto y `.claude/CLAUDE.md` en el espacio de trabajo del agente de OpenClaw.
|
||||
- `~/.claude/CLAUDE.md` del usuario agregado a `USER.md` del espacio de trabajo.
|
||||
- `~/.claude/CLAUDE.md` del usuario anexado a `USER.md` del espacio de trabajo.
|
||||
- Definiciones de servidor MCP desde `.mcp.json` del proyecto, `~/.claude.json` de Claude Code y `claude_desktop_config.json` de Claude Desktop.
|
||||
- Directorios de Skills de Claude que incluyen `SKILL.md`.
|
||||
- Archivos Markdown de comandos de Claude convertidos en Skills de OpenClaw solo con invocación manual.
|
||||
- Directorios de skills de Claude que incluyen `SKILL.md`.
|
||||
- Archivos Markdown de comandos de Claude convertidos en skills de OpenClaw solo con invocación manual.
|
||||
|
||||
### Estado de archivo y revisión manual
|
||||
### Archivo y estado de revisión manual
|
||||
|
||||
Los hooks, permisos, valores predeterminados de entorno, memoria local, reglas con alcance por ruta, subagentes, cachés, planes e historial de proyecto de Claude se conservan en el informe de migración o se informan como elementos de revisión manual. OpenClaw no ejecuta hooks, no copia listas amplias de permisos ni importa automáticamente el estado de credenciales OAuth/Desktop.
|
||||
Los hooks, permisos, valores predeterminados de entorno, memoria local, reglas con alcance por ruta, subagentes, cachés, planes e historial de proyecto de Claude se conservan en el informe de migración o se informan como elementos de revisión manual. OpenClaw no ejecuta hooks, copia allowlists amplias ni importa automáticamente estado de credenciales OAuth/Desktop.
|
||||
|
||||
## Proveedor de Codex
|
||||
|
||||
El proveedor de Codex incluido detecta el estado de Codex CLI en `~/.codex` de forma predeterminada, o
|
||||
en `CODEX_HOME` cuando esa variable de entorno está establecida. Usa `--from <path>` para
|
||||
inventariar una carpeta de inicio específica de Codex.
|
||||
|
||||
Usa este proveedor al pasar al arnés de Codex de OpenClaw y cuando quieras
|
||||
promocionar deliberadamente recursos personales útiles de Codex CLI. Los lanzamientos
|
||||
locales del servidor de aplicaciones de Codex usan directorios `CODEX_HOME` y `HOME`
|
||||
por agente, por lo que no leen tu estado personal de Codex CLI de forma predeterminada.
|
||||
|
||||
Ejecutar `openclaw migrate codex` en una terminal interactiva muestra una vista previa del plan
|
||||
completo y luego abre un selector de casillas para los elementos de copia de skills antes de la confirmación
|
||||
final de aplicación. Todos los skills empiezan seleccionados; desmarca cualquier skill que no quieras
|
||||
copiar en este agente. Para ejecuciones con scripts o exactas, pasa `--skill <name>` una vez
|
||||
por skill, por ejemplo:
|
||||
|
||||
```bash
|
||||
openclaw migrate codex --dry-run --skill gog-vault77-google-workspace
|
||||
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
|
||||
```
|
||||
|
||||
### Qué importa Codex
|
||||
|
||||
- Directorios de skills de Codex CLI bajo `$CODEX_HOME/skills`, excluida la caché
|
||||
`.system` de Codex.
|
||||
- AgentSkills personales bajo `$HOME/.agents/skills`, copiados en el espacio de trabajo
|
||||
actual del agente de OpenClaw cuando quieres propiedad por agente.
|
||||
|
||||
### Estado de Codex de revisión manual
|
||||
|
||||
Los plugins nativos de Codex, `config.toml` y `hooks/hooks.json` nativo no se
|
||||
activan automáticamente. Los plugins pueden exponer servidores MCP, apps, hooks u otro
|
||||
comportamiento ejecutable, por lo que el proveedor los informa para revisión en lugar de cargarlos
|
||||
en OpenClaw. Los archivos de configuración y hooks se copian en el informe de migración
|
||||
para revisión manual.
|
||||
|
||||
## Proveedor de Hermes
|
||||
|
||||
@ -113,22 +157,22 @@ El proveedor de Hermes incluido detecta el estado en `~/.hermes` de forma predet
|
||||
### Qué importa Hermes
|
||||
|
||||
- Configuración de modelo predeterminada desde `config.yaml`.
|
||||
- Proveedores de modelo configurados y endpoints personalizados compatibles con OpenAI desde `providers` y `custom_providers`.
|
||||
- Proveedores de modelos configurados y endpoints personalizados compatibles con OpenAI desde `providers` y `custom_providers`.
|
||||
- Definiciones de servidor MCP desde `mcp_servers` o `mcp.servers`.
|
||||
- `SOUL.md` y `AGENTS.md` en el espacio de trabajo del agente de OpenClaw.
|
||||
- `memories/MEMORY.md` y `memories/USER.md` agregados a los archivos de memoria del espacio de trabajo.
|
||||
- Valores predeterminados de configuración de memoria para la memoria de archivos de OpenClaw, además de elementos archivados o de revisión manual para proveedores de memoria externos como Honcho.
|
||||
- `memories/MEMORY.md` y `memories/USER.md` anexados a los archivos de memoria del espacio de trabajo.
|
||||
- Valores predeterminados de configuración de memoria para la memoria de archivos de OpenClaw, además de elementos de archivo o revisión manual para proveedores de memoria externos como Honcho.
|
||||
- Skills que incluyen un archivo `SKILL.md` bajo `skills/<name>/`.
|
||||
- Valores de configuración por Skill desde `skills.config`.
|
||||
- Valores de configuración por skill desde `skills.config`.
|
||||
- Claves de API compatibles desde `.env`, solo con `--include-secrets`.
|
||||
|
||||
### Claves `.env` compatibles
|
||||
|
||||
`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `GOOGLE_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`.
|
||||
|
||||
### Estado solo archivado
|
||||
### Estado solo de archivo
|
||||
|
||||
El estado de Hermes que OpenClaw no puede interpretar con seguridad se copia en el informe de migración para revisión manual, pero no se carga en la configuración ni en las credenciales activas de OpenClaw. Esto conserva el estado opaco o inseguro sin fingir que OpenClaw puede ejecutarlo o confiar en él automáticamente:
|
||||
El estado de Hermes que OpenClaw no puede interpretar de forma segura se copia en el informe de migración para revisión manual, pero no se carga en la configuración ni en las credenciales activas de OpenClaw. Esto conserva el estado opaco o inseguro sin fingir que OpenClaw puede ejecutarlo o confiar en él automáticamente:
|
||||
|
||||
- `plugins/`
|
||||
- `sessions/`
|
||||
@ -156,16 +200,16 @@ Las fuentes de migración son plugins. Un plugin declara sus ids de proveedor en
|
||||
}
|
||||
```
|
||||
|
||||
En tiempo de ejecución, el plugin llama a `api.registerMigrationProvider(...)`. El proveedor implementa `detect`, `plan` y `apply`. Core es responsable de la orquestación de la CLI, la política de copias de seguridad, las solicitudes de confirmación, la salida JSON y la comprobación previa de conflictos. Core pasa el plan revisado a `apply(ctx, plan)`, y los proveedores pueden reconstruir el plan solo cuando ese argumento esté ausente por compatibilidad.
|
||||
En tiempo de ejecución, el plugin llama a `api.registerMigrationProvider(...)`. El proveedor implementa `detect`, `plan` y `apply`. El núcleo posee la orquestación de CLI, la política de copias de seguridad, los mensajes de confirmación, la salida JSON y la comprobación previa de conflictos. El núcleo pasa el plan revisado a `apply(ctx, plan)`, y los proveedores pueden reconstruir el plan solo cuando ese argumento está ausente por compatibilidad.
|
||||
|
||||
Los plugins de proveedor pueden usar `openclaw/plugin-sdk/migration` para la construcción de elementos y conteos de resumen, además de `openclaw/plugin-sdk/migration-runtime` para copias de archivos conscientes de conflictos, copias de informes solo archivadas, envoltorios de runtime de configuración en caché e informes de migración.
|
||||
Los plugins de proveedor pueden usar `openclaw/plugin-sdk/migration` para la construcción de elementos y recuentos de resumen, además de `openclaw/plugin-sdk/migration-runtime` para copias de archivos con detección de conflictos, copias de informes solo de archivo, envoltorios de config-runtime en caché e informes de migración.
|
||||
|
||||
## Integración de incorporación
|
||||
## Integración de onboarding
|
||||
|
||||
La incorporación puede ofrecer migración cuando un proveedor detecta una fuente conocida. Tanto `openclaw onboard --flow import` como `openclaw setup --wizard --import-from hermes` usan el mismo proveedor de migración de plugin y siguen mostrando una vista previa antes de aplicar.
|
||||
El onboarding puede ofrecer migración cuando un proveedor detecta una fuente conocida. Tanto `openclaw onboard --flow import` como `openclaw setup --wizard --import-from hermes` usan el mismo proveedor de migración de plugin y aún muestran una vista previa antes de aplicar.
|
||||
|
||||
<Note>
|
||||
Las importaciones de incorporación requieren una configuración nueva de OpenClaw. Restablece primero la configuración, las credenciales, las sesiones y el espacio de trabajo si ya tienes estado local. Las importaciones con copia de seguridad más sobrescritura o fusión están protegidas por feature gate para configuraciones existentes.
|
||||
Las importaciones de onboarding requieren una configuración nueva de OpenClaw. Restablece primero la configuración, las credenciales, las sesiones y el espacio de trabajo si ya tienes estado local. Las importaciones con copia de seguridad más sobrescritura o fusión están protegidas por feature gate para configuraciones existentes.
|
||||
</Note>
|
||||
|
||||
## Relacionado
|
||||
|
||||
@ -1,27 +1,27 @@
|
||||
---
|
||||
read_when:
|
||||
- Necesitas explicar el espacio de trabajo del agente o la estructura de sus archivos
|
||||
- Quieres hacer una copia de seguridad o migrar un espacio de trabajo del agente
|
||||
- Debes explicar el espacio de trabajo del agente o su estructura de archivos
|
||||
- Desea hacer una copia de seguridad o migrar un espacio de trabajo de agente
|
||||
sidebarTitle: Agent workspace
|
||||
summary: 'Espacio de trabajo del agente: ubicación, estructura y estrategia de copia de seguridad'
|
||||
title: Espacio de trabajo del agente
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T11:26:37Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-04-30T20:05:32Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 35d59d1f0dec05db30f9166a43bfa519d7299b08d093bbeb905d8f83e5cd022a
|
||||
source_hash: b1ccf74cbec3ff20f4c1c1ce52f099a7ca3365b2536b0aad6ff1d3a5fafcca0a
|
||||
source_path: concepts/agent-workspace.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
El espacio de trabajo es el hogar del agente. Es el único directorio de trabajo usado para las herramientas de archivos y para el contexto del espacio de trabajo. Mantenlo privado y trátalo como memoria.
|
||||
|
||||
Esto es independiente de `~/.openclaw/`, que almacena configuración, credenciales y sesiones.
|
||||
Esto está separado de `~/.openclaw/`, que almacena configuración, credenciales y sesiones.
|
||||
|
||||
<Warning>
|
||||
El espacio de trabajo es el **cwd predeterminado**, no un sandbox rígido. Las herramientas resuelven rutas relativas respecto del espacio de trabajo, pero las rutas absolutas aún pueden llegar a otras partes del host a menos que el sandboxing esté habilitado. Si necesitas aislamiento, usa [`agents.defaults.sandbox`](/es/gateway/sandboxing) (y/o configuración de sandbox por agente).
|
||||
El espacio de trabajo es el **cwd predeterminado**, no un sandbox estricto. Las herramientas resuelven las rutas relativas contra el espacio de trabajo, pero las rutas absolutas aún pueden llegar a otros lugares del host a menos que el sandboxing esté habilitado. Si necesitas aislamiento, usa [`agents.defaults.sandbox`](/es/gateway/sandboxing) (y/o una configuración de sandbox por agente).
|
||||
|
||||
Cuando el sandboxing está habilitado y `workspaceAccess` no es `"rw"`, las herramientas operan dentro de un espacio de trabajo en sandbox bajo `~/.openclaw/sandboxes`, no en tu espacio de trabajo del host.
|
||||
Cuando el sandboxing está habilitado y `workspaceAccess` no es `"rw"`, las herramientas operan dentro de un espacio de trabajo de sandbox bajo `~/.openclaw/sandboxes`, no en tu espacio de trabajo del host.
|
||||
</Warning>
|
||||
|
||||
## Ubicación predeterminada
|
||||
@ -40,13 +40,13 @@ Cuando el sandboxing está habilitado y `workspaceAccess` no es `"rw"`, las herr
|
||||
}
|
||||
```
|
||||
|
||||
`openclaw onboard`, `openclaw configure` o `openclaw setup` crearán el espacio de trabajo y sembrarán los archivos bootstrap si faltan.
|
||||
`openclaw onboard`, `openclaw configure` u `openclaw setup` crearán el espacio de trabajo y sembrarán los archivos de arranque si faltan.
|
||||
|
||||
<Note>
|
||||
La copia de semilla del sandbox solo acepta archivos normales dentro del espacio de trabajo; los alias symlink/hardlink que se resuelven fuera del espacio de trabajo de origen se ignoran.
|
||||
Las copias de semilla de sandbox solo aceptan archivos normales dentro del espacio de trabajo; los alias de symlink/hardlink que se resuelven fuera del espacio de trabajo de origen se ignoran.
|
||||
</Note>
|
||||
|
||||
Si ya gestionas tú mismo los archivos del espacio de trabajo, puedes deshabilitar la creación de archivos bootstrap:
|
||||
Si ya gestionas tú mismo los archivos del espacio de trabajo, puedes desactivar la creación de archivos de arranque:
|
||||
|
||||
```json5
|
||||
{ agents: { defaults: { skipBootstrap: true } } }
|
||||
@ -54,12 +54,12 @@ Si ya gestionas tú mismo los archivos del espacio de trabajo, puedes deshabilit
|
||||
|
||||
## Carpetas adicionales del espacio de trabajo
|
||||
|
||||
Las instalaciones antiguas pueden haber creado `~/openclaw`. Mantener varios directorios de espacio de trabajo puede causar una deriva confusa de autenticación o estado, porque solo un espacio de trabajo está activo a la vez.
|
||||
Las instalaciones anteriores pueden haber creado `~/openclaw`. Mantener varios directorios de espacio de trabajo puede causar confusiones de autenticación o desviaciones de estado, porque solo un espacio de trabajo está activo a la vez.
|
||||
|
||||
<Note>
|
||||
**Recomendación:** mantén un único espacio de trabajo activo. Si ya no usas las carpetas adicionales, archívalas o muévelas a la Papelera (por ejemplo `trash ~/openclaw`). Si mantienes varios espacios de trabajo intencionalmente, asegúrate de que `agents.defaults.workspace` apunte al activo.
|
||||
**Recomendación:** mantén un único espacio de trabajo activo. Si ya no usas las carpetas adicionales, archívalas o muévelas a la papelera (por ejemplo, `trash ~/openclaw`). Si mantienes intencionalmente varios espacios de trabajo, asegúrate de que `agents.defaults.workspace` apunte al activo.
|
||||
|
||||
`openclaw doctor` advierte cuando detecta directorios adicionales de espacio de trabajo.
|
||||
`openclaw doctor` advierte cuando detecta directorios de espacio de trabajo adicionales.
|
||||
</Note>
|
||||
|
||||
## Mapa de archivos del espacio de trabajo
|
||||
@ -68,62 +68,63 @@ Estos son los archivos estándar que OpenClaw espera dentro del espacio de traba
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="AGENTS.md — instrucciones operativas">
|
||||
Instrucciones operativas para el agente y cómo debe usar la memoria. Se carga al inicio de cada sesión. Buen lugar para reglas, prioridades y detalles sobre “cómo comportarse”.
|
||||
Instrucciones operativas para el agente y cómo debe usar la memoria. Se cargan al inicio de cada sesión. Buen lugar para reglas, prioridades y detalles sobre "cómo comportarse".
|
||||
</Accordion>
|
||||
<Accordion title="SOUL.md — personalidad y tono">
|
||||
Personalidad, tono y límites. Se carga en cada sesión. Guía: [Guía de personalidad de SOUL.md](/es/concepts/soul).
|
||||
<Accordion title="SOUL.md — persona y tono">
|
||||
Persona, tono y límites. Se carga en cada sesión. Guía: [guía de personalidad de SOUL.md](/es/concepts/soul).
|
||||
</Accordion>
|
||||
<Accordion title="USER.md — quién es el usuario">
|
||||
Quién es el usuario y cómo dirigirse a él. Se carga en cada sesión.
|
||||
</Accordion>
|
||||
<Accordion title="IDENTITY.md — nombre, vibra y emoji">
|
||||
El nombre, la vibra y el emoji del agente. Se crea/actualiza durante el ritual bootstrap.
|
||||
<Accordion title="IDENTITY.md — nombre, estilo, emoji">
|
||||
El nombre, el estilo y el emoji del agente. Se crea/actualiza durante el ritual de arranque.
|
||||
</Accordion>
|
||||
<Accordion title="TOOLS.md — convenciones de herramientas locales">
|
||||
Notas sobre tus herramientas y convenciones locales. No controla la disponibilidad de herramientas; es solo orientación.
|
||||
Notas sobre tus herramientas locales y convenciones. No controla la disponibilidad de herramientas; es solo orientación.
|
||||
</Accordion>
|
||||
<Accordion title="HEARTBEAT.md — lista de verificación de Heartbeat">
|
||||
Pequeña lista de verificación opcional para ejecuciones de Heartbeat. Mantenla corta para evitar gasto de tokens.
|
||||
Lista de verificación diminuta opcional para ejecuciones de Heartbeat. Mantenla breve para evitar consumo de tokens.
|
||||
</Accordion>
|
||||
<Accordion title="BOOT.md — lista de verificación de inicio">
|
||||
Lista de verificación de inicio opcional que se ejecuta automáticamente al reiniciar el Gateway (cuando [hooks internos](/es/automation/hooks) están habilitados). Mantenla corta; usa la herramienta de mensajes para envíos salientes.
|
||||
Lista de verificación de inicio opcional que se ejecuta automáticamente al reiniciar el Gateway (cuando los [hooks internos](/es/automation/hooks) están habilitados). Mantenla breve; usa la herramienta de mensajes para envíos salientes.
|
||||
</Accordion>
|
||||
<Accordion title="BOOTSTRAP.md — ritual de primera ejecución">
|
||||
Ritual único de primera ejecución. Solo se crea para un espacio de trabajo completamente nuevo. Elimínalo después de completar el ritual.
|
||||
Ritual de primera ejecución de una sola vez. Solo se crea para un espacio de trabajo completamente nuevo. Elimínalo después de completar el ritual.
|
||||
</Accordion>
|
||||
<Accordion title="memory/YYYY-MM-DD.md — registro diario de memoria">
|
||||
Registro diario de memoria (un archivo por día). Se recomienda leer el de hoy + el de ayer al inicio de la sesión.
|
||||
Registro diario de memoria (un archivo por día). Se recomienda leer hoy + ayer al iniciar la sesión.
|
||||
</Accordion>
|
||||
<Accordion title="MEMORY.md — memoria curada a largo plazo (opcional)">
|
||||
Memoria curada a largo plazo. Solo cargar en la sesión principal y privada (no en contextos compartidos/de grupo). Consulta [Memoria](/es/concepts/memory) para el flujo de trabajo y el volcado automático de memoria.
|
||||
<Accordion title="MEMORY.md — memoria a largo plazo curada (opcional)">
|
||||
Memoria a largo plazo curada. Cárgala solo en la sesión principal y privada (no en contextos compartidos/de grupo). Consulta [Memoria](/es/concepts/memory) para ver el flujo de trabajo y el vaciado automático de memoria.
|
||||
</Accordion>
|
||||
<Accordion title="skills/ — Skills del espacio de trabajo (opcional)">
|
||||
Skills específicos del espacio de trabajo. Es la ubicación de Skills de mayor precedencia para ese espacio de trabajo. Sobrescribe Skills del agente del proyecto, Skills del agente personal, Skills gestionados, Skills incluidos y `skills.load.extraDirs` cuando los nombres coinciden.
|
||||
Skills específicos del espacio de trabajo. Ubicación de Skills de mayor precedencia para ese espacio de trabajo. Sobrescribe Skills de agente de proyecto, Skills de agente personales, Skills gestionados, Skills incluidos y `skills.load.extraDirs` cuando los nombres coinciden.
|
||||
</Accordion>
|
||||
<Accordion title="canvas/ — archivos de la IU de Canvas (opcional)">
|
||||
Archivos de la IU de Canvas para pantallas Node (por ejemplo `canvas/index.html`).
|
||||
<Accordion title="canvas/ — archivos de interfaz de Canvas (opcional)">
|
||||
Archivos de interfaz de Canvas para visualizaciones de nodos (por ejemplo `canvas/index.html`).
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
Si falta algún archivo bootstrap, OpenClaw inyecta un marcador de “archivo faltante” en la sesión y continúa. Los archivos bootstrap grandes se truncan al inyectarse; ajusta los límites con `agents.defaults.bootstrapMaxChars` (predeterminado: 12000) y `agents.defaults.bootstrapTotalMaxChars` (predeterminado: 60000). `openclaw setup` puede recrear valores predeterminados faltantes sin sobrescribir archivos existentes.
|
||||
Si falta algún archivo de arranque, OpenClaw inyecta un marcador de "archivo faltante" en la sesión y continúa. Los archivos de arranque grandes se truncan al inyectarse; ajusta los límites con `agents.defaults.bootstrapMaxChars` (predeterminado: 12000) y `agents.defaults.bootstrapTotalMaxChars` (predeterminado: 60000). `openclaw setup` puede recrear los valores predeterminados faltantes sin sobrescribir los archivos existentes.
|
||||
</Note>
|
||||
|
||||
## Qué NO está en el espacio de trabajo
|
||||
## Lo que NO está en el espacio de trabajo
|
||||
|
||||
Esto vive en `~/.openclaw/` y NO debe confirmarse en el repositorio del espacio de trabajo:
|
||||
Estos viven bajo `~/.openclaw/` y NO deben confirmarse en el repositorio del espacio de trabajo:
|
||||
|
||||
- `~/.openclaw/openclaw.json` (configuración)
|
||||
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (perfiles de autenticación del modelo: OAuth + claves API)
|
||||
- `~/.openclaw/credentials/` (estado de canal/proveedor más datos heredados de importación OAuth)
|
||||
- `~/.openclaw/agents/<agentId>/sessions/` (transcripciones de sesión + metadatos)
|
||||
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (perfiles de autenticación de modelo: OAuth + claves de API)
|
||||
- `~/.openclaw/agents/<agentId>/agent/codex-home/` (cuenta de entorno de ejecución Codex por agente, configuración, Skills, plugins y estado nativo de hilos)
|
||||
- `~/.openclaw/credentials/` (estado de canales/proveedores más datos heredados de importación OAuth)
|
||||
- `~/.openclaw/agents/<agentId>/sessions/` (transcripciones de sesiones + metadatos)
|
||||
- `~/.openclaw/skills/` (Skills gestionados)
|
||||
|
||||
Si necesitas migrar sesiones o configuración, cópialas por separado y mantenlas fuera del control de versiones.
|
||||
|
||||
## Copia de seguridad con Git (recomendado, privado)
|
||||
|
||||
Trata el espacio de trabajo como memoria privada. Ponlo en un repositorio git **privado** para que tenga copia de seguridad y pueda recuperarse.
|
||||
Trata el espacio de trabajo como memoria privada. Ponlo en un repositorio git **privado** para que tenga copia de seguridad y sea recuperable.
|
||||
|
||||
Ejecuta estos pasos en la máquina donde se ejecuta el Gateway (ahí es donde vive el espacio de trabajo).
|
||||
|
||||
@ -141,9 +142,9 @@ Ejecuta estos pasos en la máquina donde se ejecuta el Gateway (ahí es donde vi
|
||||
</Step>
|
||||
<Step title="Agregar un remoto privado">
|
||||
<Tabs>
|
||||
<Tab title="GitHub web UI">
|
||||
<Tab title="Interfaz web de GitHub">
|
||||
1. Crea un nuevo repositorio **privado** en GitHub.
|
||||
2. No lo inicialices con un README (evita conflictos de fusión).
|
||||
2. No lo inicialices con un README (evita conflictos de merge).
|
||||
3. Copia la URL remota HTTPS.
|
||||
4. Agrega el remoto y haz push:
|
||||
|
||||
@ -159,9 +160,9 @@ Ejecuta estos pasos en la máquina donde se ejecuta el Gateway (ahí es donde vi
|
||||
gh repo create openclaw-workspace --private --source . --remote origin --push
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="GitLab web UI">
|
||||
<Tab title="Interfaz web de GitLab">
|
||||
1. Crea un nuevo repositorio **privado** en GitLab.
|
||||
2. No lo inicialices con un README (evita conflictos de fusión).
|
||||
2. No lo inicialices con un README (evita conflictos de merge).
|
||||
3. Copia la URL remota HTTPS.
|
||||
4. Agrega el remoto y haz push:
|
||||
|
||||
@ -189,14 +190,14 @@ Ejecuta estos pasos en la máquina donde se ejecuta el Gateway (ahí es donde vi
|
||||
<Warning>
|
||||
Incluso en un repositorio privado, evita almacenar secretos en el espacio de trabajo:
|
||||
|
||||
- Claves API, tokens OAuth, contraseñas o credenciales privadas.
|
||||
- Claves de API, tokens OAuth, contraseñas o credenciales privadas.
|
||||
- Cualquier cosa bajo `~/.openclaw/`.
|
||||
- Volcados sin procesar de chats o adjuntos sensibles.
|
||||
|
||||
Si debes almacenar referencias sensibles, usa marcadores de posición y guarda el secreto real en otro lugar (gestor de contraseñas, variables de entorno o `~/.openclaw/`).
|
||||
</Warning>
|
||||
|
||||
Sugerencia de `.gitignore` inicial:
|
||||
Plantilla inicial sugerida de `.gitignore`:
|
||||
|
||||
```gitignore
|
||||
.DS_Store
|
||||
@ -213,7 +214,7 @@ Sugerencia de `.gitignore` inicial:
|
||||
Clona el repositorio en la ruta deseada (predeterminada `~/.openclaw/workspace`).
|
||||
</Step>
|
||||
<Step title="Actualizar configuración">
|
||||
Establece `agents.defaults.workspace` en esa ruta dentro de `~/.openclaw/openclaw.json`.
|
||||
Establece `agents.defaults.workspace` en esa ruta en `~/.openclaw/openclaw.json`.
|
||||
</Step>
|
||||
<Step title="Sembrar archivos faltantes">
|
||||
Ejecuta `openclaw setup --workspace <path>` para sembrar cualquier archivo faltante.
|
||||
@ -225,12 +226,12 @@ Sugerencia de `.gitignore` inicial:
|
||||
|
||||
## Notas avanzadas
|
||||
|
||||
- El enrutamiento multiagente puede usar distintos espacios de trabajo por agente. Consulta [Enrutamiento de canales](/es/channels/channel-routing) para la configuración de enrutamiento.
|
||||
- Si `agents.defaults.sandbox` está habilitado, las sesiones no principales pueden usar espacios de trabajo en sandbox por sesión bajo `agents.defaults.sandbox.workspaceRoot`.
|
||||
- El enrutamiento multiagente puede usar diferentes espacios de trabajo por agente. Consulta [Enrutamiento de canales](/es/channels/channel-routing) para la configuración de enrutamiento.
|
||||
- Si `agents.defaults.sandbox` está habilitado, las sesiones no principales pueden usar espacios de trabajo de sandbox por sesión bajo `agents.defaults.sandbox.workspaceRoot`.
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Heartbeat](/es/gateway/heartbeat) — archivo de espacio de trabajo HEARTBEAT.md
|
||||
- [Sandboxing](/es/gateway/sandboxing) — acceso al espacio de trabajo en entornos con sandbox
|
||||
- [Sandboxing](/es/gateway/sandboxing) — acceso al espacio de trabajo en entornos con sandboxing
|
||||
- [Sesión](/es/concepts/session) — rutas de almacenamiento de sesiones
|
||||
- [Órdenes permanentes](/es/automation/standing-orders) — instrucciones persistentes en archivos del espacio de trabajo
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,26 +1,31 @@
|
||||
---
|
||||
read_when:
|
||||
- Quieres usar el arnés de app-server incluido con Codex
|
||||
- Necesitas ejemplos de configuración del arnés de Codex
|
||||
- Quiere usar el arnés `app-server` incluido de Codex
|
||||
- Necesitas ejemplos de configuración del entorno de ejecución de Codex
|
||||
- Quieres que las implementaciones solo con Codex fallen en lugar de recurrir a PI
|
||||
summary: Ejecuta los turnos del agente integrado de OpenClaw mediante el arnés de app-server de Codex incluido
|
||||
title: Entorno de ejecución de Codex
|
||||
summary: Ejecutar turnos del agente integrado de OpenClaw mediante el arnés app-server de Codex incluido
|
||||
title: arnés de Codex
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T05:51:50Z"
|
||||
generated_at: "2026-04-30T20:05:51Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 93abb72e9590aad265e5b6b8691dd16314178c4d255679b4e53da33b792a6e6b
|
||||
source_hash: 335ec60cbdb76579db833eccb5151ffc5bcd28b370ca2e99587abdb578eeee4f
|
||||
source_path: plugins/codex-harness.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
El plugin `codex` incluido permite que OpenClaw ejecute turnos de agente embebidos a través del app-server de Codex en lugar del arnés PI integrado.
|
||||
El plugin `codex` incluido permite que OpenClaw ejecute turnos de agentes integrados mediante el
|
||||
app-server de Codex en lugar del harness PI integrado.
|
||||
|
||||
Usa esto cuando quieras que Codex sea dueño de la sesión de agente de bajo nivel: descubrimiento de modelos, reanudación nativa de hilos, compaction nativa y ejecución en app-server. OpenClaw sigue siendo dueño de los canales de chat, archivos de sesión, selección de modelo, herramientas, aprobaciones, entrega de medios y el espejo visible de la transcripción.
|
||||
Usa esto cuando quieras que Codex sea dueño de la sesión de agente de bajo nivel:
|
||||
descubrimiento de modelos, reanudación nativa de hilos, compaction nativa y ejecución en app-server.
|
||||
OpenClaw sigue siendo dueño de los canales de chat, archivos de sesión, selección de modelos, herramientas,
|
||||
aprobaciones, entrega de medios y el espejo visible de la transcripción.
|
||||
|
||||
Si intentas orientarte, empieza con
|
||||
Si estás intentando orientarte, empieza con
|
||||
[Runtimes de agente](/es/concepts/agent-runtimes). La versión corta es:
|
||||
`openai/gpt-5.5` es la referencia de modelo, `codex` es el runtime, y Telegram, Discord, Slack u otro canal sigue siendo la superficie de comunicación.
|
||||
`openai/gpt-5.5` es la referencia del modelo, `codex` es el runtime, y Telegram,
|
||||
Discord, Slack u otro canal sigue siendo la superficie de comunicación.
|
||||
|
||||
## Qué cambia este plugin
|
||||
|
||||
@ -28,110 +33,173 @@ El plugin `codex` incluido aporta varias capacidades independientes:
|
||||
|
||||
| Capacidad | Cómo se usa | Qué hace |
|
||||
| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
|
||||
| Runtime embebido nativo | `agentRuntime.id: "codex"` | Ejecuta turnos de agente embebidos de OpenClaw a través del app-server de Codex. |
|
||||
| Runtime integrado nativo | `agentRuntime.id: "codex"` | Ejecuta turnos de agentes integrados de OpenClaw mediante el app-server de Codex. |
|
||||
| Comandos nativos de control de chat | `/codex bind`, `/codex resume`, `/codex steer`, ... | Vincula y controla hilos del app-server de Codex desde una conversación de mensajería. |
|
||||
| Proveedor/catálogo del app-server de Codex | Internos de `codex`, expuestos a través del arnés | Permite que el runtime descubra y valide modelos del app-server. |
|
||||
| Ruta de comprensión de medios de Codex | Rutas de compatibilidad de modelos de imagen `codex/*` | Ejecuta turnos acotados del app-server de Codex para modelos de comprensión de imágenes compatibles. |
|
||||
| Reenvío de hooks nativos | Hooks de Plugin alrededor de eventos nativos de Codex | Permite que OpenClaw observe/bloquee eventos compatibles nativos de herramientas/finalización de Codex. |
|
||||
| Proveedor/catálogo del app-server de Codex | componentes internos de `codex`, expuestos mediante el harness | Permite que el runtime descubra y valide modelos del app-server. |
|
||||
| Ruta de comprensión de medios de Codex | rutas de compatibilidad de modelos de imagen `codex/*` | Ejecuta turnos acotados del app-server de Codex para modelos compatibles de comprensión de imágenes. |
|
||||
| Retransmisión de hooks nativos | Hooks de Plugin alrededor de eventos nativos de Codex | Permite que OpenClaw observe/bloquee eventos compatibles nativos de herramienta/finalización de Codex. |
|
||||
|
||||
Activar el plugin pone disponibles esas capacidades. **No**:
|
||||
Habilitar el plugin hace que esas capacidades estén disponibles. **No**:
|
||||
|
||||
- empieza a usar Codex para todos los modelos de OpenAI
|
||||
- convierte referencias de modelo `openai-codex/*` en el runtime nativo
|
||||
- hace que ACP/acpx sea la ruta predeterminada de Codex
|
||||
- convierte referencias de modelo `openai-codex/*` al runtime nativo
|
||||
- convierte ACP/acpx en la ruta predeterminada de Codex
|
||||
- cambia en caliente sesiones existentes que ya registraron un runtime PI
|
||||
- sustituye la entrega de canales de OpenClaw, archivos de sesión, almacenamiento de perfiles de autenticación ni el enrutamiento de mensajes
|
||||
- reemplaza la entrega de canales de OpenClaw, los archivos de sesión, el almacenamiento de perfiles de autenticación ni
|
||||
el enrutamiento de mensajes
|
||||
|
||||
El mismo plugin también es dueño de la superficie nativa de comandos de control de chat `/codex`. Si el plugin está activado y el usuario pide vincular, reanudar, dirigir, detener o inspeccionar hilos de Codex desde el chat, los agentes deberían preferir `/codex ...` sobre ACP. ACP sigue siendo el fallback explícito cuando el usuario pide ACP/acpx o está probando el adaptador ACP de Codex.
|
||||
El mismo plugin también es dueño de la superficie nativa de comandos de control de chat `/codex`. Si
|
||||
el plugin está habilitado y el usuario pide vincular, reanudar, dirigir, detener o inspeccionar
|
||||
hilos de Codex desde el chat, los agentes deberían preferir `/codex ...` sobre ACP. ACP sigue siendo
|
||||
la alternativa explícita cuando el usuario pide ACP/acpx o está probando el adaptador ACP de
|
||||
Codex.
|
||||
|
||||
Los turnos nativos de Codex mantienen los hooks de Plugin de OpenClaw como la capa pública de compatibilidad. Estos son hooks de OpenClaw en proceso, no hooks de comando `hooks.json` de Codex:
|
||||
Los turnos nativos de Codex mantienen los hooks de Plugin de OpenClaw como capa pública de compatibilidad.
|
||||
Estos son hooks en proceso de OpenClaw, no hooks de comando `hooks.json` de Codex:
|
||||
|
||||
- `before_prompt_build`
|
||||
- `before_compaction`, `after_compaction`
|
||||
- `llm_input`, `llm_output`
|
||||
- `before_tool_call`, `after_tool_call`
|
||||
- `before_message_write` para registros de transcripción reflejados
|
||||
- `before_agent_finalize` a través del reenvío `Stop` de Codex
|
||||
- `before_agent_finalize` mediante la retransmisión `Stop` de Codex
|
||||
- `agent_end`
|
||||
|
||||
Los plugins también pueden registrar middleware de resultados de herramientas neutral respecto del runtime para reescribir resultados de herramientas dinámicas de OpenClaw después de que OpenClaw ejecuta la herramienta y antes de que el resultado se devuelva a Codex. Esto es independiente del hook público de Plugin `tool_result_persist`, que transforma escrituras de resultados de herramientas de transcripción propiedad de OpenClaw.
|
||||
Los plugins también pueden registrar middleware neutral al runtime para resultados de herramientas a fin de reescribir
|
||||
resultados dinámicos de herramientas de OpenClaw después de que OpenClaw ejecuta la herramienta y antes de que el
|
||||
resultado se devuelva a Codex. Esto está separado del hook público de Plugin
|
||||
`tool_result_persist`, que transforma escrituras de resultados de herramientas en transcripciones propiedad de OpenClaw.
|
||||
|
||||
Para la semántica de los hooks de Plugin en sí, consulta [Hooks de Plugin](/es/plugins/hooks) y [Comportamiento de guardia de Plugin](/es/tools/plugin).
|
||||
Para la semántica de los hooks de Plugin en sí, consulta [Hooks de Plugin](/es/plugins/hooks)
|
||||
y [Comportamiento de guardia de Plugin](/es/tools/plugin).
|
||||
|
||||
El arnés está desactivado de forma predeterminada. Las configuraciones nuevas deberían mantener las referencias de modelo de OpenAI canónicas como `openai/gpt-*` y forzar explícitamente `agentRuntime.id: "codex"` u `OPENCLAW_AGENT_RUNTIME=codex` cuando quieran ejecución nativa en app-server. Las referencias de modelo heredadas `codex/*` todavía seleccionan automáticamente el arnés por compatibilidad, pero los prefijos de proveedor heredados respaldados por runtime no se muestran como opciones normales de modelo/proveedor.
|
||||
El harness está desactivado de forma predeterminada. Las configuraciones nuevas deberían mantener las referencias de modelo de OpenAI
|
||||
canónicas como `openai/gpt-*` y forzar explícitamente
|
||||
`agentRuntime.id: "codex"` u `OPENCLAW_AGENT_RUNTIME=codex` cuando
|
||||
quieran ejecución nativa en app-server. Las referencias de modelo heredadas `codex/*` todavía seleccionan automáticamente
|
||||
el harness por compatibilidad, pero los prefijos de proveedores heredados respaldados por runtime
|
||||
no se muestran como opciones normales de modelo/proveedor.
|
||||
|
||||
Si el plugin `codex` está activado pero el modelo principal sigue siendo `openai-codex/*`, `openclaw doctor` advierte en lugar de cambiar la ruta. Esto es intencional: `openai-codex/*` sigue siendo la ruta OAuth/suscripción de Codex en PI, y la ejecución nativa en app-server sigue siendo una elección explícita de runtime.
|
||||
Si el plugin `codex` está habilitado pero el modelo principal sigue siendo
|
||||
`openai-codex/*`, `openclaw doctor` advierte en lugar de cambiar la ruta. Eso es
|
||||
intencional: `openai-codex/*` sigue siendo la ruta de OAuth/suscripción de PI Codex, y
|
||||
la ejecución nativa en app-server sigue siendo una opción explícita de runtime.
|
||||
|
||||
## Mapa de rutas
|
||||
|
||||
Usa esta tabla antes de cambiar la configuración:
|
||||
|
||||
| Comportamiento deseado | Referencia de modelo | Configuración de runtime | Requisito de Plugin | Etiqueta de estado esperada |
|
||||
| ------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ |
|
||||
| API de OpenAI a través del ejecutor normal de OpenClaw | `openai/gpt-*` | omitido o `runtime: "pi"` | Proveedor de OpenAI | `Runtime: OpenClaw Pi Default` |
|
||||
| OAuth/suscripción de Codex a través de PI | `openai-codex/gpt-*` | omitido o `runtime: "pi"` | Proveedor OAuth de OpenAI Codex | `Runtime: OpenClaw Pi Default` |
|
||||
| Turnos embebidos nativos del app-server de Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` |
|
||||
| Proveedores mixtos con modo automático conservador | referencias específicas del proveedor | `agentRuntime.id: "auto"` | Runtimes de Plugin opcionales | Depende del runtime seleccionado |
|
||||
| Sesión explícita del adaptador ACP de Codex | Dependiente de prompt/modelo ACP | `sessions_spawn` con `runtime: "acp"` | backend `acpx` saludable | Estado de tarea/sesión ACP |
|
||||
| Comportamiento deseado | Referencia de modelo | Configuración de runtime | Requisito de Plugin | Etiqueta de estado esperada |
|
||||
| ----------------------------------------- | -------------------------- | -------------------------------------- | -------------------------- | ------------------------------- |
|
||||
| API de OpenAI mediante el ejecutor normal de OpenClaw | `openai/gpt-*` | omitido o `runtime: "pi"` | Proveedor de OpenAI | `Runtime: OpenClaw Pi Default` |
|
||||
| OAuth/suscripción de Codex mediante PI | `openai-codex/gpt-*` | omitido o `runtime: "pi"` | Proveedor OAuth de OpenAI Codex | `Runtime: OpenClaw Pi Default` |
|
||||
| Turnos integrados nativos del app-server de Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` |
|
||||
| Proveedores mixtos con modo automático conservador | referencias específicas del proveedor | `agentRuntime.id: "auto"` | Runtimes de plugin opcionales | Depende del runtime seleccionado |
|
||||
| Sesión explícita del adaptador ACP de Codex | depende de prompt/modelo ACP | `sessions_spawn` con `runtime: "acp"` | backend `acpx` saludable | Estado de tarea/sesión ACP |
|
||||
|
||||
La división importante es proveedor frente a runtime:
|
||||
|
||||
- `openai-codex/*` responde "¿qué ruta de proveedor/autenticación debería usar PI?"
|
||||
- `agentRuntime.id: "codex"` responde "¿qué bucle debería ejecutar este turno embebido?"
|
||||
- `/codex ...` responde "¿qué conversación nativa de Codex debería vincular o controlar este chat?"
|
||||
- ACP responde "¿qué proceso de arnés externo debería lanzar acpx?"
|
||||
- `agentRuntime.id: "codex"` responde "¿qué bucle debería ejecutar este
|
||||
turno integrado?"
|
||||
- `/codex ...` responde "¿a qué conversación nativa de Codex debería vincularse
|
||||
o controlar este chat?"
|
||||
- ACP responde "¿qué proceso de harness externo debería lanzar acpx?"
|
||||
|
||||
## Elige el prefijo de modelo correcto
|
||||
|
||||
Las rutas de la familia OpenAI son específicas del prefijo. Usa `openai-codex/*` cuando quieras OAuth de Codex a través de PI; usa `openai/*` cuando quieras acceso directo a la API de OpenAI o cuando estés forzando el arnés nativo del app-server de Codex:
|
||||
Las rutas de la familia OpenAI son específicas del prefijo. Usa `openai-codex/*` cuando quieras
|
||||
OAuth de Codex mediante PI; usa `openai/*` cuando quieras acceso directo a la API de OpenAI o
|
||||
cuando estés forzando el harness nativo del app-server de Codex:
|
||||
|
||||
| Referencia de modelo | Ruta de runtime | Úsalo cuando |
|
||||
| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| `openai/gpt-5.4` | Proveedor de OpenAI a través de la fontanería de OpenClaw/PI | Quieres acceso directo actual a la API de OpenAI Platform con `OPENAI_API_KEY`. |
|
||||
| `openai-codex/gpt-5.5` | OAuth de OpenAI Codex a través de OpenClaw/PI | Quieres autenticación de suscripción ChatGPT/Codex con el ejecutor PI predeterminado. |
|
||||
| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Arnés del app-server de Codex | Quieres ejecución nativa del app-server de Codex para el turno de agente embebido. |
|
||||
| Referencia de modelo | Ruta de runtime | Úsalo cuando |
|
||||
| -------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| `openai/gpt-5.4` | Proveedor de OpenAI mediante la canalización OpenClaw/PI | Quieres acceso actual directo a la API de OpenAI Platform con `OPENAI_API_KEY`. |
|
||||
| `openai-codex/gpt-5.5` | OAuth de OpenAI Codex mediante OpenClaw/PI | Quieres autenticación de suscripción ChatGPT/Codex con el ejecutor PI predeterminado. |
|
||||
| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness del app-server de Codex | Quieres ejecución nativa en el app-server de Codex para el turno de agente integrado. |
|
||||
|
||||
GPT-5.5 actualmente es solo de suscripción/OAuth en OpenClaw. Usa `openai-codex/gpt-5.5` para OAuth de PI, o `openai/gpt-5.5` con el arnés del app-server de Codex. El acceso directo con clave de API para `openai/gpt-5.5` será compatible cuando OpenAI habilite GPT-5.5 en la API pública.
|
||||
GPT-5.5 actualmente es solo por suscripción/OAuth en OpenClaw. Usa
|
||||
`openai-codex/gpt-5.5` para OAuth de PI, o `openai/gpt-5.5` con el harness de
|
||||
app-server de Codex. El acceso directo con clave de API para `openai/gpt-5.5` es compatible
|
||||
una vez que OpenAI habilite GPT-5.5 en la API pública.
|
||||
|
||||
Las referencias heredadas `codex/gpt-*` siguen aceptándose como alias de compatibilidad. La migración de compatibilidad de doctor reescribe las referencias heredadas de runtime principal a referencias de modelo canónicas y registra la política de runtime por separado, mientras que las referencias heredadas solo de fallback quedan sin cambios porque el runtime se configura para todo el contenedor del agente. Las nuevas configuraciones OAuth de PI Codex deberían usar `openai-codex/gpt-*`; las nuevas configuraciones del arnés nativo de app-server deberían usar `openai/gpt-*` más `agentRuntime.id: "codex"`.
|
||||
Las referencias heredadas `codex/gpt-*` siguen aceptándose como alias de compatibilidad. La migración de
|
||||
compatibilidad de doctor reescribe las referencias heredadas de runtime principal a referencias de modelo canónicas
|
||||
y registra la política de runtime por separado, mientras que las referencias heredadas solo de respaldo
|
||||
se dejan sin cambios porque el runtime se configura para todo el contenedor de agente.
|
||||
Las configuraciones nuevas de OAuth de PI Codex deberían usar `openai-codex/gpt-*`; las configuraciones nuevas del harness nativo de
|
||||
app-server deberían usar `openai/gpt-*` más
|
||||
`agentRuntime.id: "codex"`.
|
||||
|
||||
`agents.defaults.imageModel` sigue la misma división de prefijos. Usa `openai-codex/gpt-*` cuando la comprensión de imágenes deba ejecutarse a través de la ruta del proveedor OAuth de OpenAI Codex. Usa `codex/gpt-*` cuando la comprensión de imágenes deba ejecutarse mediante un turno acotado del app-server de Codex. El modelo del app-server de Codex debe anunciar compatibilidad con entrada de imagen; los modelos Codex solo de texto fallan antes de que empiece el turno de medios.
|
||||
`agents.defaults.imageModel` sigue la misma división de prefijos. Usa
|
||||
`openai-codex/gpt-*` cuando la comprensión de imágenes deba ejecutarse mediante la ruta del proveedor
|
||||
OpenAI Codex OAuth. Usa `codex/gpt-*` cuando la comprensión de imágenes deba ejecutarse
|
||||
mediante un turno acotado del app-server de Codex. El modelo del app-server de Codex debe
|
||||
anunciar compatibilidad con entrada de imágenes; los modelos de Codex solo de texto fallan antes de que el turno de medios
|
||||
comience.
|
||||
|
||||
Usa `/status` para confirmar el arnés efectivo de la sesión actual. Si la selección sorprende, activa el registro de depuración para el subsistema `agents/harness` e inspecciona el registro estructurado `agent harness selected` del gateway. Incluye el id del arnés seleccionado, el motivo de selección, la política de runtime/fallback y, en modo `auto`, el resultado de compatibilidad de cada candidato de Plugin.
|
||||
Usa `/status` para confirmar el harness efectivo de la sesión actual. Si la
|
||||
selección sorprende, habilita el registro de depuración para el subsistema `agents/harness`
|
||||
e inspecciona el registro estructurado `agent harness selected` del Gateway. Incluye
|
||||
el id de harness seleccionado, la razón de selección, la política de runtime/respaldo y,
|
||||
en modo `auto`, el resultado de compatibilidad de cada candidato de plugin.
|
||||
|
||||
### Qué significan las advertencias de doctor
|
||||
|
||||
`openclaw doctor` advierte cuando todo esto es cierto:
|
||||
|
||||
- el plugin `codex` incluido está activado o permitido
|
||||
- el plugin `codex` incluido está habilitado o permitido
|
||||
- el modelo principal de un agente es `openai-codex/*`
|
||||
- el runtime efectivo de ese agente no es `codex`
|
||||
|
||||
Esa advertencia existe porque los usuarios a menudo esperan que "plugin de Codex activado" implique "runtime nativo del app-server de Codex". OpenClaw no da ese salto. La advertencia significa:
|
||||
Esa advertencia existe porque los usuarios suelen esperar que "Plugin Codex habilitado" implique
|
||||
"runtime nativo del app-server de Codex." OpenClaw no hace ese salto. La advertencia
|
||||
significa:
|
||||
|
||||
- **No se requiere ningún cambio** si pretendías usar OAuth de ChatGPT/Codex a través de PI.
|
||||
- Cambia el modelo a `openai/<model>` y configura `agentRuntime.id: "codex"` si pretendías ejecución nativa en app-server.
|
||||
- Las sesiones existentes todavía necesitan `/new` o `/reset` después de un cambio de runtime, porque los pins de runtime de sesión son persistentes.
|
||||
- **No se requiere ningún cambio** si pretendías usar OAuth de ChatGPT/Codex mediante PI.
|
||||
- Cambia el modelo a `openai/<model>` y establece
|
||||
`agentRuntime.id: "codex"` si pretendías ejecución nativa en app-server.
|
||||
- Las sesiones existentes aún necesitan `/new` o `/reset` después de un cambio de runtime,
|
||||
porque las fijaciones de runtime de sesión son persistentes.
|
||||
|
||||
La selección de arnés no es un control de sesión en vivo. Cuando se ejecuta un turno embebido, OpenClaw registra el id del arnés seleccionado en esa sesión y sigue usándolo para turnos posteriores con el mismo id de sesión. Cambia la configuración de `agentRuntime` u `OPENCLAW_AGENT_RUNTIME` cuando quieras que sesiones futuras usen otro arnés; usa `/new` o `/reset` para iniciar una sesión nueva antes de cambiar una conversación existente entre PI y Codex. Esto evita reproducir una transcripción por dos sistemas nativos de sesión incompatibles.
|
||||
La selección del harness no es un control de sesión en vivo. Cuando se ejecuta un turno integrado,
|
||||
OpenClaw registra el id del harness seleccionado en esa sesión y sigue usándolo para
|
||||
turnos posteriores en el mismo id de sesión. Cambia la configuración `agentRuntime` o
|
||||
`OPENCLAW_AGENT_RUNTIME` cuando quieras que las sesiones futuras usen otro harness;
|
||||
usa `/new` o `/reset` para iniciar una sesión nueva antes de cambiar una conversación existente
|
||||
entre PI y Codex. Esto evita reproducir una transcripción por medio de
|
||||
dos sistemas de sesión nativos incompatibles.
|
||||
|
||||
Las sesiones heredadas creadas antes de los pins de arnés se tratan como fijadas a PI una vez que tienen historial de transcripción. Usa `/new` o `/reset` para incorporar esa conversación a Codex después de cambiar la configuración.
|
||||
Las sesiones heredadas creadas antes de las fijaciones de harness se tratan como fijadas a PI una vez que
|
||||
tienen historial de transcripción. Usa `/new` o `/reset` para optar esa conversación por
|
||||
Codex después de cambiar la configuración.
|
||||
|
||||
`/status` muestra el runtime efectivo del modelo. El arnés PI predeterminado aparece como `Runtime: OpenClaw Pi Default`, y el arnés del app-server de Codex aparece como `Runtime: OpenAI Codex`.
|
||||
`/status` muestra el runtime de modelo efectivo. El harness PI predeterminado aparece como
|
||||
`Runtime: OpenClaw Pi Default`, y el harness de app-server de Codex aparece como
|
||||
`Runtime: OpenAI Codex`.
|
||||
|
||||
## Requisitos
|
||||
|
||||
- OpenClaw con el plugin `codex` incluido disponible.
|
||||
- App-server de Codex `0.125.0` o más reciente. El plugin incluido gestiona un binario compatible del app-server de Codex de forma predeterminada, por lo que los comandos locales `codex` en `PATH` no afectan al inicio normal del arnés.
|
||||
- Autenticación de Codex disponible para el proceso del app-server o para el puente de autenticación de Codex de OpenClaw.
|
||||
- App-server de Codex `0.125.0` o más reciente. El plugin incluido gestiona un binario
|
||||
compatible del app-server de Codex de forma predeterminada, por lo que los comandos locales `codex` en `PATH` no
|
||||
afectan el inicio normal del harness.
|
||||
- Autenticación de Codex disponible para el proceso app-server o para el puente de autenticación de Codex
|
||||
de OpenClaw. Los lanzamientos locales del app-server usan un home de Codex gestionado por OpenClaw para cada
|
||||
agente y un `HOME` hijo aislado, por lo que no leen tu cuenta personal
|
||||
`~/.codex`, Skills, plugins, configuración, estado de hilos ni
|
||||
`$HOME/.agents/skills` nativos de forma predeterminada.
|
||||
|
||||
El plugin bloquea handshakes de app-server antiguos o sin versión. Esto mantiene a OpenClaw en la superficie de protocolo contra la que se ha probado.
|
||||
El plugin bloquea handshakes del app-server antiguos o sin versión. Eso mantiene
|
||||
OpenClaw en la superficie de protocolo contra la que se ha probado.
|
||||
|
||||
Para pruebas smoke en vivo y en Docker, la autenticación suele venir de la cuenta de la CLI de Codex o de un perfil de autenticación `openai-codex` de OpenClaw. Los lanzamientos locales stdio del app-server también pueden recurrir a `CODEX_API_KEY` / `OPENAI_API_KEY` cuando no hay ninguna cuenta presente.
|
||||
Para pruebas de humo en vivo y en Docker, la autenticación normalmente proviene de la cuenta de la CLI de Codex
|
||||
o de un perfil de autenticación `openai-codex` de OpenClaw. Los lanzamientos locales del app-server por stdio también pueden
|
||||
recurrir a `CODEX_API_KEY` / `OPENAI_API_KEY` cuando no hay ninguna cuenta presente.
|
||||
|
||||
## Configuración mínima
|
||||
|
||||
Usa `openai/gpt-5.5`, activa el plugin incluido y fuerza el arnés `codex`:
|
||||
Usa `openai/gpt-5.5`, habilita el plugin incluido y fuerza el harness `codex`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -153,7 +221,7 @@ Usa `openai/gpt-5.5`, activa el plugin incluido y fuerza el arnés `codex`:
|
||||
}
|
||||
```
|
||||
|
||||
Si tu configuración usa `plugins.allow`, incluye también `codex` ahí:
|
||||
Si tu configuración usa `plugins.allow`, incluye `codex` allí también:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -168,17 +236,19 @@ Si tu configuración usa `plugins.allow`, incluye también `codex` ahí:
|
||||
}
|
||||
```
|
||||
|
||||
Las configuraciones heredadas que establecen `agents.defaults.model` o un modelo de agente en `codex/<model>` todavía activan automáticamente el plugin `codex` incluido. Las configuraciones nuevas deberían preferir `openai/<model>` más la entrada explícita `agentRuntime` anterior.
|
||||
Las configuraciones heredadas que establecen `agents.defaults.model` o un modelo de agente en
|
||||
`codex/<model>` todavía habilitan automáticamente el plugin `codex` incluido. Las configuraciones nuevas deberían
|
||||
preferir `openai/<model>` más la entrada explícita `agentRuntime` anterior.
|
||||
|
||||
## Añadir Codex junto a otros modelos
|
||||
|
||||
No establezcas `agentRuntime.id: "codex"` globalmente si el mismo agente debería cambiar libremente entre Codex y modelos de proveedor que no sean Codex. Un runtime forzado se aplica a cada turno embebido de ese agente o sesión. Si seleccionas un modelo de Anthropic mientras ese runtime está forzado, OpenClaw aun así intenta usar el arnés de Codex y falla de forma cerrada en lugar de enrutar silenciosamente ese turno a través de PI.
|
||||
No configures `agentRuntime.id: "codex"` globalmente si el mismo agente debe alternar libremente entre modelos de proveedores Codex y no Codex. Un runtime forzado se aplica a cada turno integrado de ese agente o sesión. Si seleccionas un modelo Anthropic mientras ese runtime está forzado, OpenClaw sigue intentando usar el arnés de Codex y falla de forma cerrada en vez de enrutar silenciosamente ese turno mediante PI.
|
||||
|
||||
Usa una de estas formas en su lugar:
|
||||
|
||||
- Coloca Codex en un agente dedicado con `agentRuntime.id: "codex"`.
|
||||
- Mantén el agente predeterminado en `agentRuntime.id: "auto"` y el respaldo de PI para el uso normal mixto de proveedores.
|
||||
- Usa referencias heredadas `codex/*` solo por compatibilidad. Las configuraciones nuevas deberían preferir `openai/*` más una política explícita de runtime de Codex.
|
||||
- Pon Codex en un agente dedicado con `agentRuntime.id: "codex"`.
|
||||
- Mantén el agente predeterminado en `agentRuntime.id: "auto"` y el fallback PI para el uso normal con proveedores mixtos.
|
||||
- Usa referencias heredadas `codex/*` solo por compatibilidad. Las configuraciones nuevas deben preferir `openai/*` más una política explícita de runtime Codex.
|
||||
|
||||
Por ejemplo, esto mantiene el agente predeterminado en la selección automática normal y añade un agente Codex separado:
|
||||
|
||||
@ -219,31 +289,31 @@ Por ejemplo, esto mantiene el agente predeterminado en la selección automática
|
||||
|
||||
Con esta forma:
|
||||
|
||||
- El agente `main` predeterminado usa la ruta normal del proveedor y el respaldo de compatibilidad de PI.
|
||||
- El agente `codex` usa el arnés app-server de Codex.
|
||||
- Si Codex falta o no es compatible con el agente `codex`, el turno falla en lugar de usar PI silenciosamente.
|
||||
- El agente `main` predeterminado usa la ruta normal del proveedor y el fallback de compatibilidad PI.
|
||||
- El agente `codex` usa el arnés del app-server de Codex.
|
||||
- Si Codex falta o no es compatible para el agente `codex`, el turno falla en vez de usar PI silenciosamente.
|
||||
|
||||
## Enrutamiento de comandos de agente
|
||||
|
||||
Los agentes deberían enrutar las solicitudes de usuario por intención, no solo por la palabra "Codex":
|
||||
Los agentes deben enrutar las solicitudes de usuario por intención, no solo por la palabra "Codex":
|
||||
|
||||
| Si el usuario pide... | El agente debería usar... |
|
||||
| El usuario pide... | El agente debe usar... |
|
||||
| -------------------------------------------------------- | ------------------------------------------------ |
|
||||
| "Vincula este chat a Codex" | `/codex bind` |
|
||||
| "Reanuda aquí el hilo de Codex `<id>`" | `/codex resume <id>` |
|
||||
| "Muestra los hilos de Codex" | `/codex threads` |
|
||||
| "Presenta un informe de soporte por una ejecución defectuosa de Codex" | `/diagnostics [note]` |
|
||||
| "Envía comentarios de Codex solo para este hilo adjunto" | `/codex diagnostics [note]` |
|
||||
| "Usa Codex como runtime para este agente" | cambio de configuración a `agentRuntime.id` |
|
||||
| "Vincula este chat a Codex" | `/codex bind` |
|
||||
| "Reanuda aquí el hilo Codex `<id>`" | `/codex resume <id>` |
|
||||
| "Muestra los hilos Codex" | `/codex threads` |
|
||||
| "Presenta un informe de soporte por una ejecución mala de Codex" | `/diagnostics [note]` |
|
||||
| "Envía solo comentarios de Codex para este hilo adjunto" | `/codex diagnostics [note]` |
|
||||
| "Usa Codex como runtime para este agente" | cambio de configuración en `agentRuntime.id` |
|
||||
| "Usa mi suscripción de ChatGPT/Codex con OpenClaw normal" | referencias de modelo `openai-codex/*` |
|
||||
| "Ejecuta Codex mediante ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` |
|
||||
| "Inicia Claude Code/Gemini/OpenCode/Cursor en un hilo" | ACP/acpx, no `/codex` ni subagentes nativos |
|
||||
| "Ejecuta Codex mediante ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` |
|
||||
| "Inicia Claude Code/Gemini/OpenCode/Cursor en un hilo" | ACP/acpx, no `/codex` y no subagentes nativos |
|
||||
|
||||
OpenClaw solo anuncia la guía de generación de ACP a los agentes cuando ACP está habilitado, se puede despachar y está respaldado por un backend de runtime cargado. Si ACP no está disponible, el prompt del sistema y las Skills del Plugin no deberían enseñar al agente sobre el enrutamiento de ACP.
|
||||
OpenClaw solo anuncia orientación de generación ACP a los agentes cuando ACP está habilitado, es despachable y está respaldado por un backend de runtime cargado. Si ACP no está disponible, el prompt del sistema y las Skills del Plugin no deben enseñar al agente sobre el enrutamiento ACP.
|
||||
|
||||
## Despliegues solo con Codex
|
||||
## Implementaciones solo Codex
|
||||
|
||||
Fuerza el arnés de Codex cuando necesites demostrar que cada turno de agente integrado usa Codex. Los runtimes explícitos de Plugin tienen de forma predeterminada ningún respaldo de PI, así que `fallback: "none"` es opcional, pero a menudo resulta útil como documentación:
|
||||
Fuerza el arnés de Codex cuando necesites demostrar que cada turno de agente integrado usa Codex. Los runtimes explícitos de Plugin no tienen fallback PI de forma predeterminada, por lo que `fallback: "none"` es opcional, pero a menudo útil como documentación:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -259,13 +329,13 @@ Fuerza el arnés de Codex cuando necesites demostrar que cada turno de agente in
|
||||
}
|
||||
```
|
||||
|
||||
Sobrescritura de entorno:
|
||||
Anulación por entorno:
|
||||
|
||||
```bash
|
||||
OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
|
||||
```
|
||||
|
||||
Con Codex forzado, OpenClaw falla temprano si el Plugin de Codex está deshabilitado, el app-server es demasiado antiguo o el app-server no puede iniciar. Define `OPENCLAW_AGENT_HARNESS_FALLBACK=pi` solo si quieres intencionalmente que PI gestione una selección de arnés faltante.
|
||||
Con Codex forzado, OpenClaw falla pronto si el Plugin de Codex está deshabilitado, el app-server es demasiado antiguo o el app-server no puede iniciarse. Configura `OPENCLAW_AGENT_HARNESS_FALLBACK=pi` solo si quieres intencionalmente que PI gestione la selección de arnés faltante.
|
||||
|
||||
## Codex por agente
|
||||
|
||||
@ -300,11 +370,11 @@ Puedes hacer que un agente sea solo Codex mientras el agente predeterminado cons
|
||||
}
|
||||
```
|
||||
|
||||
Usa los comandos de sesión normales para cambiar agentes y modelos. `/new` crea una sesión nueva de OpenClaw y el arnés de Codex crea o reanuda su hilo app-server sidecar según sea necesario. `/reset` borra la vinculación de sesión de OpenClaw para ese hilo y permite que el siguiente turno resuelva de nuevo el arnés desde la configuración actual.
|
||||
Usa comandos de sesión normales para cambiar de agentes y modelos. `/new` crea una sesión nueva de OpenClaw, y el arnés de Codex crea o reanuda su hilo sidecar de app-server según sea necesario. `/reset` borra la vinculación de sesión de OpenClaw para ese hilo y permite que el siguiente turno vuelva a resolver el arnés desde la configuración actual.
|
||||
|
||||
## Descubrimiento de modelos
|
||||
|
||||
De forma predeterminada, el Plugin de Codex pide al app-server los modelos disponibles. Si el descubrimiento falla o agota el tiempo de espera, usa un catálogo de respaldo incluido para:
|
||||
De forma predeterminada, el Plugin de Codex pide al app-server los modelos disponibles. Si el descubrimiento falla o agota el tiempo de espera, usa un catálogo fallback incluido para:
|
||||
|
||||
- GPT-5.5
|
||||
- GPT-5.4 mini
|
||||
@ -330,7 +400,7 @@ Puedes ajustar el descubrimiento en `plugins.entries.codex.config.discovery`:
|
||||
}
|
||||
```
|
||||
|
||||
Deshabilita el descubrimiento cuando quieras que el inicio evite sondear Codex y se limite al catálogo de respaldo:
|
||||
Deshabilita el descubrimiento cuando quieras que el inicio evite sondear Codex y se mantenga en el catálogo fallback:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -357,11 +427,11 @@ De forma predeterminada, el Plugin inicia localmente el binario Codex gestionado
|
||||
codex app-server --listen stdio://
|
||||
```
|
||||
|
||||
El binario gestionado se declara como dependencia de runtime de Plugin incluida y se prepara con el resto de las dependencias del Plugin `codex`. Esto mantiene la versión del app-server vinculada al Plugin incluido en lugar de cualquier CLI de Codex separada que esté instalada localmente. Define `appServer.command` solo cuando quieras ejecutar intencionalmente un ejecutable diferente.
|
||||
El binario gestionado se declara como una dependencia de runtime de Plugin incluida y se prepara con el resto de las dependencias del Plugin `codex`. Esto mantiene la versión del app-server vinculada al Plugin incluido en vez de a cualquier CLI de Codex independiente que esté instalada localmente. Configura `appServer.command` solo cuando quieras intencionalmente ejecutar un ejecutable distinto.
|
||||
|
||||
De forma predeterminada, OpenClaw inicia sesiones locales del arnés de Codex en modo YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` y `sandbox: "danger-full-access"`. Esta es la postura de operador local de confianza usada para heartbeats autónomos: Codex puede usar herramientas de shell y red sin detenerse en prompts de aprobación nativos que nadie está presente para responder.
|
||||
De forma predeterminada, OpenClaw inicia sesiones locales del arnés de Codex en modo YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` y `sandbox: "danger-full-access"`. Esta es la postura de operador local de confianza que se usa para Heartbeats autónomos: Codex puede usar herramientas de shell y red sin detenerse en prompts de aprobación nativos que no hay nadie para responder.
|
||||
|
||||
Para optar por aprobaciones revisadas por el guardián de Codex, define `appServer.mode: "guardian"`:
|
||||
Para optar por aprobaciones revisadas por el guardián de Codex, configura `appServer.mode: "guardian"`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -381,11 +451,11 @@ Para optar por aprobaciones revisadas por el guardián de Codex, define `appServ
|
||||
}
|
||||
```
|
||||
|
||||
El modo Guardian usa la ruta nativa de aprobación con revisión automática de Codex. Cuando Codex pide salir del sandbox, escribir fuera del workspace o añadir permisos como acceso de red, Codex enruta esa solicitud de aprobación al revisor nativo en lugar de a un prompt humano. El revisor aplica el marco de riesgo de Codex y aprueba o deniega la solicitud específica. Usa Guardian cuando quieras más barreras de protección que el modo YOLO, pero aun así necesites que agentes desatendidos avancen.
|
||||
El modo guardián usa la ruta de aprobación de revisión automática nativa de Codex. Cuando Codex pide salir del sandbox, escribir fuera del espacio de trabajo o añadir permisos como acceso de red, Codex enruta esa solicitud de aprobación al revisor nativo en vez de a un prompt humano. El revisor aplica el marco de riesgos de Codex y aprueba o deniega la solicitud específica. Usa Guardián cuando quieras más protecciones que en modo YOLO pero sigas necesitando que los agentes desatendidos avancen.
|
||||
|
||||
El preset `guardian` se expande a `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"` y `sandbox: "workspace-write"`. Los campos de política individuales siguen sobrescribiendo `mode`, así que los despliegues avanzados pueden mezclar el preset con elecciones explícitas. El valor de revisor anterior `guardian_subagent` todavía se acepta como alias de compatibilidad, pero las configuraciones nuevas deberían usar `auto_review`.
|
||||
El preset `guardian` se expande a `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"` y `sandbox: "workspace-write"`. Los campos de política individuales siguen anulando `mode`, por lo que las implementaciones avanzadas pueden mezclar el preset con opciones explícitas. El valor de revisor anterior `guardian_subagent` sigue aceptándose como alias de compatibilidad, pero las configuraciones nuevas deben usar `auto_review`.
|
||||
|
||||
Para un app-server que ya está en ejecución, usa transporte WebSocket:
|
||||
Para un app-server ya en ejecución, usa transporte WebSocket:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -407,15 +477,26 @@ Para un app-server que ya está en ejecución, usa transporte WebSocket:
|
||||
}
|
||||
```
|
||||
|
||||
Los lanzamientos stdio del app-server heredan de forma predeterminada el entorno de proceso de OpenClaw, pero OpenClaw es dueño del puente de cuenta del app-server de Codex. La autenticación se selecciona en este orden:
|
||||
Los lanzamientos de app-server por stdio heredan de forma predeterminada el entorno del proceso de OpenClaw, pero OpenClaw posee el puente de cuenta del app-server de Codex y configura tanto `CODEX_HOME` como `HOME` en directorios por agente bajo el estado de OpenClaw de ese agente. El cargador de Skills propio de Codex lee `$CODEX_HOME/skills` y `$HOME/.agents/skills`, por lo que ambos valores quedan aislados para lanzamientos locales de app-server. Eso mantiene las Skills, plugins, configuración, cuentas y estado de hilos nativos de Codex acotados al agente de OpenClaw en vez de filtrarse desde el directorio personal de la CLI de Codex del operador.
|
||||
|
||||
1. Un perfil explícito de autenticación de OpenClaw Codex para el agente.
|
||||
2. La cuenta existente del app-server, como un inicio de sesión local de ChatGPT en la CLI de Codex.
|
||||
3. Solo para lanzamientos locales stdio del app-server, `CODEX_API_KEY`, luego `OPENAI_API_KEY`, cuando no hay cuenta de app-server presente y todavía se requiere autenticación de OpenAI.
|
||||
Los plugins de OpenClaw y las instantáneas de Skills de OpenClaw siguen fluyendo por el registro de Plugin y el cargador de Skills propios de OpenClaw. Los recursos personales de la CLI de Codex no. Si tienes Skills o plugins útiles de la CLI de Codex que deban pasar a formar parte de un agente de OpenClaw, inventaríalos explícitamente:
|
||||
|
||||
Cuando OpenClaw detecta un perfil de autenticación de Codex de estilo suscripción de ChatGPT, elimina `CODEX_API_KEY` y `OPENAI_API_KEY` del proceso hijo de Codex generado. Eso mantiene disponibles las claves de API de nivel Gateway para embeddings o modelos directos de OpenAI sin hacer que los turnos nativos del app-server de Codex se facturen accidentalmente mediante la API. Los perfiles explícitos de clave de API de Codex y el respaldo local stdio con clave de entorno usan inicio de sesión de app-server en lugar del entorno heredado del proceso hijo. Las conexiones WebSocket del app-server no reciben respaldo de clave de API de entorno de Gateway; usa un perfil de autenticación explícito o la cuenta propia del app-server remoto.
|
||||
```bash
|
||||
openclaw migrate codex --dry-run
|
||||
openclaw migrate apply codex --yes
|
||||
```
|
||||
|
||||
Si un despliegue necesita aislamiento adicional de entorno, añade esas variables a `appServer.clearEnv`:
|
||||
El proveedor de migración de Codex copia Skills al espacio de trabajo actual del agente de OpenClaw. Los plugins nativos, hooks y archivos de configuración de Codex se reportan o archivan para revisión manual en vez de activarse automáticamente, porque pueden ejecutar comandos, exponer servidores MCP o portar credenciales.
|
||||
|
||||
La autenticación se selecciona en este orden:
|
||||
|
||||
1. Un perfil de autenticación explícito de OpenClaw Codex para el agente.
|
||||
2. La cuenta existente del app-server en el directorio de inicio de Codex de ese agente.
|
||||
3. Solo para lanzamientos locales de app-server por stdio, `CODEX_API_KEY`, luego `OPENAI_API_KEY`, cuando no hay una cuenta de app-server presente y la autenticación de OpenAI sigue siendo requerida.
|
||||
|
||||
Cuando OpenClaw detecta un perfil de autenticación Codex de estilo suscripción de ChatGPT, elimina `CODEX_API_KEY` y `OPENAI_API_KEY` del proceso hijo de Codex generado. Eso mantiene disponibles las claves API de nivel Gateway para embeddings o modelos OpenAI directos sin hacer que los turnos nativos del app-server de Codex se facturen accidentalmente mediante la API. Los perfiles explícitos con clave API de Codex y el fallback local por clave de entorno stdio usan inicio de sesión del app-server en vez de entorno heredado del proceso hijo. Las conexiones de app-server por WebSocket no reciben fallback de clave API de entorno de Gateway; usa un perfil de autenticación explícito o la propia cuenta del app-server remoto.
|
||||
|
||||
Si una implementación necesita aislamiento de entorno adicional, añade esas variables a `appServer.clearEnv`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -438,38 +519,36 @@ Si un despliegue necesita aislamiento adicional de entorno, añade esas variable
|
||||
|
||||
Campos `appServer` compatibles:
|
||||
|
||||
| Campo | Predeterminado | Significado |
|
||||
| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `transport` | `"stdio"` | `"stdio"` inicia Codex; `"websocket"` se conecta a `url`. |
|
||||
| `command` | binario administrado de Codex | Ejecutable para el transporte stdio. Déjalo sin definir para usar el binario administrado; configúralo solo para una sustitución explícita. |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | Argumentos para el transporte stdio. |
|
||||
| `url` | sin definir | URL de app-server WebSocket. |
|
||||
| `authToken` | sin definir | Token Bearer para el transporte WebSocket. |
|
||||
| `headers` | `{}` | Encabezados WebSocket adicionales. |
|
||||
| `clearEnv` | `[]` | Nombres de variables de entorno adicionales eliminadas del proceso app-server stdio iniciado después de que OpenClaw construye su entorno heredado. |
|
||||
| `requestTimeoutMs` | `60000` | Tiempo de espera para llamadas del plano de control de app-server. |
|
||||
| `mode` | `"yolo"` | Preajuste para ejecución YOLO o revisada por guardian. |
|
||||
| `approvalPolicy` | `"never"` | Política de aprobación nativa de Codex enviada al iniciar/reanudar hilo/turno. |
|
||||
| `sandbox` | `"danger-full-access"` | Modo sandbox nativo de Codex enviado al iniciar/reanudar hilo. |
|
||||
| `approvalsReviewer` | `"user"` | Usa `"auto_review"` para permitir que Codex revise las solicitudes de aprobación nativas. `guardian_subagent` sigue siendo un alias heredado. |
|
||||
| `serviceTier` | sin definir | Nivel de servicio opcional de app-server de Codex: `"fast"`, `"flex"` o `null`. Los valores heredados no válidos se ignoran. |
|
||||
| Campo | Predeterminado | Significado |
|
||||
| ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `transport` | `"stdio"` | `"stdio"` inicia Codex; `"websocket"` se conecta a `url`. |
|
||||
| `command` | binario administrado de Codex | Ejecutable para el transporte stdio. Déjalo sin definir para usar el binario administrado; configúralo solo para una sobrescritura explícita. |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | Argumentos para el transporte stdio. |
|
||||
| `url` | sin definir | URL del app-server WebSocket. |
|
||||
| `authToken` | sin definir | Token Bearer para el transporte WebSocket. |
|
||||
| `headers` | `{}` | Encabezados WebSocket adicionales. |
|
||||
| `clearEnv` | `[]` | Nombres de variables de entorno adicionales eliminadas del proceso app-server stdio iniciado después de que OpenClaw construye su entorno heredado. `CODEX_HOME` y `HOME` están reservadas para el aislamiento de Codex por agente de OpenClaw en lanzamientos locales. |
|
||||
| `requestTimeoutMs` | `60000` | Tiempo de espera para llamadas del plano de control del app-server. |
|
||||
| `mode` | `"yolo"` | Preajuste para ejecución YOLO o revisada por guardian. |
|
||||
| `approvalPolicy` | `"never"` | Política de aprobación nativa de Codex enviada al iniciar/reanudar hilo/turno. |
|
||||
| `sandbox` | `"danger-full-access"` | Modo sandbox nativo de Codex enviado al iniciar/reanudar hilo. |
|
||||
| `approvalsReviewer` | `"user"` | Usa `"auto_review"` para permitir que Codex revise solicitudes de aprobación nativas. `guardian_subagent` sigue siendo un alias heredado. |
|
||||
| `serviceTier` | sin definir | Nivel de servicio opcional del app-server de Codex: `"fast"`, `"flex"` o `null`. Los valores heredados no válidos se ignoran. |
|
||||
|
||||
Las llamadas dinámicas a herramientas propiedad de OpenClaw se limitan de forma
|
||||
independiente de `appServer.requestTimeoutMs`: cada solicitud `item/tool/call` de
|
||||
Codex debe recibir una respuesta de OpenClaw en un plazo de 30 segundos. Al
|
||||
agotarse el tiempo de espera, OpenClaw aborta la señal de la herramienta cuando
|
||||
se admite y devuelve una respuesta fallida de herramienta dinámica a Codex para
|
||||
que el turno pueda continuar en lugar de dejar la sesión en `processing`.
|
||||
Las llamadas dinámicas a herramientas propiedad de OpenClaw se limitan de forma independiente de
|
||||
`appServer.requestTimeoutMs`: cada solicitud Codex `item/tool/call` debe recibir
|
||||
una respuesta de OpenClaw en un plazo de 30 segundos. Al agotarse el tiempo de espera, OpenClaw aborta la señal de herramienta
|
||||
cuando es compatible y devuelve una respuesta de herramienta dinámica fallida a Codex para que
|
||||
el turno pueda continuar en lugar de dejar la sesión en `processing`.
|
||||
|
||||
Después de que OpenClaw responde a una solicitud de app-server de Codex con
|
||||
alcance de turno, el arnés también espera que Codex termine el turno nativo con
|
||||
`turn/completed`. Si app-server queda en silencio durante 60 segundos después de
|
||||
esa respuesta, OpenClaw intenta interrumpir el turno de Codex, registra un
|
||||
tiempo de espera de diagnóstico y libera el carril de sesión de OpenClaw para
|
||||
que los mensajes de chat de seguimiento no queden en cola detrás de un turno
|
||||
Después de que OpenClaw responde a una solicitud app-server de Codex con alcance de turno, el arnés
|
||||
también espera que Codex finalice el turno nativo con `turn/completed`. Si el
|
||||
app-server queda en silencio durante 60 segundos después de esa respuesta, OpenClaw interrumpe
|
||||
el turno de Codex con el mejor esfuerzo, registra un tiempo de espera de diagnóstico y libera el
|
||||
carril de sesión de OpenClaw para que los mensajes de chat posteriores no queden en cola detrás de un turno
|
||||
nativo obsoleto.
|
||||
|
||||
Las sustituciones de entorno siguen disponibles para pruebas locales:
|
||||
Las sobrescrituras de entorno siguen disponibles para pruebas locales:
|
||||
|
||||
- `OPENCLAW_CODEX_APP_SERVER_BIN`
|
||||
- `OPENCLAW_CODEX_APP_SERVER_ARGS`
|
||||
@ -483,24 +562,22 @@ Las sustituciones de entorno siguen disponibles para pruebas locales:
|
||||
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` se eliminó. Usa
|
||||
`plugins.entries.codex.config.appServer.mode: "guardian"` en su lugar, o
|
||||
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` para pruebas locales puntuales. Se
|
||||
prefiere la configuración para implementaciones repetibles porque mantiene el
|
||||
comportamiento del plugin en el mismo archivo revisado que el resto de la
|
||||
configuración del arnés de Codex.
|
||||
prefiere la configuración para despliegues repetibles porque mantiene el comportamiento del plugin en el
|
||||
mismo archivo revisado que el resto de la configuración del arnés de Codex.
|
||||
|
||||
## Uso de computadora
|
||||
|
||||
Computer Use se cubre en su propia guía de configuración:
|
||||
[Codex Computer Use](/es/plugins/codex-computer-use).
|
||||
El uso de computadora se cubre en su propia guía de configuración:
|
||||
[Uso de computadora de Codex](/es/plugins/codex-computer-use).
|
||||
|
||||
La versión corta: OpenClaw no incluye como proveedor la app de control de
|
||||
escritorio ni ejecuta acciones de escritorio por sí mismo. Prepara app-server de
|
||||
Codex, verifica que el servidor MCP `computer-use` esté disponible y luego deja
|
||||
que Codex gestione las llamadas nativas a herramientas MCP durante los turnos en
|
||||
modo Codex.
|
||||
La versión breve: OpenClaw no integra como proveedor la app de control de escritorio ni ejecuta
|
||||
acciones de escritorio por sí mismo. Prepara el app-server de Codex, verifica que el
|
||||
servidor MCP `computer-use` esté disponible y luego permite que Codex gestione las llamadas nativas
|
||||
a herramientas MCP durante los turnos en modo Codex.
|
||||
|
||||
Para acceso directo al controlador TryCua fuera del flujo del marketplace de
|
||||
Codex, registra `cua-driver mcp` con `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`.
|
||||
Consulta [Codex Computer Use](/es/plugins/codex-computer-use) para ver la distinción
|
||||
Para acceso directo al controlador TryCua fuera del flujo de marketplace de Codex, registra
|
||||
`cua-driver mcp` con `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`.
|
||||
Consulta [Uso de computadora de Codex](/es/plugins/codex-computer-use) para ver la distinción
|
||||
entre Computer Use propiedad de Codex y el registro MCP directo.
|
||||
|
||||
Configuración mínima:
|
||||
@ -538,21 +615,19 @@ La configuración se puede comprobar o instalar desde la superficie de comandos:
|
||||
- `/codex computer-use install --source <marketplace-source>`
|
||||
- `/codex computer-use install --marketplace-path <path>`
|
||||
|
||||
Computer Use es específico de macOS y puede requerir permisos locales del
|
||||
sistema operativo antes de que el servidor MCP de Codex pueda controlar apps. Si
|
||||
`computerUse.enabled` es true y el servidor MCP no está disponible, los turnos
|
||||
en modo Codex fallan antes de que el hilo se inicie, en lugar de ejecutarse en
|
||||
silencio sin las herramientas nativas de Computer Use. Consulta
|
||||
[Codex Computer Use](/es/plugins/codex-computer-use) para conocer las opciones de
|
||||
marketplace, los límites del catálogo remoto, los motivos de estado y la
|
||||
solución de problemas.
|
||||
Computer Use es específico de macOS y puede requerir permisos locales del sistema operativo antes de que el
|
||||
servidor MCP de Codex pueda controlar apps. Si `computerUse.enabled` es true y el servidor MCP
|
||||
no está disponible, los turnos en modo Codex fallan antes de que se inicie el hilo en lugar de
|
||||
ejecutarse silenciosamente sin las herramientas nativas de Computer Use. Consulta
|
||||
[Uso de computadora de Codex](/es/plugins/codex-computer-use) para opciones de marketplace,
|
||||
límites del catálogo remoto, motivos de estado y solución de problemas.
|
||||
|
||||
Cuando `computerUse.autoInstall` es true, OpenClaw puede registrar el
|
||||
marketplace estándar incluido de Codex Desktop desde
|
||||
Cuando `computerUse.autoInstall` es true, OpenClaw puede registrar el marketplace estándar
|
||||
incluido de Codex Desktop desde
|
||||
`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` si Codex
|
||||
aún no ha descubierto un marketplace local. Usa `/new` o `/reset` después de
|
||||
cambiar la configuración de runtime o Computer Use para que las sesiones
|
||||
existentes no mantengan una vinculación antigua de PI o de hilo de Codex.
|
||||
cambiar la configuración de runtime o Computer Use para que las sesiones existentes no conserven un enlace antiguo
|
||||
de PI o de hilo de Codex.
|
||||
|
||||
## Recetas comunes
|
||||
|
||||
@ -570,7 +645,7 @@ Codex local con transporte stdio predeterminado:
|
||||
}
|
||||
```
|
||||
|
||||
Validación del arnés solo de Codex:
|
||||
Validación del arnés solo con Codex:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -637,281 +712,166 @@ App-server remoto con encabezados explícitos:
|
||||
}
|
||||
```
|
||||
|
||||
El cambio de modelo sigue controlado por OpenClaw. Cuando una sesión de
|
||||
OpenClaw se adjunta a un hilo de Codex existente, el siguiente turno envía de
|
||||
nuevo a app-server el modelo de OpenAI, el proveedor, la política de aprobación,
|
||||
el sandbox y el nivel de servicio seleccionados actualmente. Cambiar de
|
||||
`openai/gpt-5.5` a `openai/gpt-5.2` conserva la vinculación del hilo, pero pide
|
||||
a Codex que continúe con el modelo recién seleccionado.
|
||||
El cambio de modelo sigue controlado por OpenClaw. Cuando una sesión de OpenClaw está adjunta
|
||||
a un hilo de Codex existente, el siguiente turno envía de nuevo al app-server
|
||||
el modelo de OpenAI, proveedor, política de aprobación, sandbox y nivel de servicio
|
||||
seleccionados actualmente. Cambiar de `openai/gpt-5.5` a `openai/gpt-5.2` mantiene el
|
||||
enlace del hilo, pero solicita a Codex continuar con el modelo recién seleccionado.
|
||||
|
||||
## Comando Codex
|
||||
|
||||
El plugin incluido registra `/codex` como comando slash autorizado. Es genérico
|
||||
y funciona en cualquier canal que admita comandos de texto de OpenClaw.
|
||||
El plugin incluido registra `/codex` como comando slash autorizado. Es
|
||||
genérico y funciona en cualquier canal que admita comandos de texto de OpenClaw.
|
||||
|
||||
Formas comunes:
|
||||
|
||||
- `/codex status` muestra conectividad activa de app-server, modelos, cuenta, límites de tasa, servidores MCP y skills.
|
||||
- `/codex models` lista los modelos activos de app-server de Codex.
|
||||
- `/codex threads [filter]` lista los hilos recientes de Codex.
|
||||
- `/codex status` muestra conectividad en vivo del app-server, modelos, cuenta, límites de tasa, servidores MCP y Skills.
|
||||
- `/codex models` lista los modelos en vivo del app-server de Codex.
|
||||
- `/codex threads [filter]` lista hilos recientes de Codex.
|
||||
- `/codex resume <thread-id>` adjunta la sesión actual de OpenClaw a un hilo de Codex existente.
|
||||
- `/codex compact` pide a app-server de Codex que compacte el hilo adjunto.
|
||||
- `/codex compact` solicita al app-server de Codex compactar el hilo adjunto.
|
||||
- `/codex review` inicia la revisión nativa de Codex para el hilo adjunto.
|
||||
- `/codex diagnostics [note]` pregunta antes de enviar comentarios de diagnóstico de Codex para el hilo adjunto.
|
||||
- `/codex computer-use status` comprueba el plugin de Computer Use configurado y el servidor MCP.
|
||||
- `/codex computer-use install` instala el plugin de Computer Use configurado y recarga los servidores MCP.
|
||||
- `/codex account` muestra el estado de la cuenta y los límites de tasa.
|
||||
- `/codex mcp` lista el estado de los servidores MCP de app-server de Codex.
|
||||
- `/codex skills` lista las skills de app-server de Codex.
|
||||
- `/codex computer-use status` comprueba el plugin Computer Use configurado y el servidor MCP.
|
||||
- `/codex computer-use install` instala el plugin Computer Use configurado y recarga los servidores MCP.
|
||||
- `/codex account` muestra el estado de cuenta y límites de tasa.
|
||||
- `/codex mcp` lista el estado de servidores MCP del app-server de Codex.
|
||||
- `/codex skills` lista las Skills del app-server de Codex.
|
||||
|
||||
### Flujo de depuración común
|
||||
|
||||
Cuando un agente respaldado por Codex hace algo inesperado en Telegram, Discord,
|
||||
Slack u otro canal, empieza con la conversación donde ocurrió el problema:
|
||||
Cuando un agente respaldado por Codex hace algo inesperado en Telegram, Discord, Slack
|
||||
u otro canal, empieza con la conversación donde ocurrió el problema:
|
||||
|
||||
1. Ejecuta `/diagnostics bad tool choice after image upload` u otra nota breve
|
||||
que describa lo que viste.
|
||||
2. Aprueba la solicitud de diagnóstico una vez. La aprobación crea el zip local
|
||||
de diagnósticos del Gateway y, como la sesión usa el arnés de Codex, también
|
||||
2. Aprueba la solicitud de diagnóstico una vez. La aprobación crea el zip de diagnósticos
|
||||
local del Gateway y, como la sesión usa el arnés de Codex, también
|
||||
envía el paquete de comentarios relevante de Codex a los servidores de OpenAI.
|
||||
3. Copia la respuesta de diagnóstico completada en el informe de error o hilo de
|
||||
soporte. Incluye la ruta del paquete local, el resumen de privacidad, los ids
|
||||
de sesión de OpenClaw, los ids de hilo de Codex y una línea `Inspect locally`
|
||||
para cada hilo de Codex.
|
||||
4. Si quieres depurar la ejecución por tu cuenta, ejecuta el comando impreso
|
||||
`Inspect locally` en una terminal. Se parece a `codex resume <thread-id>` y
|
||||
abre el hilo nativo de Codex para que puedas inspeccionar la conversación,
|
||||
continuarla localmente o preguntarle a Codex por qué eligió una herramienta o
|
||||
un plan concretos.
|
||||
3. Copia la respuesta de diagnósticos completada en el informe de error o hilo de soporte.
|
||||
Incluye la ruta del paquete local, el resumen de privacidad, los ids de sesión de OpenClaw,
|
||||
los ids de hilo de Codex y una línea `Inspect locally` para cada hilo de Codex.
|
||||
4. Si quieres depurar la ejecución tú mismo, ejecuta el comando `Inspect locally`
|
||||
impreso en una terminal. Se parece a `codex resume <thread-id>` y abre el
|
||||
hilo nativo de Codex para que puedas inspeccionar la conversación, continuarla localmente
|
||||
o preguntar a Codex por qué eligió una herramienta o plan en particular.
|
||||
|
||||
Usa `/codex diagnostics [note]` solo cuando quieras específicamente la carga de
|
||||
comentarios de Codex para el hilo adjunto actualmente sin el paquete completo de
|
||||
diagnósticos del Gateway de OpenClaw. Para la mayoría de los informes de
|
||||
soporte, `/diagnostics [note]` es el mejor punto de partida porque vincula el
|
||||
estado local del Gateway y los ids de hilo de Codex en una sola respuesta.
|
||||
Consulta [Exportación de diagnósticos](/es/gateway/diagnostics) para ver el modelo
|
||||
de privacidad completo y el comportamiento en chats de grupo.
|
||||
Usa `/codex diagnostics [note]` solo cuando quieras específicamente subir comentarios de Codex para el hilo adjunto actualmente sin el paquete completo de diagnósticos del Gateway de OpenClaw. Para la mayoría de los informes de soporte, `/diagnostics [note]` es el mejor punto de partida porque vincula el estado local del Gateway y los id. de hilos de Codex en una sola respuesta. Consulta [Exportación de diagnósticos](/es/gateway/diagnostics) para ver el modelo completo de privacidad y el comportamiento en chats grupales.
|
||||
|
||||
El núcleo de OpenClaw también expone `/diagnostics [note]` solo para propietarios
|
||||
como el comando general de diagnósticos del Gateway. Su solicitud de aprobación
|
||||
muestra el preámbulo de datos sensibles, enlaza a [Exportación de diagnósticos](/es/gateway/diagnostics)
|
||||
y solicita `openclaw gateway diagnostics export --json` mediante aprobación
|
||||
explícita de exec cada vez. No apruebes diagnósticos con una regla de permitir
|
||||
todo. Después de la aprobación, OpenClaw envía un informe que se puede pegar con
|
||||
la ruta del paquete local y el resumen del manifiesto. Cuando la sesión activa
|
||||
de OpenClaw usa el arnés de Codex, esa misma aprobación también autoriza el
|
||||
envío de los paquetes de comentarios relevantes de Codex a los servidores de
|
||||
OpenAI. La solicitud de aprobación dice que se enviarán comentarios de Codex,
|
||||
pero no lista los ids de sesión o de hilo de Codex antes de la aprobación.
|
||||
El núcleo de OpenClaw también expone `/diagnostics [note]`, solo para propietarios, como el comando general de diagnósticos del Gateway. Su solicitud de aprobación muestra el preámbulo de datos sensibles, enlaza a [Exportación de diagnósticos](/es/gateway/diagnostics) y solicita `openclaw gateway diagnostics export --json` mediante aprobación explícita de ejecución cada vez. No apruebes diagnósticos con una regla de permitir todo. Después de la aprobación, OpenClaw envía un informe que se puede pegar con la ruta del paquete local y el resumen del manifiesto. Cuando la sesión activa de OpenClaw usa el harness de Codex, esa misma aprobación también autoriza el envío de los paquetes relevantes de comentarios de Codex a los servidores de OpenAI. La solicitud de aprobación indica que se enviarán comentarios de Codex, pero no enumera los id. de sesión ni de hilo de Codex antes de la aprobación.
|
||||
|
||||
Si `/diagnostics` lo invoca un propietario en un chat de grupo, OpenClaw mantiene
|
||||
limpio el canal compartido: el grupo recibe solo un aviso breve, mientras que el
|
||||
preámbulo de diagnóstico, las solicitudes de aprobación y los ids de
|
||||
sesión/hilo de Codex se envían al propietario por la ruta privada de aprobación.
|
||||
Si no hay una ruta privada hacia el propietario, OpenClaw rechaza la solicitud
|
||||
del grupo y pide al propietario que la ejecute desde un DM.
|
||||
Si un propietario invoca `/diagnostics` en un chat grupal, OpenClaw mantiene limpio el canal compartido: el grupo recibe solo un aviso breve, mientras que el preámbulo de diagnósticos, las solicitudes de aprobación y los id. de sesión/hilo de Codex se envían al propietario mediante la ruta privada de aprobación. Si no existe una ruta privada para el propietario, OpenClaw rechaza la solicitud del grupo y pide al propietario que la ejecute desde un DM.
|
||||
|
||||
Las llamadas de carga aprobadas de Codex llaman a `feedback/upload` del app-server de Codex y piden
|
||||
al app-server que incluya registros para cada hilo listado y subhilos de Codex generados
|
||||
cuando estén disponibles. La carga pasa por la ruta normal de comentarios de Codex hacia los
|
||||
servidores de OpenAI; si los comentarios de Codex están deshabilitados en ese app-server, el comando devuelve
|
||||
el error del app-server. La respuesta de diagnósticos completada lista los canales,
|
||||
los ids de sesión de OpenClaw, los ids de hilo de Codex y los comandos locales `codex resume <thread-id>`
|
||||
para los hilos que se enviaron. Si deniegas o ignoras la aprobación,
|
||||
OpenClaw no imprime esos ids de Codex. Esta carga no reemplaza la exportación local de
|
||||
diagnósticos del Gateway.
|
||||
La subida aprobada de Codex llama a `feedback/upload` del app-server de Codex y pide al app-server que incluya registros para cada hilo listado y subhilos de Codex generados cuando estén disponibles. La subida pasa por la ruta normal de comentarios de Codex hacia los servidores de OpenAI; si los comentarios de Codex están desactivados en ese app-server, el comando devuelve el error del app-server. La respuesta de diagnósticos completada enumera los canales, los id. de sesión de OpenClaw, los id. de hilo de Codex y los comandos locales `codex resume <thread-id>` para los hilos que se enviaron. Si deniegas o ignoras la aprobación, OpenClaw no imprime esos id. de Codex. Esta subida no reemplaza la exportación local de diagnósticos del Gateway.
|
||||
|
||||
`/codex resume` escribe el mismo archivo de enlace sidecar que el arnés usa para
|
||||
turnos normales. En el siguiente mensaje, OpenClaw reanuda ese hilo de Codex, pasa el
|
||||
modelo de OpenClaw seleccionado actualmente al app-server y mantiene habilitado el historial
|
||||
extendido.
|
||||
`/codex resume` escribe el mismo archivo de enlace auxiliar que usa el harness para los turnos normales. En el siguiente mensaje, OpenClaw reanuda ese hilo de Codex, pasa el modelo de OpenClaw seleccionado actualmente al app-server y mantiene habilitado el historial extendido.
|
||||
|
||||
### Inspeccionar un hilo de Codex desde la CLI
|
||||
|
||||
La forma más rápida de entender una ejecución defectuosa de Codex suele ser abrir directamente el hilo
|
||||
nativo de Codex:
|
||||
La forma más rápida de entender una ejecución incorrecta de Codex suele ser abrir directamente el hilo nativo de Codex:
|
||||
|
||||
```sh
|
||||
codex resume <thread-id>
|
||||
```
|
||||
|
||||
Usa esto cuando notes un bug en una conversación de canal y quieras inspeccionar la
|
||||
sesión problemática de Codex, continuarla localmente o preguntar a Codex por qué eligió
|
||||
una herramienta o una decisión de razonamiento concreta. La ruta más sencilla suele ser ejecutar
|
||||
`/diagnostics [note]` primero: después de aprobarlo, el informe completado lista
|
||||
cada hilo de Codex e imprime un comando `Inspect locally`, por ejemplo
|
||||
`codex resume <thread-id>`. Puedes copiar ese comando directamente en una terminal.
|
||||
Usa esto cuando notes un error en una conversación de canal y quieras inspeccionar la sesión problemática de Codex, continuarla localmente o preguntar a Codex por qué tomó una decisión concreta de herramienta o razonamiento. La ruta más sencilla suele ser ejecutar primero `/diagnostics [note]`: después de aprobarlo, el informe completado enumera cada hilo de Codex e imprime un comando `Inspeccionar localmente`, por ejemplo `codex resume <thread-id>`. Puedes copiar ese comando directamente en una terminal.
|
||||
|
||||
También puedes obtener un id de hilo desde `/codex binding` para el chat actual o
|
||||
`/codex threads [filter]` para hilos recientes del app-server de Codex, y luego ejecutar el mismo
|
||||
comando `codex resume` en tu shell.
|
||||
También puedes obtener un id. de hilo desde `/codex binding` para el chat actual o `/codex threads [filter]` para hilos recientes del app-server de Codex, y luego ejecutar el mismo comando `codex resume` en tu shell.
|
||||
|
||||
La superficie de comandos requiere Codex app-server `0.125.0` o posterior. Los métodos de
|
||||
control individuales se informan como `unsupported by this Codex app-server` si un
|
||||
app-server futuro o personalizado no expone ese método JSON-RPC.
|
||||
La superficie de comandos requiere el app-server de Codex `0.125.0` o posterior. Los métodos de control individuales se reportan como `unsupported by this Codex app-server` si un app-server futuro o personalizado no expone ese método JSON-RPC.
|
||||
|
||||
## Límites de hooks
|
||||
|
||||
El arnés de Codex tiene tres capas de hooks:
|
||||
El harness de Codex tiene tres capas de hooks:
|
||||
|
||||
| Capa | Propietario | Propósito |
|
||||
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
|
||||
| Hooks de plugins de OpenClaw | OpenClaw | Compatibilidad de producto/plugin en arneses PI y Codex. |
|
||||
| Middleware de extensión del app-server de Codex | Plugins incluidos de OpenClaw | Comportamiento de adaptador por turno alrededor de herramientas dinámicas de OpenClaw. |
|
||||
| Capa | Propietario | Propósito |
|
||||
| ------------------------------------- | ------------------------ | -------------------------------------------------------------------- |
|
||||
| Hooks de plugins de OpenClaw | OpenClaw | Compatibilidad de producto/plugin entre harnesses de PI y Codex. |
|
||||
| Middleware de extensión del app-server de Codex | Plugins incluidos con OpenClaw | Comportamiento del adaptador por turno alrededor de herramientas dinámicas de OpenClaw. |
|
||||
| Hooks nativos de Codex | Codex | Ciclo de vida de bajo nivel de Codex y política de herramientas nativas desde la configuración de Codex. |
|
||||
|
||||
OpenClaw no usa archivos `hooks.json` de proyecto o globales de Codex para enrutar
|
||||
comportamiento de plugins de OpenClaw. Para el puente compatible de herramientas nativas y permisos,
|
||||
OpenClaw inyecta configuración de Codex por hilo para `PreToolUse`, `PostToolUse`,
|
||||
`PermissionRequest` y `Stop`. Otros hooks de Codex como `SessionStart` y
|
||||
`UserPromptSubmit` siguen siendo controles de nivel Codex; no se exponen como
|
||||
hooks de plugins de OpenClaw en el contrato v1.
|
||||
OpenClaw no usa archivos `hooks.json` de proyecto ni globales de Codex para enrutar el comportamiento de plugins de OpenClaw. Para el puente compatible de herramientas nativas y permisos, OpenClaw inyecta configuración de Codex por hilo para `PreToolUse`, `PostToolUse`, `PermissionRequest` y `Stop`. Otros hooks de Codex como `SessionStart` y `UserPromptSubmit` siguen siendo controles de nivel Codex; no se exponen como hooks de plugins de OpenClaw en el contrato v1.
|
||||
|
||||
Para las herramientas dinámicas de OpenClaw, OpenClaw ejecuta la herramienta después de que Codex pida la
|
||||
llamada, por lo que OpenClaw dispara el comportamiento de plugin y middleware que posee en el
|
||||
adaptador del arnés. Para herramientas nativas de Codex, Codex posee el registro canónico de la herramienta.
|
||||
OpenClaw puede reflejar eventos seleccionados, pero no puede reescribir el hilo nativo de Codex
|
||||
a menos que Codex exponga esa operación mediante app-server o callbacks de hooks nativos.
|
||||
Para las herramientas dinámicas de OpenClaw, OpenClaw ejecuta la herramienta después de que Codex solicita la llamada, por lo que OpenClaw dispara el comportamiento de plugin y middleware que posee en el adaptador del harness. Para herramientas nativas de Codex, Codex posee el registro canónico de la herramienta. OpenClaw puede reflejar eventos seleccionados, pero no puede reescribir el hilo nativo de Codex salvo que Codex exponga esa operación mediante el app-server o callbacks de hooks nativos.
|
||||
|
||||
Las proyecciones de Compaction y ciclo de vida de LLM provienen de notificaciones del app-server de Codex
|
||||
y del estado del adaptador de OpenClaw, no de comandos de hooks nativos de Codex.
|
||||
Los eventos `before_compaction`, `after_compaction`, `llm_input` y
|
||||
`llm_output` de OpenClaw son observaciones de nivel adaptador, no capturas byte por byte
|
||||
de la solicitud interna o las cargas útiles de Compaction de Codex.
|
||||
Las proyecciones de Compaction y del ciclo de vida del LLM provienen de notificaciones del app-server de Codex y del estado del adaptador de OpenClaw, no de comandos de hooks nativos de Codex. Los eventos `before_compaction`, `after_compaction`, `llm_input` y `llm_output` de OpenClaw son observaciones de nivel adaptador, no capturas byte a byte de la solicitud interna ni de los payloads de Compaction de Codex.
|
||||
|
||||
Las notificaciones `hook/started` y `hook/completed` nativas de Codex del app-server se
|
||||
proyectan como eventos de agente `codex_app_server.hook` para trayectoria y depuración.
|
||||
No invocan hooks de plugins de OpenClaw.
|
||||
Las notificaciones `hook/started` y `hook/completed` nativas de Codex del app-server se proyectan como eventos de agente `codex_app_server.hook` para trayectoria y depuración. No invocan hooks de plugins de OpenClaw.
|
||||
|
||||
## Contrato de soporte V1
|
||||
## Contrato de soporte v1
|
||||
|
||||
El modo Codex no es PI con una llamada de modelo diferente debajo. Codex posee más del
|
||||
bucle de modelo nativo, y OpenClaw adapta sus superficies de plugin y sesión
|
||||
alrededor de ese límite.
|
||||
El modo Codex no es PI con una llamada de modelo diferente por debajo. Codex posee una parte mayor del bucle nativo del modelo, y OpenClaw adapta sus superficies de plugin y sesión alrededor de ese límite.
|
||||
|
||||
Compatible en el runtime v1 de Codex:
|
||||
|
||||
| Superficie | Soporte | Por qué |
|
||||
| -------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Bucle de modelo de OpenAI mediante Codex | Compatible | El app-server de Codex posee el turno de OpenAI, la reanudación de hilo nativo y la continuación de herramienta nativa. |
|
||||
| Enrutamiento y entrega de canales de OpenClaw | Compatible | Telegram, Discord, Slack, WhatsApp, iMessage y otros canales permanecen fuera del runtime del modelo. |
|
||||
| Herramientas dinámicas de OpenClaw | Compatible | Codex pide a OpenClaw ejecutar estas herramientas, por lo que OpenClaw permanece en la ruta de ejecución. |
|
||||
| Plugins de prompt y contexto | Compatible | OpenClaw construye superposiciones de prompt y proyecta contexto en el turno de Codex antes de iniciar o reanudar el hilo. |
|
||||
| Ciclo de vida del motor de contexto | Compatible | El ensamblado, la ingesta o mantenimiento posterior al turno, y la coordinación de Compaction del motor de contexto se ejecutan para turnos de Codex. |
|
||||
| Hooks de herramientas dinámicas | Compatible | `before_tool_call`, `after_tool_call` y el middleware de resultados de herramientas se ejecutan alrededor de herramientas dinámicas propiedad de OpenClaw. |
|
||||
| Hooks de ciclo de vida | Compatible como observaciones del adaptador | `llm_input`, `llm_output`, `agent_end`, `before_compaction` y `after_compaction` se disparan con cargas útiles honestas del modo Codex. |
|
||||
| Puerta de revisión de respuesta final | Compatible mediante el relé de hook nativo | Codex `Stop` se retransmite a `before_agent_finalize`; `revise` pide a Codex una pasada de modelo más antes de la finalización. |
|
||||
| Bloqueo u observación de shell, patch y MCP nativos | Compatible mediante el relé de hook nativo | Codex `PreToolUse` y `PostToolUse` se retransmiten para superficies de herramientas nativas confirmadas, incluidas cargas útiles MCP en Codex app-server `0.125.0` o posterior. Se admite el bloqueo; no la reescritura de argumentos. |
|
||||
| Política de permisos nativa | Compatible mediante el relé de hook nativo | Codex `PermissionRequest` puede enrutarse a través de la política de OpenClaw cuando el runtime lo expone. Si OpenClaw no devuelve ninguna decisión, Codex continúa por su ruta normal de guardian o aprobación de usuario. |
|
||||
| Captura de trayectoria del app-server | Compatible | OpenClaw registra la solicitud que envió al app-server y las notificaciones del app-server que recibe. |
|
||||
| Superficie | Soporte | Motivo |
|
||||
| --------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Bucle de modelo de OpenAI mediante Codex | Compatible | El app-server de Codex posee el turno de OpenAI, la reanudación del hilo nativo y la continuación de herramientas nativas. |
|
||||
| Enrutamiento y entrega de canales de OpenClaw | Compatible | Telegram, Discord, Slack, WhatsApp, iMessage y otros canales permanecen fuera del runtime del modelo. |
|
||||
| Herramientas dinámicas de OpenClaw | Compatible | Codex pide a OpenClaw que ejecute estas herramientas, por lo que OpenClaw permanece en la ruta de ejecución. |
|
||||
| Plugins de prompt y contexto | Compatible | OpenClaw construye superposiciones de prompt y proyecta contexto en el turno de Codex antes de iniciar o reanudar el hilo. |
|
||||
| Ciclo de vida del motor de contexto | Compatible | El ensamblado, la ingesta o el mantenimiento posterior al turno, y la coordinación de Compaction del motor de contexto se ejecutan para turnos de Codex. |
|
||||
| Hooks de herramientas dinámicas | Compatible | `before_tool_call`, `after_tool_call` y el middleware de resultados de herramientas se ejecutan alrededor de herramientas dinámicas propiedad de OpenClaw. |
|
||||
| Hooks de ciclo de vida | Compatible como observaciones del adaptador | `llm_input`, `llm_output`, `agent_end`, `before_compaction` y `after_compaction` se disparan con payloads honestos del modo Codex. |
|
||||
| Puerta de revisión de respuesta final | Compatible mediante el relay de hooks nativos | `Stop` de Codex se retransmite a `before_agent_finalize`; `revise` pide a Codex una pasada más del modelo antes de la finalización. |
|
||||
| Bloqueo u observación de shell, patch y MCP nativos | Compatible mediante el relay de hooks nativos | `PreToolUse` y `PostToolUse` de Codex se retransmiten para superficies de herramientas nativas confirmadas, incluidos payloads MCP en el app-server de Codex `0.125.0` o posterior. El bloqueo es compatible; la reescritura de argumentos no. |
|
||||
| Política de permisos nativa | Compatible mediante el relay de hooks nativos | `PermissionRequest` de Codex puede enrutarse mediante la política de OpenClaw donde el runtime lo expone. Si OpenClaw no devuelve ninguna decisión, Codex continúa por su ruta normal de guardián o aprobación del usuario. |
|
||||
| Captura de trayectoria del app-server | Compatible | OpenClaw registra la solicitud que envió al app-server y las notificaciones del app-server que recibe. |
|
||||
|
||||
No compatible en el runtime v1 de Codex:
|
||||
|
||||
| Superficie | Límite V1 | Ruta futura |
|
||||
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| Mutación de argumentos de herramientas nativas | Los hooks pre-herramienta nativos de Codex pueden bloquear, pero OpenClaw no reescribe argumentos de herramientas nativas de Codex. | Requiere soporte de hooks/esquema de Codex para entrada de herramienta de reemplazo. |
|
||||
| Historial editable de transcripción nativa de Codex | Codex posee el historial canónico del hilo nativo. OpenClaw posee un reflejo y puede proyectar contexto futuro, pero no debe mutar elementos internos no compatibles. | Añadir APIs explícitas del app-server de Codex si se necesita cirugía del hilo nativo. |
|
||||
| `tool_result_persist` para registros de herramientas nativas de Codex | Ese hook transforma escrituras de transcripción propiedad de OpenClaw, no registros de herramientas nativas de Codex. | Podría reflejar registros transformados, pero la reescritura canónica necesita soporte de Codex. |
|
||||
| Metadatos enriquecidos de Compaction nativa | OpenClaw observa el inicio y la finalización de Compaction, pero no recibe una lista estable de conservados/descartados, delta de tokens ni carga útil de resumen. | Necesita eventos de Compaction de Codex más ricos. |
|
||||
| Intervención de Compaction | Los hooks actuales de Compaction de OpenClaw son de nivel notificación en modo Codex. | Añadir hooks pre/post Compaction de Codex si los plugins necesitan vetar o reescribir la Compaction nativa. |
|
||||
| Captura byte por byte de la solicitud de API de modelo | OpenClaw puede capturar solicitudes y notificaciones del app-server, pero el núcleo de Codex construye internamente la solicitud final a la API de OpenAI. | Necesita un evento de trazado de solicitud de modelo de Codex o API de depuración. |
|
||||
| Superficie | Límite V1 | Ruta futura |
|
||||
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| Mutación de argumentos de herramientas nativas | Los hooks preherramienta nativos de Codex pueden bloquear, pero OpenClaw no reescribe argumentos de herramientas nativas de Codex. | Requiere compatibilidad de hooks/esquemas de Codex para reemplazar la entrada de herramienta. |
|
||||
| Historial editable de transcripción nativa de Codex | Codex posee el historial canónico de hilos nativos. OpenClaw posee un espejo y puede proyectar contexto futuro, pero no debe mutar componentes internos no compatibles. | Agregar API explícitas del servidor de aplicaciones de Codex si se necesita cirugía de hilos nativos. |
|
||||
| `tool_result_persist` para registros de herramientas nativas de Codex | Ese hook transforma escrituras de transcripción propiedad de OpenClaw, no registros de herramientas nativas de Codex. | Podría reflejar registros transformados, pero la reescritura canónica necesita compatibilidad de Codex. |
|
||||
| Metadatos nativos enriquecidos de Compaction | OpenClaw observa el inicio y la finalización de Compaction, pero no recibe una lista estable de conservados/eliminados, delta de tokens ni carga útil de resumen. | Necesita eventos de Compaction de Codex más enriquecidos. |
|
||||
| Intervención de Compaction | Los hooks actuales de Compaction de OpenClaw están a nivel de notificación en modo Codex. | Agregar hooks pre/post Compaction de Codex si los plugins necesitan vetar o reescribir Compaction nativa. |
|
||||
| Captura byte por byte de solicitudes de API de modelo | OpenClaw puede capturar solicitudes y notificaciones del servidor de aplicaciones, pero el núcleo de Codex construye internamente la solicitud final a la API de OpenAI. | Necesita un evento de rastreo de solicitud de modelo de Codex o una API de depuración. |
|
||||
|
||||
## Herramientas, medios y Compaction
|
||||
|
||||
El arnés de Codex cambia únicamente el ejecutor de agente embebido de bajo nivel.
|
||||
El arnés de Codex solo cambia el ejecutor de agente integrado de bajo nivel.
|
||||
|
||||
OpenClaw todavía construye la lista de herramientas y recibe resultados de herramientas dinámicas desde el
|
||||
arnés. Texto, imágenes, video, música, TTS, aprobaciones y salida de herramientas de mensajería
|
||||
continúan por la ruta normal de entrega de OpenClaw.
|
||||
OpenClaw sigue construyendo la lista de herramientas y recibiendo resultados de herramientas dinámicas desde el arnés. Texto, imágenes, video, música, TTS, aprobaciones y salida de herramientas de mensajería continúan por la ruta normal de entrega de OpenClaw.
|
||||
|
||||
El relé de hook nativo es intencionadamente genérico, pero el contrato de soporte v1 está
|
||||
limitado a las rutas de herramientas y permisos nativas de Codex que OpenClaw prueba. En
|
||||
el runtime de Codex, eso incluye cargas útiles de shell, patch y MCP `PreToolUse`,
|
||||
`PostToolUse` y `PermissionRequest`. No asumas que cada evento de hook futuro de
|
||||
Codex es una superficie de plugin de OpenClaw hasta que el contrato de runtime lo nombre.
|
||||
El relé de hooks nativos es intencionalmente genérico, pero el contrato de compatibilidad v1 se limita a las rutas de herramientas nativas de Codex y permisos que OpenClaw prueba. En el entorno de ejecución de Codex, eso incluye cargas útiles de shell, patch y MCP `PreToolUse`, `PostToolUse` y `PermissionRequest`. No asumas que cada evento futuro de hook de Codex es una superficie de plugin de OpenClaw hasta que el contrato de tiempo de ejecución lo nombre.
|
||||
|
||||
Para `PermissionRequest`, OpenClaw solo devuelve decisiones explícitas de permitir o denegar
|
||||
cuando la política decide. Un resultado sin decisión no es una autorización. Codex lo trata como ausencia de
|
||||
decisión de hook y continúa hacia su propia ruta de guardian o aprobación de usuario.
|
||||
Para `PermissionRequest`, OpenClaw solo devuelve decisiones explícitas de permitir o denegar cuando la política decide. Un resultado sin decisión no es una autorización. Codex lo trata como ausencia de decisión de hook y pasa a su propia ruta de guardián o aprobación de usuario.
|
||||
|
||||
Las elicitaciones de aprobación de herramientas MCP de Codex se enrutan mediante el flujo de aprobación de
|
||||
plugins de OpenClaw cuando Codex marca `_meta.codex_approval_kind` como
|
||||
`"mcp_tool_call"`. Los prompts `request_user_input` de Codex se envían de vuelta al
|
||||
chat de origen, y el siguiente mensaje de seguimiento en cola responde a esa solicitud del servidor
|
||||
nativo en lugar de dirigirse como contexto adicional. Otras solicitudes de elicitación MCP
|
||||
siguen fallando cerradas.
|
||||
Las solicitudes de aprobación de herramientas MCP de Codex se enrutan mediante el flujo de aprobación de plugins de OpenClaw cuando Codex marca `_meta.codex_approval_kind` como `"mcp_tool_call"`. Los prompts de Codex `request_user_input` se envían de vuelta al chat de origen, y el siguiente mensaje de seguimiento en cola responde esa solicitud nativa del servidor en lugar de dirigirse como contexto adicional. Otras solicitudes de interacción de MCP siguen fallando de forma cerrada.
|
||||
|
||||
El direccionamiento de la cola de ejecución activa se asigna a `turn/steer` del app-server de Codex. Con el
|
||||
valor predeterminado `messages.queue.mode: "steer"`, OpenClaw agrupa los mensajes de chat en cola
|
||||
durante la ventana de silencio configurada y los envía como una sola solicitud `turn/steer` en
|
||||
orden de llegada. El modo heredado `queue` envía solicitudes `turn/steer` separadas. Los turnos de
|
||||
revisión de Codex y de compaction manual pueden rechazar el direccionamiento en el mismo turno, en cuyo caso
|
||||
OpenClaw usa la cola de seguimiento cuando el modo seleccionado permite la reserva. Consulta
|
||||
[Cola de direccionamiento](/es/concepts/queue-steering).
|
||||
El direccionamiento de cola de ejecución activa se asigna a `turn/steer` del servidor de aplicaciones de Codex. Con el valor predeterminado `messages.queue.mode: "steer"`, OpenClaw agrupa mensajes de chat en cola durante la ventana de silencio configurada y los envía como una sola solicitud `turn/steer` en orden de llegada. El modo heredado `queue` envía solicitudes `turn/steer` separadas. Los turnos de revisión y Compaction manual de Codex pueden rechazar el direccionamiento en el mismo turno, en cuyo caso OpenClaw usa la cola de seguimiento cuando el modo seleccionado permite respaldo. Consulta [Cola de direccionamiento](/es/concepts/queue-steering).
|
||||
|
||||
Cuando el modelo seleccionado usa el arnés de Codex, la compaction nativa de hilos se
|
||||
delega al app-server de Codex. OpenClaw mantiene un espejo de transcripción para el historial de canales,
|
||||
la búsqueda, `/new`, `/reset` y futuros cambios de modelo o arnés. El
|
||||
espejo incluye el prompt del usuario, el texto final del asistente y registros ligeros de razonamiento
|
||||
o plan de Codex cuando el app-server los emite. Hoy, OpenClaw solo
|
||||
registra señales de inicio y finalización de la compaction nativa. Todavía no expone un
|
||||
resumen de compaction legible por humanos ni una lista auditable de qué entradas conservó Codex
|
||||
después de la compaction.
|
||||
Cuando el modelo seleccionado usa el arnés de Codex, la Compaction de hilos nativos se delega al servidor de aplicaciones de Codex. OpenClaw mantiene un espejo de transcripción para historial de canal, búsqueda, `/new`, `/reset` y cambios futuros de modelo o arnés. El espejo incluye el prompt del usuario, el texto final del asistente y registros ligeros de razonamiento o plan de Codex cuando el servidor de aplicaciones los emite. Hoy, OpenClaw solo registra señales de inicio y finalización de Compaction nativa. Aún no expone un resumen legible por humanos de Compaction ni una lista auditable de qué entradas conservó Codex después de Compaction.
|
||||
|
||||
Como Codex posee el hilo nativo canónico, `tool_result_persist` no
|
||||
reescribe actualmente los registros de resultados de herramientas nativos de Codex. Solo se aplica cuando
|
||||
OpenClaw escribe un resultado de herramienta de transcripción de sesión propiedad de OpenClaw.
|
||||
Como Codex posee el hilo nativo canónico, `tool_result_persist` actualmente no reescribe registros de resultados de herramientas nativas de Codex. Solo se aplica cuando OpenClaw escribe un resultado de herramienta en la transcripción de una sesión propiedad de OpenClaw.
|
||||
|
||||
La generación de medios no requiere PI. La comprensión de imágenes, videos, música, PDF, TTS y medios
|
||||
sigue usando la configuración correspondiente de proveedor/modelo, como
|
||||
`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` y
|
||||
`messages.tts`.
|
||||
La generación de medios no requiere PI. Imágenes, video, música, PDF, TTS y comprensión de medios siguen usando la configuración de proveedor/modelo correspondiente, como `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` y `messages.tts`.
|
||||
|
||||
## Solución de problemas
|
||||
|
||||
**Codex no aparece como un proveedor `/model` normal:** esto es lo esperado en
|
||||
configuraciones nuevas. Selecciona un modelo `openai/gpt-*` con
|
||||
`agentRuntime.id: "codex"` (o una referencia heredada `codex/*`), habilita
|
||||
`plugins.entries.codex.enabled` y comprueba si `plugins.allow` excluye
|
||||
`codex`.
|
||||
**Codex no aparece como un proveedor normal de `/model`:** esto es esperado para configuraciones nuevas. Selecciona un modelo `openai/gpt-*` con `agentRuntime.id: "codex"` (o una referencia heredada `codex/*`), habilita `plugins.entries.codex.enabled` y comprueba si `plugins.allow` excluye `codex`.
|
||||
|
||||
**OpenClaw usa PI en lugar de Codex:** `agentRuntime.id: "auto"` todavía puede usar PI como
|
||||
backend de compatibilidad cuando ningún arnés de Codex reclama la ejecución. Establece
|
||||
`agentRuntime.id: "codex"` para forzar la selección de Codex durante las pruebas. Un
|
||||
runtime de Codex forzado ahora falla en lugar de recurrir a PI, salvo que
|
||||
establezcas explícitamente `agentRuntime.fallback: "pi"`. Una vez seleccionado el app-server de Codex,
|
||||
sus errores se muestran directamente sin configuración de reserva adicional.
|
||||
**OpenClaw usa PI en lugar de Codex:** `agentRuntime.id: "auto"` todavía puede usar PI como backend de compatibilidad cuando ningún arnés de Codex reclama la ejecución. Configura `agentRuntime.id: "codex"` para forzar la selección de Codex durante las pruebas. Un entorno de ejecución de Codex forzado ahora falla en lugar de volver a PI, a menos que configures explícitamente `agentRuntime.fallback: "pi"`. Una vez seleccionado el servidor de aplicaciones de Codex, sus fallos se muestran directamente sin configuración de respaldo adicional.
|
||||
|
||||
**El app-server se rechaza:** actualiza Codex para que el handshake del app-server
|
||||
informe la versión `0.125.0` o una posterior. Las versiones preliminares de la misma versión o con sufijo de compilación,
|
||||
como `0.125.0-alpha.2` o `0.125.0+custom`, se rechazan porque el
|
||||
mínimo estable del protocolo `0.125.0` es lo que prueba OpenClaw.
|
||||
**El servidor de aplicaciones se rechaza:** actualiza Codex para que el handshake del servidor de aplicaciones informe la versión `0.125.0` o una más reciente. Versiones preliminares de la misma versión o versiones con sufijo de compilación como `0.125.0-alpha.2` o `0.125.0+custom` se rechazan porque el mínimo de protocolo estable `0.125.0` es lo que OpenClaw prueba.
|
||||
|
||||
**El descubrimiento de modelos es lento:** reduce `plugins.entries.codex.config.discovery.timeoutMs`
|
||||
o deshabilita el descubrimiento.
|
||||
**El descubrimiento de modelos es lento:** reduce `plugins.entries.codex.config.discovery.timeoutMs` o deshabilita el descubrimiento.
|
||||
|
||||
**El transporte WebSocket falla de inmediato:** comprueba `appServer.url`, `authToken`
|
||||
y que el app-server remoto use la misma versión del protocolo app-server de Codex.
|
||||
**El transporte WebSocket falla de inmediato:** revisa `appServer.url`, `authToken` y que el servidor de aplicaciones remoto hable la misma versión del protocolo del servidor de aplicaciones de Codex.
|
||||
|
||||
**Un modelo que no es de Codex usa PI:** esto es lo esperado salvo que hayas forzado
|
||||
`agentRuntime.id: "codex"` para ese agente o seleccionado una referencia heredada
|
||||
`codex/*`. Las referencias simples `openai/gpt-*` y de otros proveedores permanecen en su ruta de
|
||||
proveedor normal en modo `auto`. Si fuerzas `agentRuntime.id: "codex"`, cada
|
||||
turno incrustado de ese agente debe ser un modelo de OpenAI compatible con Codex.
|
||||
**Un modelo que no es Codex usa PI:** esto es esperado a menos que hayas forzado `agentRuntime.id: "codex"` para ese agente o seleccionado una referencia heredada `codex/*`. Las referencias simples `openai/gpt-*` y de otros proveedores permanecen en su ruta normal de proveedor en modo `auto`. Si fuerzas `agentRuntime.id: "codex"`, cada turno integrado para ese agente debe ser un modelo de OpenAI compatible con Codex.
|
||||
|
||||
**Computer Use está instalado, pero las herramientas no se ejecutan:** comprueba
|
||||
`/codex computer-use status` desde una sesión nueva. Si una herramienta informa
|
||||
`Native hook relay unavailable`, usa `/new` o `/reset`; si persiste, reinicia
|
||||
el Gateway para limpiar registros obsoletos de hooks nativos. Si `computer-use.list_apps`
|
||||
agota el tiempo de espera, reinicia Codex Computer Use o Codex Desktop y vuelve a intentarlo.
|
||||
**Computer Use está instalado pero las herramientas no se ejecutan:** comprueba `/codex computer-use status` desde una sesión nueva. Si una herramienta informa `Native hook relay unavailable`, usa `/new` o `/reset`; si persiste, reinicia el gateway para borrar registros obsoletos de hooks nativos. Si `computer-use.list_apps` agota el tiempo de espera, reinicia Codex Computer Use o Codex Desktop y vuelve a intentarlo.
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Plugins de arnés de agente](/es/plugins/sdk-agent-harness)
|
||||
- [Runtimes de agente](/es/concepts/agent-runtimes)
|
||||
- [Entornos de ejecución de agentes](/es/concepts/agent-runtimes)
|
||||
- [Proveedores de modelos](/es/concepts/model-providers)
|
||||
- [Proveedor de OpenAI](/es/providers/openai)
|
||||
- [Proveedor OpenAI](/es/providers/openai)
|
||||
- [Estado](/es/cli/status)
|
||||
- [Hooks de Plugin](/es/plugins/hooks)
|
||||
- [Hooks de plugins](/es/plugins/hooks)
|
||||
- [Referencia de configuración](/es/gateway/configuration-reference)
|
||||
- [Pruebas](/es/help/testing-live#live-codex-app-server-harness-smoke)
|
||||
|
||||
@ -1,58 +1,57 @@
|
||||
---
|
||||
read_when:
|
||||
- Añadir o modificar Skills
|
||||
- Cambiar el control de activación de Skills, las listas de permitidos o las reglas de carga
|
||||
- Cambiar las reglas de activación de Skills, las listas de permitidos o las reglas de carga
|
||||
- Comprender la precedencia de Skills y el comportamiento de las instantáneas
|
||||
sidebarTitle: Skills
|
||||
summary: 'Skills: administradas frente a espacio de trabajo, reglas de control, listas de permitidos de agentes y conexión de configuración'
|
||||
summary: 'Skills: administradas vs. de espacio de trabajo, reglas de control, listas de permitidos de agentes y cableado de configuración'
|
||||
title: Skills
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T09:34:53Z"
|
||||
generated_at: "2026-04-30T20:05:47Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d7dd17f52119bf0a0bb197025070abb68f7667a7d22c3d5fa6ef2f666110a45a
|
||||
source_hash: b58d690786756bd3539940aae9f2abcb8a497798ed7b6afeb5e6d6e255fcf257
|
||||
source_path: tools/skills.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw usa carpetas de skills **compatibles con [AgentSkills](https://agentskills.io)** para enseñar al agente a usar herramientas. Cada skill es un directorio que contiene un `SKILL.md` con frontmatter YAML e instrucciones. OpenClaw carga skills incluidas más reemplazos locales opcionales, y las filtra en tiempo de carga según el entorno, la configuración y la presencia de binarios.
|
||||
OpenClaw usa carpetas de Skills **compatibles con [AgentSkills](https://agentskills.io)** para enseñar al agente cómo usar herramientas. Cada skill es un directorio que contiene un `SKILL.md` con frontmatter YAML e instrucciones. OpenClaw carga los Skills incluidos más anulaciones locales opcionales, y los filtra en el momento de carga según el entorno, la configuración y la presencia de binarios.
|
||||
|
||||
## Ubicaciones y precedencia
|
||||
|
||||
OpenClaw carga skills desde estas fuentes, **con la mayor precedencia primero**:
|
||||
OpenClaw carga Skills desde estas fuentes, **con la precedencia más alta primero**:
|
||||
|
||||
| # | Fuente | Ruta |
|
||||
| --- | ------------------------- | -------------------------------- |
|
||||
| 1 | Skills del workspace | `<workspace>/skills` |
|
||||
| 2 | Skills del agente del proyecto | `<workspace>/.agents/skills` |
|
||||
| # | Fuente | Ruta |
|
||||
| --- | --------------------- | -------------------------------- |
|
||||
| 1 | Skills del espacio de trabajo | `<workspace>/skills` |
|
||||
| 2 | Skills del agente del proyecto | `<workspace>/.agents/skills` |
|
||||
| 3 | Skills personales del agente | `~/.agents/skills` |
|
||||
| 4 | Skills gestionadas/locales | `~/.openclaw/skills` |
|
||||
| 5 | Skills incluidas | incluidas con la instalación |
|
||||
| 6 | Carpetas de skills adicionales | `skills.load.extraDirs` (config) |
|
||||
| 4 | Skills gestionados/locales | `~/.openclaw/skills` |
|
||||
| 5 | Skills incluidos | enviados con la instalación |
|
||||
| 6 | Carpetas de Skills adicionales | `skills.load.extraDirs` (config) |
|
||||
|
||||
Si un nombre de skill entra en conflicto, gana la fuente de mayor precedencia.
|
||||
Si el nombre de un skill entra en conflicto, gana la fuente más alta.
|
||||
|
||||
## Skills por agente frente a compartidas
|
||||
El directorio nativo `$CODEX_HOME/skills` de Codex CLI no es una de estas raíces de Skills de OpenClaw. En modo arnés de Codex, los lanzamientos locales del servidor de aplicación usan homes de Codex aislados por agente, por lo que los Skills personales de Codex CLI no se cargan implícitamente. Usa `openclaw migrate codex --dry-run` para inventariarlos y `openclaw migrate codex` para elegir directorios de Skills con un indicador interactivo de casillas antes de copiarlos en el espacio de trabajo actual del agente de OpenClaw. Para ejecuciones no interactivas, repite `--skill <name>` para los Skills exactos que quieres copiar.
|
||||
|
||||
En configuraciones **multiagente**, cada agente tiene su propio workspace:
|
||||
## Skills por agente frente a compartidos
|
||||
|
||||
| Ámbito | Ruta | Visible para |
|
||||
| -------------------- | ------------------------------------------- | ---------------------------- |
|
||||
| Por agente | `<workspace>/skills` | Solo ese agente |
|
||||
| Agente del proyecto | `<workspace>/.agents/skills` | Solo el agente de ese workspace |
|
||||
| Agente personal | `~/.agents/skills` | Todos los agentes en esa máquina |
|
||||
| Gestionadas/locales compartidas | `~/.openclaw/skills` | Todos los agentes en esa máquina |
|
||||
| Directorios adicionales compartidos | `skills.load.extraDirs` (menor precedencia) | Todos los agentes en esa máquina |
|
||||
En configuraciones **multiagente**, cada agente tiene su propio espacio de trabajo:
|
||||
|
||||
Mismo nombre en varios lugares → gana la fuente de mayor precedencia. Workspace supera a
|
||||
agente del proyecto, supera a agente personal, supera a gestionadas/locales, supera a incluidas,
|
||||
supera a directorios adicionales.
|
||||
| Ámbito | Ruta | Visible para |
|
||||
| -------------------- | ------------------------------------------- | --------------------------- |
|
||||
| Por agente | `<workspace>/skills` | Solo ese agente |
|
||||
| Agente del proyecto | `<workspace>/.agents/skills` | Solo el agente de ese espacio de trabajo |
|
||||
| Agente personal | `~/.agents/skills` | Todos los agentes en esa máquina |
|
||||
| Gestionado/local compartido | `~/.openclaw/skills` | Todos los agentes en esa máquina |
|
||||
| Directorios adicionales compartidos | `skills.load.extraDirs` (precedencia más baja) | Todos los agentes en esa máquina |
|
||||
|
||||
## Listas de permisos de skills por agente
|
||||
Mismo nombre en varios lugares → gana la fuente más alta. El espacio de trabajo supera al agente del proyecto, que supera al agente personal, que supera al gestionado/local, que supera al incluido, que supera a los directorios adicionales.
|
||||
|
||||
La **ubicación** de la skill y la **visibilidad** de la skill son controles separados.
|
||||
La ubicación/precedencia decide qué copia de una skill con el mismo nombre gana; las listas
|
||||
de permisos del agente deciden qué skills puede usar realmente un agente.
|
||||
## Listas de permitidos de Skills del agente
|
||||
|
||||
La **ubicación** del skill y la **visibilidad** del skill son controles separados.
|
||||
La ubicación/precedencia decide qué copia de un skill con el mismo nombre gana; las listas de permitidos del agente deciden qué Skills puede usar realmente un agente.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -70,90 +69,61 @@ de permisos del agente deciden qué skills puede usar realmente un agente.
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Reglas de listas de permisos">
|
||||
- Omite `agents.defaults.skills` para permitir skills sin restricciones de forma predeterminada.
|
||||
<Accordion title="Reglas de la lista de permitidos">
|
||||
- Omite `agents.defaults.skills` para permitir Skills sin restricciones de forma predeterminada.
|
||||
- Omite `agents.list[].skills` para heredar `agents.defaults.skills`.
|
||||
- Define `agents.list[].skills: []` para no permitir skills.
|
||||
- Una lista no vacía `agents.list[].skills` es el conjunto **final** para ese
|
||||
agente; no se fusiona con los valores predeterminados.
|
||||
- La lista de permisos efectiva se aplica a la construcción de prompts, el descubrimiento
|
||||
de comandos slash de skills, la sincronización del sandbox y las instantáneas de skills.
|
||||
- Define `agents.list[].skills: []` para no permitir Skills.
|
||||
- Una lista no vacía `agents.list[].skills` es el conjunto **final** para ese agente; no se combina con los valores predeterminados.
|
||||
- La lista de permitidos efectiva se aplica en la construcción del prompt, la detección de slash commands de Skills, la sincronización del sandbox y las instantáneas de Skills.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Plugins y skills
|
||||
## Plugins y Skills
|
||||
|
||||
Los Plugins pueden incluir sus propias skills listando directorios `skills` en
|
||||
`openclaw.plugin.json` (rutas relativas a la raíz del Plugin). Las skills del Plugin
|
||||
se cargan cuando el Plugin está habilitado. Este es el lugar adecuado para guías operativas
|
||||
específicas de herramientas que son demasiado largas para la descripción de la herramienta pero deben estar
|
||||
disponibles siempre que el Plugin esté instalado; por ejemplo, el Plugin de navegador
|
||||
incluye una skill `browser-automation` para el control del navegador en varios pasos.
|
||||
Los Plugins pueden incluir sus propios Skills listando directorios `skills` en `openclaw.plugin.json` (rutas relativas a la raíz del Plugin). Los Skills del Plugin se cargan cuando el Plugin está habilitado. Este es el lugar correcto para guías operativas específicas de herramientas que son demasiado largas para la descripción de la herramienta, pero que deben estar disponibles siempre que el Plugin esté instalado; por ejemplo, el Plugin del navegador incluye un skill `browser-automation` para control del navegador en varios pasos.
|
||||
|
||||
Los directorios de skills de Plugin se fusionan en la misma ruta de baja precedencia que
|
||||
`skills.load.extraDirs`, por lo que una skill incluida, gestionada, de agente o de workspace
|
||||
con el mismo nombre los reemplaza. Puedes condicionarlas mediante
|
||||
`metadata.openclaw.requires.config` en la entrada de configuración del Plugin.
|
||||
Los directorios de Skills del Plugin se combinan en la misma ruta de baja precedencia que `skills.load.extraDirs`, por lo que un skill incluido, gestionado, de agente o de espacio de trabajo con el mismo nombre los anula. Puedes condicionarlos mediante `metadata.openclaw.requires.config` en la entrada de configuración del Plugin.
|
||||
|
||||
Consulta [Plugins](/es/tools/plugin) para descubrimiento/configuración y [Herramientas](/es/tools) para
|
||||
la superficie de herramientas que esas skills enseñan.
|
||||
Consulta [Plugins](/es/tools/plugin) para detección/configuración y [Herramientas](/es/tools) para la superficie de herramientas que esos Skills enseñan.
|
||||
|
||||
## Taller de Skills
|
||||
## Skill Workshop
|
||||
|
||||
El Plugin opcional y experimental **Taller de Skills** puede crear o actualizar
|
||||
skills del workspace a partir de procedimientos reutilizables observados durante el trabajo del agente. Está
|
||||
deshabilitado de forma predeterminada y debe habilitarse explícitamente mediante
|
||||
`plugins.entries.skill-workshop`.
|
||||
El Plugin opcional y experimental **Skill Workshop** puede crear o actualizar Skills del espacio de trabajo a partir de procedimientos reutilizables observados durante el trabajo del agente. Está deshabilitado de forma predeterminada y debe habilitarse explícitamente mediante `plugins.entries.skill-workshop`.
|
||||
|
||||
Taller de Skills escribe solo en `<workspace>/skills`, analiza el contenido generado,
|
||||
admite aprobación pendiente o escrituras seguras automáticas, pone en cuarentena
|
||||
propuestas inseguras y actualiza la instantánea de skills después de escrituras
|
||||
correctas para que las nuevas skills estén disponibles sin reiniciar el Gateway.
|
||||
Skill Workshop escribe solo en `<workspace>/skills`, analiza el contenido generado, admite aprobación pendiente o escrituras seguras automáticas, pone en cuarentena propuestas inseguras y actualiza la instantánea de Skills después de escrituras correctas para que los nuevos Skills estén disponibles sin reiniciar el Gateway.
|
||||
|
||||
Úsalo para correcciones como _"la próxima vez, verifica la atribución de GIF"_ o
|
||||
flujos de trabajo difíciles de obtener, como listas de comprobación de QA de medios. Empieza con aprobación
|
||||
pendiente; usa escrituras automáticas solo en workspaces de confianza después de revisar
|
||||
sus propuestas. Guía completa: [Plugin Taller de Skills](/es/plugins/skill-workshop).
|
||||
Úsalo para correcciones como _"la próxima vez, verifica la atribución del GIF"_ o flujos de trabajo aprendidos con esfuerzo, como listas de comprobación de QA de medios. Empieza con aprobación pendiente; usa escrituras automáticas solo en espacios de trabajo de confianza después de revisar sus propuestas. Guía completa: [Plugin Skill Workshop](/es/plugins/skill-workshop).
|
||||
|
||||
## ClawHub (instalación y sincronización)
|
||||
|
||||
[ClawHub](https://clawhub.ai) es el registro público de skills para OpenClaw.
|
||||
Usa los comandos nativos `openclaw skills` para descubrir/instalar/actualizar, o la
|
||||
CLI `clawhub` separada para flujos de trabajo de publicación/sincronización. Guía completa:
|
||||
[ClawHub](https://clawhub.ai) es el registro público de Skills para OpenClaw.
|
||||
Usa los comandos nativos `openclaw skills` para descubrir/instalar/actualizar, o la CLI `clawhub` separada para flujos de trabajo de publicación/sincronización. Guía completa:
|
||||
[ClawHub](/es/tools/clawhub).
|
||||
|
||||
| Acción | Comando |
|
||||
| ---------------------------------- | -------------------------------------- |
|
||||
| Instalar una skill en el workspace | `openclaw skills install <skill-slug>` |
|
||||
| Actualizar todas las skills instaladas | `openclaw skills update --all` |
|
||||
| Sincronizar (analizar + publicar actualizaciones) | `clawhub sync --all` |
|
||||
| Instalar un skill en el espacio de trabajo | `openclaw skills install <skill-slug>` |
|
||||
| Actualizar todos los Skills instalados | `openclaw skills update --all` |
|
||||
| Sincronizar (analizar + publicar actualizaciones) | `clawhub sync --all` |
|
||||
|
||||
`openclaw skills install` nativo instala en el directorio `skills/` del workspace activo.
|
||||
La CLI `clawhub` separada también instala en `./skills` bajo tu directorio de trabajo actual
|
||||
(o recurre al workspace configurado de OpenClaw). OpenClaw lo recoge como
|
||||
`<workspace>/skills` en la siguiente sesión.
|
||||
Las raíces de skills configuradas también admiten un nivel de agrupación, como
|
||||
`skills/<group>/<skill>/SKILL.md`, para que las skills de terceros relacionadas puedan
|
||||
mantenerse bajo una carpeta compartida sin un escaneo recursivo amplio.
|
||||
`openclaw skills install` nativo instala en el directorio `skills/` del espacio de trabajo activo. La CLI `clawhub` separada también instala en `./skills` bajo tu directorio de trabajo actual (o recurre al espacio de trabajo de OpenClaw configurado). OpenClaw lo recoge como `<workspace>/skills` en la siguiente sesión.
|
||||
Las raíces de Skills configuradas también admiten un nivel de agrupación, como `skills/<group>/<skill>/SKILL.md`, de modo que los Skills de terceros relacionados puedan mantenerse bajo una carpeta compartida sin un análisis recursivo amplio.
|
||||
|
||||
Las páginas de skills de ClawHub muestran el estado más reciente del análisis de seguridad antes de instalar,
|
||||
con páginas de detalle del analizador para VirusTotal, ClawScan y análisis estático.
|
||||
`openclaw skills install <slug>` sigue siendo solo la ruta de instalación; los publicadores
|
||||
recuperan falsos positivos mediante el panel de ClawHub o
|
||||
`clawhub skill rescan <slug>`.
|
||||
Las páginas de Skills de ClawHub muestran el estado del análisis de seguridad más reciente antes de la instalación, con páginas de detalles del analizador para VirusTotal, ClawScan y análisis estático.
|
||||
`openclaw skills install <slug>` sigue siendo solo la ruta de instalación; los publicadores recuperan falsos positivos mediante el panel de ClawHub o `clawhub skill rescan <slug>`.
|
||||
|
||||
## Seguridad
|
||||
|
||||
<Warning>
|
||||
Trata las skills de terceros como **código no confiable**. Léelas antes de habilitarlas.
|
||||
Trata los Skills de terceros como **código no confiable**. Léelos antes de habilitarlos.
|
||||
Prefiere ejecuciones en sandbox para entradas no confiables y herramientas riesgosas. Consulta
|
||||
[Sandboxing](/es/gateway/sandboxing) para los controles del lado del agente.
|
||||
</Warning>
|
||||
|
||||
- El descubrimiento de skills de workspace y directorios adicionales solo acepta raíces de skills y archivos `SKILL.md` cuyo realpath resuelto permanezca dentro de la raíz configurada.
|
||||
- Las instalaciones de dependencias de skills respaldadas por Gateway (`skills.install`, onboarding y la UI de configuración de Skills) ejecutan el analizador de código peligroso integrado antes de ejecutar metadatos de instalador. Los hallazgos `critical` bloquean de forma predeterminada salvo que el llamador defina explícitamente el override peligroso; los hallazgos sospechosos siguen solo advirtiendo.
|
||||
- `openclaw skills install <slug>` es distinto: descarga una carpeta de skill de ClawHub en el workspace y no usa la ruta de metadatos de instalador anterior.
|
||||
- `skills.entries.*.env` y `skills.entries.*.apiKey` inyectan secretos en el proceso **host** para ese turno del agente (no en el sandbox). Mantén los secretos fuera de prompts y logs.
|
||||
- La detección de Skills del espacio de trabajo y de directorios adicionales solo acepta raíces de Skills y archivos `SKILL.md` cuyo realpath resuelto permanezca dentro de la raíz configurada.
|
||||
- Las instalaciones de dependencias de Skills respaldadas por el Gateway (`skills.install`, onboarding y la UI de configuración de Skills) ejecutan el analizador integrado de código peligroso antes de ejecutar metadatos de instalador. Los hallazgos `critical` bloquean de forma predeterminada salvo que el llamador establezca explícitamente la anulación peligrosa; los hallazgos sospechosos siguen solo advirtiendo.
|
||||
- `openclaw skills install <slug>` es diferente: descarga una carpeta de skill de ClawHub en el espacio de trabajo y no usa la ruta de metadatos de instalador anterior.
|
||||
- `skills.entries.*.env` y `skills.entries.*.apiKey` inyectan secretos en el proceso **host** para ese turno del agente (no en el sandbox). Mantén los secretos fuera de prompts y registros.
|
||||
|
||||
Para un modelo de amenazas y listas de comprobación más amplios, consulta [Seguridad](/es/gateway/security).
|
||||
|
||||
@ -168,35 +138,32 @@ description: Generate or edit images via a provider-backed image workflow
|
||||
---
|
||||
```
|
||||
|
||||
OpenClaw sigue la especificación AgentSkills para diseño/intención. El analizador usado
|
||||
por el agente integrado solo admite claves de frontmatter de **una línea**;
|
||||
`metadata` debe ser un **objeto JSON de una línea**. Usa `{baseDir}` en
|
||||
las instrucciones para hacer referencia a la ruta de la carpeta de la skill.
|
||||
OpenClaw sigue la especificación de AgentSkills para diseño/intención. El parser usado por el agente integrado admite solo claves de frontmatter de **una línea**; `metadata` debe ser un **objeto JSON de una línea**. Usa `{baseDir}` en instrucciones para referenciar la ruta de la carpeta del skill.
|
||||
|
||||
### Claves opcionales de frontmatter
|
||||
|
||||
<ParamField path="homepage" type="string">
|
||||
URL mostrada como "Sitio web" en la UI de Skills de macOS. También se admite mediante `metadata.openclaw.homepage`.
|
||||
URL mostrada como "Sitio web" en la UI de Skills de macOS. También compatible mediante `metadata.openclaw.homepage`.
|
||||
</ParamField>
|
||||
<ParamField path="user-invocable" type="boolean" default="true">
|
||||
Cuando es `true`, la skill se expone como un comando slash de usuario.
|
||||
Cuando es `true`, el skill se expone como slash command de usuario.
|
||||
</ParamField>
|
||||
<ParamField path="disable-model-invocation" type="boolean" default="false">
|
||||
Cuando es `true`, la skill se excluye del prompt del modelo (sigue disponible mediante invocación de usuario).
|
||||
Cuando es `true`, el skill se excluye del prompt del modelo (sigue disponible mediante invocación del usuario).
|
||||
</ParamField>
|
||||
<ParamField path="command-dispatch" type='"tool"'>
|
||||
Cuando se define como `tool`, el comando slash omite el modelo y se despacha directamente a una herramienta.
|
||||
Cuando se establece en `tool`, el slash command omite el modelo y se despacha directamente a una herramienta.
|
||||
</ParamField>
|
||||
<ParamField path="command-tool" type="string">
|
||||
Nombre de la herramienta que se invoca cuando se define `command-dispatch: tool`.
|
||||
Nombre de la herramienta que se invoca cuando se establece `command-dispatch: tool`.
|
||||
</ParamField>
|
||||
<ParamField path="command-arg-mode" type='"raw"' default="raw">
|
||||
Para el despacho a herramienta, reenvía la cadena de argumentos sin procesar a la herramienta (sin análisis del core). La herramienta se invoca con `{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }`.
|
||||
Para despacho a herramienta, reenvía la cadena de argumentos sin procesar a la herramienta (sin parsing del núcleo). La herramienta se invoca con `{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }`.
|
||||
</ParamField>
|
||||
|
||||
## Condicionamiento (filtros en tiempo de carga)
|
||||
|
||||
OpenClaw filtra skills en tiempo de carga usando `metadata` (JSON de una línea):
|
||||
OpenClaw filtra Skills en el momento de carga usando `metadata` (JSON de una línea):
|
||||
|
||||
```markdown
|
||||
---
|
||||
@ -216,7 +183,7 @@ metadata:
|
||||
Campos bajo `metadata.openclaw`:
|
||||
|
||||
<ParamField path="always" type="boolean">
|
||||
Cuando es `true`, incluye siempre la skill (omite otras condiciones).
|
||||
Cuando es `true`, siempre incluye el skill (omite otras condiciones).
|
||||
</ParamField>
|
||||
<ParamField path="emoji" type="string">
|
||||
Emoji opcional usado por la UI de Skills de macOS.
|
||||
@ -225,7 +192,7 @@ Campos bajo `metadata.openclaw`:
|
||||
URL opcional mostrada como "Sitio web" en la UI de Skills de macOS.
|
||||
</ParamField>
|
||||
<ParamField path="os" type='"darwin" | "linux" | "win32"' >
|
||||
Lista opcional de plataformas. Si se define, la skill solo es elegible en esos SO.
|
||||
Lista opcional de plataformas. Si se establece, el skill solo es apto en esos sistemas operativos.
|
||||
</ParamField>
|
||||
<ParamField path="requires.bins" type="string[]">
|
||||
Cada uno debe existir en `PATH`.
|
||||
@ -246,28 +213,24 @@ Campos bajo `metadata.openclaw`:
|
||||
Especificaciones opcionales de instalador usadas por la UI de Skills de macOS (brew/node/go/uv/download).
|
||||
</ParamField>
|
||||
|
||||
Si no hay `metadata.openclaw`, la skill siempre es elegible (salvo que esté
|
||||
deshabilitada en la configuración o bloqueada por `skills.allowBundled` para skills incluidas).
|
||||
Si no está presente `metadata.openclaw`, el skill siempre es apto (salvo que esté deshabilitado en la configuración o bloqueado por `skills.allowBundled` para Skills incluidos).
|
||||
|
||||
<Note>
|
||||
Los bloques heredados `metadata.clawdbot` todavía se aceptan cuando
|
||||
`metadata.openclaw` está ausente, por lo que las skills instaladas antiguas conservan sus
|
||||
condiciones de dependencias y sugerencias de instalador. Las skills nuevas y actualizadas deben usar
|
||||
`metadata.openclaw`.
|
||||
Los bloques heredados `metadata.clawdbot` siguen aceptándose cuando `metadata.openclaw` está ausente, de modo que los Skills instalados antiguos conservan sus condiciones de dependencia e indicaciones de instalador. Los Skills nuevos y actualizados deben usar `metadata.openclaw`.
|
||||
</Note>
|
||||
|
||||
### Notas de sandboxing
|
||||
|
||||
- `requires.bins` se comprueba en el **host** en tiempo de carga de la skill.
|
||||
- `requires.bins` se comprueba en el **host** en el momento de carga del skill.
|
||||
- Si un agente está en sandbox, el binario también debe existir **dentro del contenedor**. Instálalo mediante `agents.defaults.sandbox.docker.setupCommand` (o una imagen personalizada). `setupCommand` se ejecuta una vez después de crear el contenedor. Las instalaciones de paquetes también requieren salida de red, un FS raíz escribible y un usuario root en el sandbox.
|
||||
- Ejemplo: la skill `summarize` (`skills/summarize/SKILL.md`) necesita la CLI `summarize` en el contenedor de sandbox para ejecutarse allí.
|
||||
- Ejemplo: el skill `summarize` (`skills/summarize/SKILL.md`) necesita la CLI `summarize` en el contenedor de sandbox para ejecutarse allí.
|
||||
|
||||
### Especificaciones de instalador
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: gemini
|
||||
description: Use Gemini CLI for coding assistance and Google search lookups.
|
||||
description: Usa Gemini CLI para asistencia de programación y búsquedas en Google.
|
||||
metadata:
|
||||
{
|
||||
"openclaw":
|
||||
@ -281,7 +244,7 @@ metadata:
|
||||
"kind": "brew",
|
||||
"formula": "gemini-cli",
|
||||
"bins": ["gemini"],
|
||||
"label": "Install Gemini CLI (brew)",
|
||||
"label": "Instalar Gemini CLI (brew)",
|
||||
},
|
||||
],
|
||||
},
|
||||
@ -291,25 +254,25 @@ metadata:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Reglas de selección del instalador">
|
||||
- Si se enumeran varios instaladores, el Gateway elige una sola opción preferida (brew cuando está disponible; de lo contrario, node).
|
||||
- Si todos los instaladores son `download`, OpenClaw enumera cada entrada para que puedas ver los artefactos disponibles.
|
||||
- Si se enumeran varios instaladores, el Gateway elige una única opción preferida (brew cuando está disponible; de lo contrario, node).
|
||||
- Si todos los instaladores son `download`, OpenClaw muestra cada entrada para que puedas ver los artefactos disponibles.
|
||||
- Las especificaciones del instalador pueden incluir `os: ["darwin"|"linux"|"win32"]` para filtrar opciones por plataforma.
|
||||
- Las instalaciones de Node respetan `skills.install.nodeManager` en `openclaw.json` (predeterminado: npm; opciones: npm/pnpm/yarn/bun). Esto solo afecta a las instalaciones de Skills; el entorno de ejecución del Gateway debe seguir siendo Node; no se recomienda Bun para WhatsApp/Telegram.
|
||||
- La selección de instalador respaldada por el Gateway se basa en preferencias: cuando las especificaciones de instalación mezclan tipos, OpenClaw prefiere Homebrew cuando `skills.install.preferBrew` está habilitado y `brew` existe, luego `uv`, luego el gestor de node configurado, y luego otros recursos alternativos como `go` o `download`.
|
||||
- Las instalaciones de Node respetan `skills.install.nodeManager` en `openclaw.json` (predeterminado: npm; opciones: npm/pnpm/yarn/bun). Esto solo afecta a las instalaciones de Skills; el tiempo de ejecución del Gateway debe seguir siendo Node: Bun no se recomienda para WhatsApp/Telegram.
|
||||
- La selección de instalador respaldada por Gateway se basa en preferencias: cuando las especificaciones de instalación mezclan tipos, OpenClaw prefiere Homebrew cuando `skills.install.preferBrew` está habilitado y `brew` existe, luego `uv`, luego el gestor de node configurado y después otros mecanismos de reserva como `go` o `download`.
|
||||
- Si cada especificación de instalación es `download`, OpenClaw muestra todas las opciones de descarga en lugar de reducirlas a un instalador preferido.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Detalles por instalador">
|
||||
- **Instalaciones de Go:** si falta `go` y `brew` está disponible, el gateway instala primero Go mediante Homebrew y define `GOBIN` en el `bin` de Homebrew cuando es posible.
|
||||
- **Instalaciones de Go:** si falta `go` y `brew` está disponible, el gateway instala primero Go mediante Homebrew y establece `GOBIN` en el `bin` de Homebrew cuando es posible.
|
||||
- **Instalaciones por descarga:** `url` (obligatorio), `archive` (`tar.gz` | `tar.bz2` | `zip`), `extract` (predeterminado: automático cuando se detecta un archivo), `stripComponents`, `targetDir` (predeterminado: `~/.openclaw/tools/<skillKey>`).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Sobrescrituras de configuración
|
||||
## Anulaciones de configuración
|
||||
|
||||
Las Skills incluidas y administradas pueden activarse o desactivarse y recibir valores de entorno
|
||||
en `skills.entries` dentro de `~/.openclaw/openclaw.json`:
|
||||
Las Skills incluidas y gestionadas se pueden activar o desactivar y recibir valores de entorno
|
||||
en `skills.entries`, dentro de `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -334,37 +297,35 @@ en `skills.entries` dentro de `~/.openclaw/openclaw.json`:
|
||||
```
|
||||
|
||||
<ParamField path="enabled" type="boolean">
|
||||
`false` desactiva la Skill incluso si está incluida o instalada.
|
||||
La Skill incluida `coding-agent` es opcional: define
|
||||
`false` deshabilita la Skill incluso si está incluida o instalada.
|
||||
La Skill incluida `coding-agent` es opcional: establece
|
||||
`skills.entries.coding-agent.enabled: true` antes de exponerla a los agentes,
|
||||
y luego asegúrate de que uno de `claude`, `codex`, `opencode` o `pi` esté instalado y
|
||||
autenticado para su propia CLI.
|
||||
</ParamField>
|
||||
<ParamField path="apiKey" type='string | { source, provider, id }'>
|
||||
Atajo para Skills que declaran `metadata.openclaw.primaryEnv`. Admite texto plano o SecretRef.
|
||||
Conveniencia para Skills que declaran `metadata.openclaw.primaryEnv`. Admite texto sin formato o SecretRef.
|
||||
</ParamField>
|
||||
<ParamField path="env" type="Record<string, string>">
|
||||
Se inyecta solo si la variable aún no está definida en el proceso.
|
||||
</ParamField>
|
||||
<ParamField path="config" type="object">
|
||||
Contenedor opcional para campos personalizados por Skill. Las claves personalizadas deben vivir aquí.
|
||||
Bolsa opcional para campos personalizados por Skill. Las claves personalizadas deben estar aquí.
|
||||
</ParamField>
|
||||
<ParamField path="allowBundled" type="string[]">
|
||||
Lista de permitidos opcional solo para Skills **incluidas**. Si se define, solo las Skills incluidas en la lista son elegibles (las Skills administradas/de espacio de trabajo no se ven afectadas).
|
||||
Lista de permitidos opcional solo para Skills **incluidas**. Si se establece, solo las Skills incluidas en la lista son elegibles (las Skills gestionadas/de espacio de trabajo no se ven afectadas).
|
||||
</ParamField>
|
||||
|
||||
Si el nombre de la Skill contiene guiones, pon la clave entre comillas (JSON5 permite claves
|
||||
entre comillas). Las claves de configuración coinciden con el **nombre de la Skill** de forma predeterminada; si una Skill
|
||||
entrecomilladas). Las claves de configuración coinciden con el **nombre de la Skill** de forma predeterminada; si una Skill
|
||||
define `metadata.openclaw.skillKey`, usa esa clave en `skills.entries`.
|
||||
|
||||
<Note>
|
||||
Para generación/edición de imágenes de stock dentro de OpenClaw, usa la herramienta principal
|
||||
Para generar/editar imágenes de stock dentro de OpenClaw, usa la herramienta principal
|
||||
`image_generate` con `agents.defaults.imageGenerationModel` en lugar
|
||||
de una Skill incluida. Los ejemplos de Skills aquí son para flujos de trabajo personalizados o de terceros.
|
||||
Para análisis de imágenes nativo, usa la herramienta `image` con
|
||||
de una Skill incluida. Los ejemplos de Skills aquí son para flujos de trabajo personalizados o de terceros. Para análisis de imágenes nativo, usa la herramienta `image` con
|
||||
`agents.defaults.imageModel`. Si eliges `openai/*`, `google/*`,
|
||||
`fal/*` u otro modelo de imagen específico de proveedor, añade también la clave de autenticación/API
|
||||
de ese proveedor.
|
||||
`fal/*` u otro modelo de imagen específico de proveedor, añade también la clave de autenticación/API de ese proveedor.
|
||||
</Note>
|
||||
|
||||
## Inyección de entorno
|
||||
@ -373,39 +334,39 @@ Cuando se inicia una ejecución de agente, OpenClaw:
|
||||
|
||||
1. Lee los metadatos de la Skill.
|
||||
2. Aplica `skills.entries.<key>.env` y `skills.entries.<key>.apiKey` a `process.env`.
|
||||
3. Construye el prompt del sistema con Skills **elegibles**.
|
||||
4. Restaura el entorno original después de que finaliza la ejecución.
|
||||
3. Construye el prompt del sistema con las Skills **elegibles**.
|
||||
4. Restaura el entorno original después de que termina la ejecución.
|
||||
|
||||
La inyección de entorno está **limitada a la ejecución del agente**, no a un entorno de shell
|
||||
global.
|
||||
La inyección de entorno está **limitada a la ejecución del agente**, no a un entorno
|
||||
global de shell.
|
||||
|
||||
Para el backend incluido `claude-cli`, OpenClaw también materializa la misma
|
||||
Para el backend `claude-cli` incluido, OpenClaw también materializa la misma
|
||||
instantánea elegible como un Plugin temporal de Claude Code y la pasa con
|
||||
`--plugin-dir`. Claude Code puede entonces usar su resolutor nativo de Skills mientras
|
||||
OpenClaw sigue controlando la precedencia, las listas de permitidos por agente, las puertas de activación y
|
||||
la inyección de variables de entorno/claves de API de `skills.entries.*`. Otros backends de CLI usan solo el
|
||||
`--plugin-dir`. Claude Code puede entonces usar su resolvedor nativo de Skills mientras
|
||||
OpenClaw sigue controlando la precedencia, las listas de permitidos por agente, las puertas de acceso y la
|
||||
inyección de claves de entorno/API de `skills.entries.*`. Otros backends de CLI usan solo el
|
||||
catálogo del prompt.
|
||||
|
||||
## Instantáneas y actualización
|
||||
|
||||
OpenClaw toma instantáneas de las Skills elegibles **cuando se inicia una sesión** y
|
||||
reutiliza esa lista para los turnos posteriores de la misma sesión. Los cambios en
|
||||
OpenClaw toma una instantánea de las Skills elegibles **cuando se inicia una sesión** y
|
||||
reutiliza esa lista en los turnos posteriores de la misma sesión. Los cambios en
|
||||
Skills o en la configuración surten efecto en la siguiente sesión nueva.
|
||||
|
||||
Las Skills pueden actualizarse a mitad de sesión en dos casos:
|
||||
Las Skills pueden actualizarse en mitad de una sesión en dos casos:
|
||||
|
||||
- El observador de Skills está habilitado.
|
||||
- Aparece un nuevo nodo remoto elegible.
|
||||
|
||||
Piensa en esto como una **recarga en caliente**: la lista actualizada se usa en el
|
||||
siguiente turno del agente. Si la lista efectiva de Skills permitidas para el agente cambia para esa
|
||||
sesión, OpenClaw actualiza la instantánea para que las Skills visibles permanezcan alineadas
|
||||
Piensa en esto como una **recarga en caliente**: la lista actualizada se recoge en el
|
||||
siguiente turno del agente. Si la lista de Skills permitidas efectiva del agente cambia para esa
|
||||
sesión, OpenClaw actualiza la instantánea para que las Skills visibles sigan alineadas
|
||||
con el agente actual.
|
||||
|
||||
### Observador de Skills
|
||||
|
||||
De forma predeterminada, OpenClaw observa las carpetas de Skills e incrementa la instantánea de Skills
|
||||
cuando cambian archivos `SKILL.md`. Configúralo en `skills.load`:
|
||||
De forma predeterminada, OpenClaw observa las carpetas de Skills y actualiza la instantánea de Skills
|
||||
cuando cambian los archivos `SKILL.md`. Configúralo en `skills.load`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -418,19 +379,19 @@ cuando cambian archivos `SKILL.md`. Configúralo en `skills.load`:
|
||||
}
|
||||
```
|
||||
|
||||
### Nodos macOS remotos (Gateway en Linux)
|
||||
### Nodos macOS remotos (Gateway Linux)
|
||||
|
||||
Si el Gateway se ejecuta en Linux pero hay un **nodo macOS** conectado con
|
||||
`system.run` permitido (seguridad de aprobaciones de Exec no definida en `deny`),
|
||||
OpenClaw puede tratar las Skills solo para macOS como elegibles cuando los binarios requeridos
|
||||
están presentes en ese nodo. El agente debe ejecutar esas Skills
|
||||
`system.run` permitido (seguridad de aprobaciones de Exec no configurada en `deny`),
|
||||
OpenClaw puede tratar las Skills solo para macOS como elegibles cuando los
|
||||
binarios requeridos están presentes en ese nodo. El agente debe ejecutar esas Skills
|
||||
mediante la herramienta `exec` con `host=node`.
|
||||
|
||||
Esto depende de que el nodo informe su soporte de comandos y de una comprobación de binarios
|
||||
Esto depende de que el nodo informe su compatibilidad de comandos y de una comprobación de binarios
|
||||
mediante `system.which` o `system.run`. Los nodos sin conexión **no** hacen
|
||||
visibles las Skills solo remotas. Si un nodo conectado deja de responder a comprobaciones de
|
||||
binarios, OpenClaw borra sus coincidencias de binarios en caché para que los agentes ya no vean
|
||||
Skills que actualmente no pueden ejecutarse allí.
|
||||
visibles las Skills solo remotas. Si un nodo conectado deja de responder a las
|
||||
comprobaciones de binarios, OpenClaw borra sus coincidencias de binarios en caché para que los agentes ya no vean
|
||||
Skills que no pueden ejecutarse allí actualmente.
|
||||
|
||||
## Impacto en tokens
|
||||
|
||||
@ -438,8 +399,8 @@ Cuando las Skills son elegibles, OpenClaw inyecta una lista XML compacta de Skil
|
||||
disponibles en el prompt del sistema (mediante `formatSkillsForPrompt` en
|
||||
`pi-coding-agent`). El coste es determinista:
|
||||
|
||||
- **Sobrecoste base** (solo cuando hay ≥1 Skill): 195 caracteres.
|
||||
- **Por Skill:** 97 caracteres + la longitud de los valores `<name>`, `<description>` y `<location>` escapados para XML.
|
||||
- **Sobrecarga base** (solo cuando hay ≥1 Skill): 195 caracteres.
|
||||
- **Por Skill:** 97 caracteres + la longitud de los valores `<name>`, `<description>` y `<location>` escapados en XML.
|
||||
|
||||
Fórmula (caracteres):
|
||||
|
||||
@ -447,29 +408,29 @@ Fórmula (caracteres):
|
||||
total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))
|
||||
```
|
||||
|
||||
El escape XML expande `& < > " '` en entidades (`&`, `<`, etc.),
|
||||
lo que aumenta la longitud. Los conteos de tokens varían según el tokenizador del modelo. Una estimación aproximada
|
||||
de estilo OpenAI es ~4 caracteres/token, por lo que **97 caracteres ≈ 24 tokens** por
|
||||
El escapado XML expande `& < > " '` en entidades (`&`, `<`, etc.),
|
||||
lo que aumenta la longitud. Los recuentos de tokens varían según el tokenizador del modelo. Una estimación aproximada
|
||||
al estilo de OpenAI es ~4 caracteres/token, por lo que **97 caracteres ≈ 24 tokens** por
|
||||
Skill más las longitudes reales de tus campos.
|
||||
|
||||
## Ciclo de vida de Skills administradas
|
||||
## Ciclo de vida de Skills gestionadas
|
||||
|
||||
OpenClaw incluye un conjunto base de Skills como **Skills incluidas** con la
|
||||
instalación (paquete npm u OpenClaw.app). `~/.openclaw/skills` existe para
|
||||
sobrescrituras locales; por ejemplo, fijar o parchear una Skill sin
|
||||
cambiar la copia incluida. Las Skills de espacio de trabajo pertenecen al usuario y sobrescriben
|
||||
ambas cuando hay conflictos de nombre.
|
||||
anulaciones locales; por ejemplo, fijar o parchear una Skill sin
|
||||
cambiar la copia incluida. Las Skills de espacio de trabajo son propiedad del usuario y prevalecen
|
||||
sobre ambas en conflictos de nombre.
|
||||
|
||||
## ¿Buscas más Skills?
|
||||
|
||||
Explora [https://clawhub.ai](https://clawhub.ai). Esquema completo de configuración:
|
||||
[Configuración de Skills](/es/tools/skills-config).
|
||||
Explora [https://clawhub.ai](https://clawhub.ai). Esquema de configuración
|
||||
completo: [Configuración de Skills](/es/tools/skills-config).
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [ClawHub](/es/tools/clawhub) — registro público de Skills
|
||||
- [Crear Skills](/es/tools/creating-skills) — creación de Skills personalizadas
|
||||
- [Plugins](/es/tools/plugin) — descripción general del sistema de Plugins
|
||||
- [Plugin Skill Workshop](/es/plugins/skill-workshop) — genera Skills a partir del trabajo del agente
|
||||
- [Crear Skills](/es/tools/creating-skills) — crear Skills personalizadas
|
||||
- [Plugins](/es/tools/plugin) — descripción general del sistema de plugins
|
||||
- [Plugin Skill Workshop](/es/plugins/skill-workshop) — generar Skills a partir del trabajo del agente
|
||||
- [Configuración de Skills](/es/tools/skills-config) — referencia de configuración de Skills
|
||||
- [Comandos de barra](/es/tools/slash-commands) — todos los comandos de barra disponibles
|
||||
|
||||
Loading…
Reference in New Issue
Block a user