openclaw path
Acesso de shell fornecido por Plugin ao substrato de endereçamento oc://: um
esquema de caminhos despachado por tipo para inspecionar e editar arquivos
endereçáveis do workspace (markdown, jsonc, jsonl, yaml/yml/lobster). Operadores
self-hosted, autores de Plugin e extensões de editor o usam para ler, localizar
ou atualizar um local restrito sem criar parsers por arquivo manualmente.
A CLI espelha os verbos públicos do substrato:
resolveé concreto e de correspondência única.findé o verbo de múltiplas correspondências para curingas, uniões, predicados e expansão posicional.setaceita apenas caminhos concretos ou marcadores de inserção; padrões com curinga são rejeitados antes da escrita.
path é fornecido pelo Plugin opcional incluído oc-path. Habilite-o antes
do primeiro uso:
Por que usá-lo
O estado do OpenClaw fica espalhado por markdown editado por humanos, configuração JSONC comentada, logs JSONL somente de acréscimo e arquivos YAML de workflow/especificação. Scripts de shell, hooks e agentes frequentemente precisam de um pequeno valor desses arquivos: uma chave de frontmatter, uma configuração de Plugin, um campo de registro de log, uma etapa YAML ou um item de lista sob uma seção nomeada.openclaw path dá a esses chamadores um endereço estável em vez de um grep,
regex ou parser pontual para cada tipo de arquivo. O mesmo caminho oc:// pode ser validado,
resolvido, pesquisado, simulado e escrito pelo terminal, o que torna automações restritas
mais fáceis de revisar e mais seguras de reproduzir. Ele é especialmente útil quando
você quer atualizar uma folha preservando o restante dos comentários, quebras de linha e
formatação adjacente do arquivo.
Use-o quando o que você quer tem um endereço lógico, mas o formato físico do arquivo
varia:
- Um hook quer ler uma configuração de JSONC comentado sem perder comentários ao gravar o valor de volta.
- Um script de manutenção quer encontrar todos os campos de evento correspondentes em um log JSONL sem carregar o log inteiro em um parser personalizado.
- Uma extensão de editor quer pular para uma seção ou item de lista em markdown por slug e então renderizar a linha exata para a qual ele foi resolvido.
- Um agente quer simular uma pequena edição no workspace antes de aplicá-la, com os bytes alterados visíveis na revisão.
openclaw path para edições comuns de arquivo inteiro, migrações
ricas de configuração ou escritas específicas de memória. Essas devem usar o comando
ou Plugin proprietário. path é para operações pequenas e endereçáveis em arquivos, quando um
comando de terminal repetível é mais claro que outro parser sob medida.
Como ele é usado
Leia um valor de um arquivo de configuração editado por humanos:--json quando um
chamador precisar de saída estruturada e --human quando uma pessoa estiver inspecionando o
resultado.
Como funciona
openclaw path faz quatro coisas:
- Analisa o endereço
oc://em slots: arquivo, seção, item, campo e sessão opcional. - Escolhe o adaptador de tipo de arquivo a partir da extensão do destino (
.md,.jsonc,.jsonl,.yaml,.yml,.lobstere aliases relacionados). - Resolve os slots contra a AST desse tipo de arquivo: cabeçalhos/itens de markdown, chaves de objeto/índices de array JSONC, registros de linha JSONL ou nós de mapa/sequência YAML.
- Para
set, emite bytes editados pelo mesmo adaptador para que as partes intocadas do arquivo mantenham comentários, quebras de linha e formatação próxima quando o tipo oferecer suporte.
resolve e set exigem um destino concreto. find é o verbo exploratório:
ele expande curingas, uniões, predicados e ordinais nas correspondências concretas
que você pode inspecionar antes de escolher uma para escrever.
Subcomandos
| Subcomando | Finalidade |
|---|---|
resolve <oc-path> | Imprime a correspondência concreta no caminho (ou “não encontrado”). |
find <pattern> | Enumera correspondências para um caminho com curinga / união / predicado. |
set <oc-path> <value> | Escreve uma folha ou destino de inserção em um caminho concreto. Suporta --dry-run. |
validate <oc-path> | Somente análise; imprime a decomposição estrutural (arquivo / seção / item / campo). |
emit <file> | Faz round-trip de um arquivo por parseXxx + emitXxx (diagnóstico de fidelidade de bytes). |
Flags globais
| Flag | Finalidade |
|---|---|
--cwd <dir> | Resolve o slot de arquivo contra este diretório (padrão: process.cwd()). |
--file <path> | Sobrescreve o caminho resolvido do slot de arquivo (acesso absoluto). |
--json | Força saída JSON (padrão quando stdout não é um TTY). |
--human | Força saída humana (padrão quando stdout é um TTY). |
--dry-run | (somente em set) imprime os bytes que seriam escritos sem escrever. |
--diff | (com set --dry-run) imprime um diff unificado em vez dos bytes completos. |
Sintaxe oc://
field exige item, e item exige section. Em todos os
quatro slots:
- Segmentos entre aspas —
"a/b.c"sobrevive a separadores/e.. O conteúdo é literal em bytes;"e\não são permitidos dentro das aspas. O slot de arquivo também reconhece aspas:oc://"skills/email-drafter"/Tools/$lasttrataskills/email-draftercomo um único caminho de arquivo. - Predicados —
[k=v],[k!=v],[k<v],[k<=v],[k>v],[k>=v]. Operações numéricas exigem que ambos os lados sejam convertíveis para números finitos. - Uniões —
{a,b,c}corresponde a qualquer uma das alternativas. - Curingas —
*(subsegmento único) e**(zero ou mais, recursivo).findaceita estes;resolveesetos rejeitam como ambíguos. - Posicional —
$first/$lastresolvem para o primeiro / último índice ou chave declarada. - Ordinal —
#Npara a enésima correspondência por ordem do documento. - Marcadores de inserção —
+,+key,+nnnpara inserção com chave / indexada (use comset). - Escopo de sessão —
?session=cron-dailyetc. Ortogonal ao aninhamento de slots. Valores de sessão são brutos, não decodificados por porcentagem; eles não podem conter caracteres de controle nem delimitadores de consulta reservados (?,&,%).
?, &, %) fora de segmentos entre aspas, predicado ou união
são rejeitados. Caracteres de controle (U+0000-U+001F, U+007F) são rejeitados
em qualquer lugar, incluindo o valor de consulta session.
formatOcPath(parseOcPath(path)) === path é garantido para caminhos canônicos.
Parâmetros de consulta não canônicos são ignorados, exceto pelo primeiro valor
session= não vazio.
Endereçamento por tipo de arquivo
| Tipo | Modelo de endereçamento |
|---|---|
| Markdown | Seções H2 por slug, itens de lista por slug ou #N, frontmatter via [frontmatter]. |
| JSONC/JSON | Chaves de objeto e índices de array; pontos dividem subsegmentos aninhados, exceto quando entre aspas. |
| JSONL | Endereços de linha de nível superior (L1, L2, $first, $last), depois descida no estilo JSONC dentro da linha. |
| YAML/YML/.lobster | Chaves de mapa e índices de sequência; comentários e estilo de fluxo são tratados pela API de documento YAML. |
resolve retorna uma correspondência estruturada: root, node, leaf ou
insertion-point, com um número de linha baseado em 1. Valores folha são expostos como texto
mais um leafType para que autores de Plugin possam renderizar prévias sem depender
do formato da AST por tipo.
Contrato de mutação
set escreve um destino concreto:
- Valores de frontmatter em Markdown e campos de item
- key: valuesão folhas de string. Inserções em Markdown acrescentam seções, chaves de frontmatter ou itens de seção e renderizam uma forma markdown canônica para o arquivo alterado. - Escritas de folhas JSONC convertem o valor de string para o tipo de folha existente
(
string,numberfinito,true/falseounull). Use--value-jsonquando uma substituição de folha JSONC/JSON/JSONL deve analisar<value>como JSON e pode mudar de formato, como substituir um atalho SecretRef em string por um objeto. Inserções em objetos e arrays JSONC analisam<value>como JSON e usam o caminho de edição dejsonc-parserpara escritas comuns de folhas, preservando comentários e formatação próxima. - Escritas de folhas JSONL convertem como JSONC dentro de uma linha. Substituição de linha inteira e
acréscimo analisam
<value>como JSON. JSONL renderizado preserva a convenção dominante de quebra de linha LF/CRLF do arquivo. - Escritas de folhas YAML convertem para o tipo escalar existente (
string,numberfinito,true/falseounull). Inserções YAML usam a API de documento do pacoteyamlincluído para atualizações de mapa/sequência. Documentos YAML malformados com erros de parser são recusados antes da mutação comparse-error.
--dry-run antes de escritas visíveis ao usuário quando os bytes exatos importarem. O
substrato preserva saída idêntica em bytes para round-trips de análise/emissão, mas uma
mutação pode canonicalizar a região editada ou o arquivo dependendo do tipo.
Adicione --diff quando quiser a prévia como um patch antes/depois focado em vez
do arquivo renderizado completo.
Exemplos
Receitas por tipo de arquivo
Os mesmos cinco verbos funcionam em todos os tipos; o esquema de endereçamento despacha com base na extensão do arquivo. Os exemplos abaixo usam os fixtures da descrição do PR.Markdown
[frontmatter] endereça o bloco de frontmatter YAML; tools
corresponde ao cabeçalho ## Tools via slug, e as folhas de itens mantêm sua forma de slug
mesmo quando a origem usa underscores (send_email → send-email).
JSONC
jsonc-parser, então comentários e espaços em branco sobrevivem a um
set. Execute primeiro com --dry-run para inspecionar os bytes antes de confirmar.
JSONL
[event=action]) quando você não
souber o número da linha, ou pelo segmento canônico LN quando souber.
YAML
Document do pacote yaml, em vez de um parser feito à mão,
então ciclos comuns de parse/emissão preservam comentários e o formato de autoria, enquanto
os caminhos resolvidos usam o mesmo modelo de chave de mapa / índice de sequência do JSONC. O mesmo
adaptador lida com arquivos .yaml, .yml e .lobster.
Referência de subcomandos
resolve <oc-path>
Lê uma única folha ou nó. Wildcards são rejeitados — use find para eles.
Sai com 0 em uma correspondência, 1 em uma ausência limpa, 2 em um erro de parse ou padrão
recusado.
find <pattern>
Enumera cada correspondência para um padrão de wildcard / predicado / união. Sai com 0
em pelo menos uma correspondência, 1 em zero. Wildcards no slot de arquivo são rejeitados com
OC_PATH_FILE_WILDCARD_UNSUPPORTED — passe um arquivo concreto (globbing de múltiplos arquivos
é um recurso futuro).
set <oc-path> <value>
Escreve uma folha. Combine com --dry-run para visualizar os bytes que seriam
gravados sem tocar no arquivo. Adicione --diff para uma prévia de diff unificado.
Sai com 0 em uma gravação bem-sucedida, 1 se o substrato recusar (por exemplo, um
sentinel guard atingido), 2 em erros de parse.
+key cria o filho nomeado se ele ainda não
existir; +nnn e + simples funcionam para inserção indexada e anexação, respectivamente.
validate <oc-path>
Verificação somente de parse. Sem acesso ao sistema de arquivos. Útil quando você quer confirmar que um
caminho de template está bem formado antes de substituir variáveis, ou quando quer
a decomposição estrutural para depuração:
0 quando válido, 1 quando inválido (com code e
message estruturados), 2 em erros de argumentos.
emit <file>
Faz round-trip de um arquivo pelo parser e emissor por tipo. A saída deve
ser idêntica em bytes à entrada em um arquivo válido — divergência indica um
bug de parser ou um sentinel atingido. Útil para depurar o comportamento do substrato em
entradas do mundo real.
Códigos de saída
| Código | Significado |
|---|---|
0 | Sucesso. (resolve / find: pelo menos uma correspondência. set: gravação bem-sucedida.) |
1 | Nenhuma correspondência, ou set rejeitado pelo substrato (sem erro em nível de sistema). |
2 | Erro de argumento ou parse. |
Modo de saída
openclaw path reconhece TTY: saída legível por humanos em um terminal, JSON quando
stdout é encadeado por pipe ou redirecionado. --json e --human substituem a
detecção automática.
Observações
setgrava bytes pelo caminho de emissão do substrato, que aplica o redaction-sentinel guard automaticamente. Uma folha que carrega__OPENCLAW_REDACTED__(literalmente ou como substring) é recusada no momento da gravação.- O parse de JSONC e as edições de folhas usam a dependência local do Plugin
jsonc-parser, então comentários e formatação são preservados em gravações comuns de folhas, em vez de passar por um caminho de parser/re-renderização feito à mão. pathnão sabe sobre LKG. Se o arquivo for rastreado por LKG, a próxima chamada observe decide se promove / recupera.set --batchpara multi-set atômico pelo ciclo de vida de promoção/recuperação do LKG está planejado junto com o substrato de recuperação de LKG.