Plugin OC Path

O Plugin oc-path incluído adiciona a CLI openclaw path para o esquema de endereçamento de arquivos do espaço de trabalho oc://. Ele é distribuído no repositório do OpenClaw em extensions/oc-path/, mas é opcional: a instalação/compilação o deixa inativo até que você o habilite.

Os endereços oc:// apontam para uma única folha (ou um conjunto de folhas definido por curinga) dentro de um arquivo do espaço de trabalho. O Plugin reconhece quatro tipos de arquivo:

• markdown (.md): frontmatter, seções, itens, campos
• jsonc (.jsonc, .json): comentários e formatação preservados
• jsonl (.jsonl, .ndjson): registros orientados a linhas
• yaml (.yaml, .yml, .lobster): nós de mapa/sequência/escalar por meio da API Document do pacote yaml

Quem hospeda a própria instância e as extensões de editor usam a CLI para ler ou gravar uma única folha sem criar scripts diretamente com o SDK; agentes e hooks a tratam como uma base determinística, para que as operações de ida e volta com fidelidade de bytes e a proteção por sentinela de redação sejam aplicadas uniformemente a todos os tipos. Consulte a referência da CLI para ver a gramática completa, a lista de opções por verbo e exemplos práticos para cada tipo de arquivo; esta página explica por que e como habilitar o Plugin.

Por que habilitá-lo

Habilite o oc-path quando scripts, hooks ou ferramentas de agente locais precisarem apontar para uma parte específica do estado do espaço de trabalho sem um analisador personalizado para cada formato de arquivo. Um único endereço oc:// pode identificar uma chave de frontmatter Markdown, um item de seção, uma folha de configuração JSONC, um campo de evento JSONL ou uma etapa de fluxo de trabalho YAML.

Isso é importante para fluxos de trabalho de manutenção nos quais a alteração deve permanecer pequena, auditável e repetível: inspecionar um valor, localizar registros correspondentes, simular uma gravação e, em seguida, aplicar somente essa folha, sem alterar comentários, finais de linha ou a formatação próxima.

Motivos comuns para habilitá-lo:

• Automação local: scripts de shell resolvem ou atualizam um valor do espaço de trabalho com openclaw path … --json, em vez de manter códigos de análise separados para Markdown, JSONC, JSONL e YAML.
• Edições visíveis para agentes: um agente mostra um diff de simulação para uma folha endereçada antes da gravação, o que é mais fácil de revisar do que uma reescrita livre do arquivo.
• Integrações com editores: um editor mapeia oc://AGENTS.md/tools/gh para o nó Markdown e o número de linha exatos, sem fazer suposições com base no texto do título.
• Diagnóstico: emit faz uma operação de ida e volta do arquivo pelo analisador e pelo emissor, permitindo verificar se um tipo de arquivo mantém estabilidade de bytes antes de depender de edições automatizadas.

# O Plugin do GitHub está habilitado nesta configuração?openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --json # Quais nomes de chamadas de ferramenta aparecem neste log de sessão?openclaw path find 'oc://session.jsonl/[event=tool_call]/name' --json # Quais bytes esta pequena edição de configuração gravaria?openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run

O oc-path intencionalmente não é responsável pela semântica de nível superior. Os Plugins de memória continuam responsáveis pelas gravações de memória, os comandos de configuração continuam responsáveis pelo gerenciamento completo da configuração e a recuperação da última configuração válida (LKG) continua responsável pela restauração/promoção. O oc-path é a camada restrita de endereçamento e de operações de arquivo com preservação de bytes em torno da qual essas ferramentas de nível superior podem ser desenvolvidas.

Onde ele é executado

O Plugin é executado no mesmo processo da CLI openclaw, no host em que você invoca o comando. Ele não precisa de um Gateway em execução e não abre nenhum soquete de rede; cada verbo é uma transformação pura sobre um arquivo indicado por você.

Os metadados do Plugin ficam em extensions/oc-path/openclaw.plugin.json:

{  "id": "oc-path",  "name": "OC Path",  "activation": {    "onStartup": false,    "onCommands": ["path"]  },  "commandAliases": [{ "name": "path", "kind": "cli" }]}

onStartup: false mantém o Plugin fora do caminho de inicialização do Gateway. commandAliases e activation.onCommands instruem a CLI a carregar o Plugin sob demanda na primeira vez que você executa openclaw path …, portanto, instalações que nunca usam o verbo não têm custo adicional.

Habilitar

openclaw plugins enable oc-path

Reinicie o Gateway (se você executar um) para que o snapshot do manifesto reconheça o novo estado. As invocações diretas de openclaw path funcionam imediatamente no mesmo host; a CLI carrega o Plugin sob demanda.

Desabilite com:

openclaw plugins disable oc-path

Dependências

Todas as dependências de análise são locais ao Plugin; habilitar o oc-path não adiciona novos pacotes ao runtime principal:

O JSONL continua sendo implementado manualmente: a análise orientada a linhas é mais simples do que qualquer dependência, e a análise de cada linha já passa pelo jsonc-parser.

O que ele oferece

Atualmente, a CLI é a única superfície pública. Os verbos da base são privados do Plugin; os consumidores usam a CLI (ou desenvolvem seu próprio Plugin com o SDK).

Relação com outros Plugins

• memory-*: as gravações de memória passam pelos Plugins de memória, não pelo oc-path. O oc-path é uma base genérica para arquivos; os Plugins de memória adicionam sua própria semântica sobre ela.
• LKG: path não conhece a restauração da última configuração válida. Se um arquivo editado por meio de path também for acompanhado pelo LKG, o próximo ciclo de observação da configuração decidirá se ele deve ser promovido ou recuperado; trate uma edição feita por path da mesma forma que qualquer outra gravação direta nesse arquivo.

Segurança

set grava bytes brutos por meio do caminho de emissão da base, que aplica automaticamente a proteção por sentinela de redação. Uma folha que contenha __OPENCLAW_REDACTED__ (literalmente ou como substring) é recusada no momento da gravação com OC_EMIT_SENTINEL. A CLI também remove a sentinela literal de toda saída legível por humanos ou em JSON que ela imprime, substituindo-a por [REDACTED], para que capturas de terminal e pipelines nunca exponham o marcador.

Relacionados

• Referência da CLI openclaw path
• Gerenciar Plugins
• Desenvolvimento de Plugins