Obsidian Vault Integration
Integrates OpenClaw agents with an Obsidian vault for shared knowledge management. Supports structured reading of task lists, milestones, team info, and safe writes back to vault files.
Configuration
Set the vault path via environment variable OBSIDIAN_VAULT_PATH. If not set, uses the default path noted in AGENTS.md.
Environment variables used:
- -
OBSIDIAN_VAULT_PATH — Path to the Obsidian vault directory (optional, defaults to agent's configured path)
Quick Start
Read tasks from vault
CODEBLOCK0
Returns JSON array of tasks parsed from checkbox items, with priority (critical/important/nice), status (todo/done), owner, and title.
Add a task to the vault
CODEBLOCK1
Mark a task done
CODEBLOCK2
File Discovery
Files are discovered by their frontmatter type: field as the primary method. If a file is moved to a subfolder, it's still found by metadata.
CODEBLOCK3
Fallback chain:
- 1. Frontmatter
type: field (most reliable — survives moves) - Filename pattern matching (e.g.,
*open-questions*) - Full-text search (slowest, last resort)
See references/file-formats.md for parsing rules per file type.
Error Handling
| Code | Meaning | Recovery |
|---|
| ERRVAULTNOTFOUND | Vault path doesn't exist | Check OBSIDIANVAULTPATH or AGENTS.md |
| ERRFILENOTFOUND |
Requested file not found | Run discovery to find by metadata |
| ERR
PARSEFAILED | Malformed markdown | Return partial data with warning |
| ERR_CONFLICT | File changed since last read | Re-read, resolve manually |
Safety
- - All writes are logged to
<vault>/.vault-audit.log (timestamp, agent, file, action) - Timestamp check prevents overwrites when file has changed
- Solo mode (default): all agents can read/write everything
- Team mode (v2): per-agent folder permissions
Permissions
Solo mode (default): No config needed. All agents have full read/write access.
Team mode (v2, not yet implemented): Optional permissions block in SKILL.md for folder-level access control per agent.
Scripts
- -
vault-read.py — Read and parse vault files into structured JSON - INLINECODE8 — Write updates back to vault files with safety checks
References
- -
references/file-formats.md — Parsing rules for each file type
Obsidian 知识库集成
将 OpenClaw 智能体与 Obsidian 知识库集成，实现共享知识管理。支持结构化读取任务列表、里程碑、团队信息，并安全写回知识库文件。
配置
通过环境变量 OBSIDIANVAULTPATH 设置知识库路径。若未设置，则使用 AGENTS.md 中记录的默认路径。
使用的环境变量：
- - OBSIDIANVAULTPATH — Obsidian 知识库目录路径（可选，默认为智能体配置路径）
快速开始
从知识库读取任务
bash
python scripts/vault-read.py <知识库路径> --file open-questions.md --format json
返回从复选框项解析出的任务 JSON 数组，包含优先级（critical/important/nice）、状态（todo/done）、负责人和标题。
向知识库添加任务
bash
python scripts/vault-write.py <知识库路径> --file open-questions.md --action add-task --title 新任务 --priority important --owner Dave
标记任务完成
bash
python scripts/vault-write.py <知识库路径> --file open-questions.md --action mark-done --task-id 3
文件发现
主要通过文件前置元数据的 type: 字段发现文件。即使文件移动到子文件夹，仍可通过元数据找到。
yaml
type: open-questions
status: active
回退链：
- 1. 前置元数据 type: 字段（最可靠——移动后仍有效）
- 文件名模式匹配（例如 open-questions）
- 全文搜索（最慢，最后手段）
各文件类型的解析规则见 references/file-formats.md。
错误处理
| 错误码 | 含义 | 恢复方法 |
|---|
| ERRVAULTNOTFOUND | 知识库路径不存在 | 检查 OBSIDIANVAULTPATH 或 AGENTS.md |
| ERRFILENOTFOUND |
请求的文件未找到 | 运行发现功能通过元数据查找 |
| ERR
PARSEFAILED | Markdown 格式错误 | 返回部分数据并附带警告 |
| ERR_CONFLICT | 自上次读取后文件已变更 | 重新读取，手动解决冲突 |
安全性
- - 所有写入操作均记录到 <知识库>/.vault-audit.log（时间戳、智能体、文件、操作）
- 时间戳检查防止文件变更后发生覆盖
- 单人模式（默认）：所有智能体可读写所有内容
- 团队模式（v2）：按智能体设置文件夹权限
权限
单人模式（默认）： 无需配置。所有智能体拥有完整读写权限。
团队模式（v2，尚未实现）： 在 SKILL.md 中可选权限块，用于按智能体设置文件夹级访问控制。
脚本
- - vault-read.py — 读取并解析知识库文件为结构化 JSON
- vault-write.py — 将更新安全写回知识库文件
参考
- - references/file-formats.md — 各文件类型的解析规则
