🏛️ Arquitetura de Integração
A integração é direta: o OpenClaw acessa o vault via filesystem local. Sem banco de dados intermediário, sem embeddings, sem sincronização — apenas leitura e escrita de arquivos Markdown onde o Obsidian já os mantém.
🏛️ Fluxo de consulta completo
O LLM lê os arquivos Markdown diretamente. Nenhum processo de indexação vetorial necessário.
O agente sempre começa pelo index.md para encontrar as páginas relevantes antes de ler o conteúdo.
Leitura de arquivo local: <5ms. Gargalo real é o LLM, não o acesso ao vault.
📝 Configurando o SOUL.md para o Wiki
A seção knowledge_base do SOUL.md é onde você instrui o agente sobre a estrutura do vault — caminhos, como interpretar o index.md, limites de tokens e formato de resposta com citação de fonte.
## Fontes de Conhecimento
knowledge_base:
# Caminho absoluto do vault
vault_root: /home/user/vault/
# Índice de navegação
index_file: /home/user/vault/index.md
# Pasta de conhecimento compilado
wiki_path: /home/user/vault/wiki/
# Pasta para novos documentos
inbox_path: /home/user/vault/raw/inbox/
# Limite de tokens por consulta
max_context_tokens: 8000
# Formato de citação de fonte
cite_format: "Fonte: wiki/{filename}"
# Comportamento quando não encontrar
not_found_message: |
Não tenho essa informação registrada no wiki.
Deseja que eu adicione como tarefa de pesquisa?## Instruções de Consulta
Ao receber uma pergunta sobre o vault:
1. Leia /home/user/vault/index.md
2. Identifique as 2-3 páginas mais relevantes
3. Leia o conteúdo de cada página identificada
4. Sintetize uma resposta baseada APENAS
no conteúdo lido
5. Sempre cite a fonte no formato:
"Fonte: wiki/nome-da-pagina.md"
6. Se não encontrar, use not_found_message
7. NUNCA invente informações
Exemplos de consultas esperadas:
- "O que sei sobre Python async?"
- "O que decidimos sobre a arquitetura X?"
- "Quais são os projetos ativos?"Defina max_context_tokens conservadoramente no início (4000-8000). Se o agente tentar ler muitas páginas de uma vez, excede o contexto do LLM e a resposta piora. O index.md bem estruturado é o que permite selecionar poucas páginas com alta precisão.
🔐 Permissões de Leitura/Escrita
Permissões granulares e explícitas protegem o vault de acesso indevido. A regra de ouro: o agente tem acesso de leitura ao wiki/ e acesso de escrita apenas ao raw/inbox/ — nunca ao wiki/ diretamente.
🔐 Modelo de permissões do vault
## Permissões de Filesystem
skills:
- name: filesystem
permissions:
read:
- "/home/user/vault/wiki/"
- "/home/user/vault/index.md"
- "/home/user/vault/raw/inbox/" # para confirmar recebimento
write:
- "/home/user/vault/raw/inbox/" # ÚNICO diretório de escrita
deny:
- "/home/user/vault/SOUL.md" # proteger configuração
- "/home/user/vault/log.md" # proteger histórico
- "/home/user/vault/raw/" # bloquear raw/ geral
allowed_extensions:
- ".md"
- ".txt"
- ".pdf"
max_file_size: "10MB"
audit_log: true # registra todos os acessos💬 Primeiro Prompt via Telegram
O momento de verdade: sua primeira consulta ao vault via Telegram. Vamos acompanhar o fluxo completo de "o que sei sobre X?" até a resposta com fonte citada.
Simulação de conversa — primeira consulta
O que sei sobre Python async?
você · 14:23
Python Async — resumo do que você tem registrado:
Python async/await usa o event loop do asyncio para executar corrotinas concorrentemente sem threads. Você usa principalmente com FastAPI e httpx para requests HTTP não-bloqueantes.
Padrões que você documentou:
- • asyncio.gather() para paralelizar múltiplos awaits
- • async context managers com async with
- • Evitar misturar sync e async — usar run_in_executor quando necessário
📄 Fonte: wiki/python-async.md · wiki/fastapi-patterns.md
- 1. Telegram entrega mensagem ao WS Gateway
- 2. Orquestrador recebe e processa com SOUL.md
- 3. Skill filesystem lê index.md (~50ms)
- 4. LLM identifica páginas relevantes
- 5. Filesystem lê cada página selecionada
- 6. LLM sintetiza resposta com citação
- 7. Gateway envia para o Telegram
📥 Ingestão via Mensagem
O fluxo inverso: você envia um arquivo ou texto pelo celular → o agente salva em raw/inbox/ → dispara a ingestão → wiki/ atualizado. Zero fricção de captura.
Você envia o documento pelo Telegram
Pode ser texto livre, PDF anexado, ou URL. O agente aceita qualquer formato configurado em allowed_extensions.
OpenClaw salva em raw/inbox/
# Arquivo criado automaticamente:
# raw/inbox/2026-04-09_1423_telegram-upload.md
---
source: telegram
received_at: 2026-04-09T14:23:00
sender: user_id_123
original_filename: artigo-python.pdf
status: pending_ingestion
---
[conteúdo do documento aqui]Ingestão disparada (automática ou manual)
# Via skill exec — chama Claude Code
claude "ingerir raw/inbox/ → wiki/" --vault /home/user/vault
# Ou o agente responde confirmando e pergunta:
"📥 Documento salvo em raw/inbox/.
Deseja ingerir agora? (pode levar 2-3 min)"Confirmação de sucesso via Telegram
O agente notifica quando a ingestão termina: "✓ Ingestão concluída: 2 páginas criadas/atualizadas em wiki/. Páginas: python-async-advanced.md, asyncio-patterns.md"
✅ Testando a Integração
Uma integração não testada é uma integração que vai falhar em produção. Execute este checklist antes de usar o sistema no dia a dia.
# Verificar status do OpenClaw
curl http://localhost:3000/health
# Ver logs em tempo real
pm2 logs openclaw --lines 50
# Testar leitura de arquivo direto
curl http://localhost:3000/debug/read \
-d '{"path": "/vault/index.md"}'
# Ver audit log de filesystem
cat /home/user/vault/.openclaw-audit.log \
| tail -20
# Testar conexão Telegram
curl http://localhost:3000/debug/channels⚠️ Remova ou proteja os endpoints /debug em produção