openclaw path
Acceso desde shell al esquema de direccionamiento oc://: una sintaxis de rutas despachada por tipo para inspeccionar y editar archivos direccionables del espacio de trabajo (markdown, jsonc, jsonl, yaml/yml/lobster). Quienes se autohospedan, los autores de plugins y las extensiones de editores lo usan para leer, buscar o actualizar una ubicación acotada sin crear manualmente un analizador por archivo.
path lo proporciona el Plugin opcional incluido oc-path. Habilítalo antes del primer uso:
resolvees concreto y de coincidencia única.findes el verbo de múltiples coincidencias para comodines, uniones, predicados y expansión posicional.setsolo acepta rutas concretas o marcadores de inserción; los patrones con comodines se rechazan antes de escribir.validateanaliza una ruta sin acceso al sistema de archivos.emithace una ida y vuelta de un archivo mediante parse + emit (diagnóstico de fidelidad byte a byte).
Por qué usarlo
El estado de OpenClaw está repartido entre markdown editado por humanos, configuración JSONC con comentarios, registros JSONL de solo anexado y archivos YAML de flujos de trabajo/especificaciones. Scripts, hooks y agentes a menudo necesitan un valor pequeño de esos archivos: una clave de frontmatter, una configuración de plugin, un campo de registro de log, un paso YAML o un elemento de lista bajo una sección con nombre.openclaw path da a esos llamadores una dirección estable en lugar de un grep, una regex o un analizador puntual por cada tipo de archivo. La misma ruta oc:// se puede validar, resolver, buscar, ejecutar en simulación y escribir desde la terminal, lo que mantiene la automatización acotada revisable y reproducible. Preserva el resto del archivo, de modo que escribir una hoja no altera sus comentarios, finales de línea ni el formato cercano.
Úsalo cuando lo que quieres tiene una dirección lógica, pero la forma del archivo varía:
- Un hook lee una configuración de JSONC con comentarios sin perder comentarios cuando vuelve a escribir el valor.
- Un script de mantenimiento encuentra todos los campos de evento coincidentes en un log JSONL sin cargar todo el log en un analizador personalizado.
- Un editor salta a una sección de markdown o a un elemento de lista por slug, y luego renderiza la línea exacta que resolvió.
- Un agente simula una pequeña edición del espacio de trabajo antes de aplicarla, con los bytes cambiados visibles en la revisión.
openclaw path para ediciones ordinarias de archivos completos, migraciones ricas de configuración o escrituras específicas de memoria; esas deben usar el comando o Plugin propietario. path es para operaciones pequeñas y direccionables sobre archivos en las que un comando de terminal repetible supera a otro analizador a medida.
Cómo se usa
Leer un valor de un archivo de configuración editado por humanos:--json cuando un llamador necesite salida estructurada y --human cuando una persona esté inspeccionando el resultado.
Cómo funciona
- Analiza la dirección
oc://en ranuras: archivo, sección, elemento, campo y una consulta de sesión opcional. - Elige el adaptador de tipo de archivo a partir de la extensión de destino (
.md,.jsonc,.json,.jsonl,.ndjson,.yaml,.yml,.lobster). - Resuelve las ranuras contra la estructura de ese tipo de archivo: encabezados/elementos de markdown, claves de objeto/índices de array JSONC, registros de línea JSONL o nodos de mapa/secuencia YAML.
- Para
set, emite bytes editados mediante el mismo adaptador, de modo que las partes intactas del archivo conserven sus comentarios, finales de línea y formato cercano cuando el tipo lo admite.
resolve y set requieren un objetivo concreto. find es el verbo exploratorio: expande comodines, uniones, predicados y ordinales en las coincidencias concretas que puedes inspeccionar antes de elegir una para escribir.
Subcomandos
| Subcomando | Propósito |
|---|---|
resolve <oc-path> | Imprimir la coincidencia concreta en la ruta (o “no encontrado”). |
find <pattern> | Enumerar coincidencias para una ruta con comodín / unión / predicado. |
set <oc-path> <value> | Escribir una hoja u objetivo de inserción en una ruta concreta. Admite --dry-run. |
validate <oc-path> | Solo análisis; imprimir el desglose estructural (archivo / sección / elemento / campo). |
emit <file> | Hacer una ida y vuelta de un archivo mediante parse + emit (diagnóstico de fidelidad byte a byte). |
Flags globales
| Flag | Se aplica a | Propósito |
|---|---|---|
--cwd <dir> | resolve, find, set, emit | Resolver la ranura de archivo contra este directorio (predeterminado: process.cwd()). |
--file <path> | resolve, find, set, emit | Sustituir la ruta resuelta de la ranura de archivo (acceso absoluto). |
--json | todos | Forzar salida JSON (predeterminado cuando stdout no es una TTY). |
--human | todos | Forzar salida humana (predeterminado cuando stdout es una TTY). |
--value-json | set | Analizar <value> como JSON para reemplazo de hojas JSON/JSONC/JSONL. |
--dry-run | set | Imprimir los bytes que se escribirían sin escribir. |
--diff | set (requiere --dry-run) | Imprimir un diff unificado en lugar de los bytes completos. |
validate solo acepta --json / --human; no realiza acceso al sistema de archivos, por lo que --cwd y --file no se aplican.
Sintaxis oc://
field requiere item, e item requiere section. En las cuatro ranuras:
- Segmentos entre comillas —
"a/b.c"sobrevive a los separadores/y.. El contenido es literal a nivel de bytes;"y\no están permitidos dentro de las comillas. La ranura de archivo también reconoce comillas:oc://"skills/email-drafter"/Tools/$lasttrataskills/email-draftercomo una única ruta de archivo. - Predicados —
[k=v],[k!=v],[k<v],[k<=v],[k>v],[k>=v]. Los operadores numéricos requieren que ambos lados se conviertan a números finitos. - Uniones —
{a,b,c}coincide con cualquiera de las alternativas. - Comodines —
*(un solo subsegmento) y**(cero o más, recursivo).findlos acepta;resolveysetlos rechazan por ambiguos. - Posicional —
$first/$lastse resuelven al primer / último índice o clave declarada. - Ordinal —
#Npara la enésima coincidencia según el orden del documento. - Marcadores de inserción —
+,+key,+nnnpara inserción con clave / indexada (usar conset). - Ámbito de sesión —
?session=cron-daily, etc. Ortogonal al anidamiento de ranuras. Los valores de sesión son raw, no decodificados por porcentaje; no pueden contener caracteres de control ni delimitadores de consulta reservados (?,&,%).
?, &, %) fuera de segmentos entre comillas, de predicado o de unión se rechazan. Los caracteres de control (U+0000-U+001F, U+007F) se rechazan en cualquier lugar, incluido el valor de consulta session.
formatOcPath(parseOcPath(path)) === path está garantizado para rutas canónicas. Los parámetros de consulta no canónicos se ignoran salvo por el primer valor session= no vacío.
Límites estrictos: una ruta tiene un máximo de 4096 bytes, como máximo 4 ranuras (archivo/sección/elemento/campo), como máximo 64 subsegmentos con puntos por ranura y como máximo 256 niveles de recorrido anidado para rutas JSON profundas. Por separado, cualquier entrada de archivo JSONC/JSON de más de 16 MiB se rechaza con un diagnóstico de análisis en lugar de analizarse, para cualquier verbo que cargue ese archivo.
Direccionamiento por tipo de archivo
| Tipo | Extensiones de archivo | Modelo de direccionamiento |
|---|---|---|
| Markdown | .md | Secciones H2 por slug, elementos de lista por slug o #N, frontmatter mediante [frontmatter]. |
| JSONC/JSON | .jsonc, .json | Claves de objeto e índices de array; los puntos separan subsegmentos anidados salvo que estén entre comillas. |
| JSONL | .jsonl, .ndjson | Direcciones de línea de nivel superior (L1, L2, $first, $last), luego descenso estilo JSONC dentro de la línea. |
| YAML/.lobster | .yaml, .yml, .lobster | Claves de mapa e índices de secuencia; los comentarios y el estilo de flujo los maneja la API de documento YAML. |
resolve devuelve una coincidencia estructurada: root, node, leaf o insertion-point, con un número de línea basado en 1. Los valores de hoja se exponen como texto más un leafType, de modo que los autores de plugins puedan renderizar previsualizaciones sin depender de la forma AST específica de cada tipo.
Contrato de mutación
set escribe un objetivo concreto:
- Los valores de frontmatter de Markdown y los campos de elemento
- key: valueson hojas de cadena. Las inserciones de Markdown anexan secciones, claves de frontmatter o elementos de sección, y renderizan una forma markdown canónica para el archivo cambiado. Los cuerpos de sección no se pueden escribir completos medianteset. - Las escrituras de hojas JSONC convierten el valor de cadena al tipo de hoja existente (
string,numberfinito,true/falseonull). Usa--value-jsoncuando un reemplazo de hoja JSONC/JSON/JSONL deba analizar<value>como JSON y pueda cambiar de forma, como reemplazar una abreviatura de referencia secreta de cadena por un objeto. Las inserciones de objetos y arrays JSONC analizan<value>como JSON y usan la ruta de edición dejsonc-parserpara escrituras ordinarias de hojas, preservando comentarios y formato cercano. - Las escrituras de hojas JSONL convierten como JSONC dentro de una línea. El reemplazo de línea completa y el anexado analizan
<value>como JSON. El JSONL renderizado preserva la convención dominante de finales de línea LF/CRLF del archivo (voto mayoritario entre los saltos de línea del archivo, de modo que un archivo mayoritariamente CRLF permanece CRLF incluso con unos pocos LF sueltos). - Las escrituras de hojas YAML convierten al tipo escalar existente (
string,numberfinito,true/falseonull). Las inserciones YAML usan la API de documento del paqueteyamlincluido para actualizaciones de mapas/secuencias. Los documentos YAML malformados con errores de analizador se rechazan antes de la mutación conparse-error.
--dry-run antes de escrituras visibles para usuarios cuando importen los bytes exactos. Las ediciones JSONC y YAML parchean el documento existente (mediante jsonc-parser o la API de documento yaml), por lo que los bytes intactos normalmente sobreviven; markdown reconstruye el archivo desde su estructura analizada en cualquier edición, lo que puede normalizar formato incidental fuera de la hoja cambiada. Añade --diff cuando quieras la previsualización como un parche enfocado de antes/después en lugar del archivo renderizado completo.
Ejemplos
Recetas por tipo de archivo
Los mismos cinco verbos funcionan en todos los tipos; el esquema de direccionamiento se despacha según la extensión del archivo.Markdown
[frontmatter] dirige al bloque de frontmatter YAML; tools
coincide con el encabezado ## Tools mediante slug, y las hojas de elementos conservan su forma de slug
incluso cuando el origen usa guiones bajos (send_email se convierte en send-email).
JSONC
jsonc-parser, por lo que los comentarios y los espacios sobreviven a un
set. Ejecuta primero con --dry-run para inspeccionar los bytes antes de confirmar.
Los archivos .json usan el mismo adaptador y ruta de edición que .jsonc.
JSONL
[event=action]) cuando no
conozcas el número de línea, o por el segmento canónico LN cuando sí.
Los archivos .ndjson usan el mismo adaptador que .jsonl.
YAML
Document del paquete yaml en lugar de un
analizador hecho a mano, por lo que los recorridos ordinarios de analizar/emitir conservan comentarios y la forma de autoría
mientras las rutas resueltas usan el mismo modelo de clave de mapa / índice de secuencia que
JSONC. El mismo adaptador gestiona archivos .yaml, .yml y .lobster.
Referencia de subcomandos
resolve <oc-path>
Lee una sola hoja o nodo. Los comodines se rechazan: usa find para ellos.
Sale con 0 si hay coincidencia, 1 en una ausencia limpia, 2 ante un error de análisis o un patrón
rechazado.
find <pattern>
Enumera cada coincidencia para un patrón de comodín / predicado / unión. Sale con 0
si hay al menos una coincidencia, 1 si no hay ninguna. Los comodines en la posición de archivo se rechazan con
OC_PATH_FILE_WILDCARD_UNSUPPORTED: pasa un archivo concreto (el globbing
de varios archivos es una función futura).
set <oc-path> <value>
Escribe una hoja. Combínalo con --dry-run para previsualizar los bytes que se
escribirían sin tocar el archivo. Añade --diff para una vista previa de diff unificado.
Sale con 0 si la escritura se completa correctamente, 1 si el sustrato la rechaza (por ejemplo, si se activa una
guarda centinela), 2 ante errores de análisis.
+key crea el hijo nombrado si todavía no
existe; +nnn y + sin más funcionan para inserción indexada y agregación,
respectivamente.
validate <oc-path>
Comprobación solo de análisis. Sin acceso al sistema de archivos. Útil cuando quieres confirmar que una
ruta de plantilla está bien formada antes de sustituir variables, o cuando quieres
el desglose estructural para depuración:
0 cuando es válida, 1 cuando no lo es (con un code y
message estructurados), 2 ante errores de argumentos.
emit <file>
Hace un recorrido de ida y vuelta de un archivo por el analizador y emisor de su tipo. La salida debería
ser idéntica byte a byte a la entrada en un archivo sano; cualquier divergencia indica un
error del analizador o la activación de un centinela. Útil para depurar el comportamiento del sustrato en
entradas reales.
Códigos de salida
| Código | Significado |
|---|---|
0 | Éxito. (resolve / find: al menos una coincidencia. set: escritura completada correctamente.) |
1 | Sin coincidencia, o set rechazado por el sustrato (sin error a nivel de sistema). |
2 | Error de argumento o de análisis. |
Modo de salida
openclaw path detecta TTY: salida legible para humanos en un terminal, JSON cuando
stdout se canaliza o redirige. --json y --human anulan la
detección automática.
Notas
setescribe bytes mediante la ruta de emisión del sustrato, que aplica la guarda de centinela de redacción automáticamente. Una hoja que contenga__OPENCLAW_REDACTED__(literalmente o como subcadena) se rechaza en el momento de escritura.- El análisis JSONC y las ediciones de hojas usan la dependencia local del Plugin
jsonc-parser, por lo que los comentarios y el formato se preservan en escrituras ordinarias de hojas en lugar de pasar por una ruta de analizador/reprocesado hecha a mano. pathno conoce el seguimiento ni la recuperación de la configuración last-known-good (LKG); ese ciclo de vida pertenece a otra parte. Si un archivo que editas mediantepathtambién tiene seguimiento LKG, la siguiente lectura de configuración decide si promoverlo o recuperarlo; trata una edición depathigual que cualquier otra escritura directa en ese archivo.