Obsidian Skill

Access and search your local Obsidian vault.

Vault Location

The vault lives at ~/.openclaw/workspace/obsidian-vault — inside the only persistent path on the instance, so it survives every container upgrade.

For backward compatibility, ~/.obsidian-vault is a symlink to the real vault. Either path works in commands and prompts.

First-Time Setup

Run this idempotent block before any sync method, and again after any image upgrade where the symlink is missing:

VAULT="$HOME/.openclaw/workspace/obsidian-vault"
LEGACY="$HOME/.obsidian-vault"

# Migrate a pre-1.3.0 vault that lived in the non-persistent legacy path
if [ -d "$LEGACY" ] && [ ! -L "$LEGACY" ] && [ ! -e "$VAULT" ]; then
  mv "$LEGACY" "$VAULT"
fi

mkdir -p "$VAULT"
ln -snf "$VAULT" "$LEGACY"

Vault Design (Optional)

After the directory exists, ask the user whether they want help designing the vault's structure. This is interactive — don't impose a layout without asking.

Ask first:

• What will the vault be used for? (research, writing, daily journaling, project notes, general knowledge base)
• Their experience level with Obsidian
• Any existing folders or tag conventions to preserve

A minimal default most users find useful (customize per use case):

VAULT="$HOME/.openclaw/workspace/obsidian-vault"
mkdir -p "$VAULT/Notes" "$VAULT/Daily" "$VAULT/Templates" "$VAULT/Archive"

Customize: academic research vaults often add Literature/ and Sources/; writing vaults use Drafts/ and Published/; PKM vaults sometimes split by MOCs/ (maps of content) and Topics/.

Recommend desktop community plugins by workflow (the bot does NOT install desktop Obsidian plugins — the user installs them in their desktop Obsidian app):

• Daily journaling: Templater, Calendar, Periodic Notes
• Research: Citations, Annotator, Excalidraw
• Writing: Longform, Linter
• Sync: Obsidian Git or Remotely Save (see sync section below)

A reasonable daily-note template (write to Templates/Daily.md):

# {{date:YYYY-MM-DD}}

## Focus


## Notes


## Tomorrow

Design guidelines:

• Start with a minimal folder structure that can grow organically — refactoring later is cheap.
• Use frontmatter (tags:, status:, project:) for metadata the bot can filter on later.
• Wikilinks ([[note]]) build the graph; encourage linking liberally.
• Don't over-engineer.

Sync Your Vault Across Devices

Pick ONE sync method when the user asks to keep it in sync with their laptop or phone. Ask which they prefer if they don't say.

Method 1: Obsidian Headless Sync (paid, official, best fidelity)

Use when the user has an Obsidian Sync subscription. Syncs notes, settings, and plugins. Requires Node 22+ (already present).

npm install -g obsidian-headless
ob login                                  # device-code flow; user opens URL on their laptop
ob sync-list-remote                       # show their remote vaults; let user pick one
ob sync-setup --vault "<vault-name>" --path "$HOME/.openclaw/workspace/obsidian-vault"
nohup ob sync --path "$HOME/.openclaw/workspace/obsidian-vault" --continuous > "$HOME/.openclaw/workspace/obsidian-vault/.sync.log" 2>&1 &

obsidian-headless is a global npm install in the image layer; after an image upgrade, re-run npm install -g obsidian-headless once.

Method 2: Obsidian Git (free, recommended for free users)

Use when the user wants free sync via a private GitHub repo. They must install the "Obsidian Git" community plugin on their desktop and push to a private repo first.

VAULT="$HOME/.openclaw/workspace/obsidian-vault"
LEGACY="$HOME/.obsidian-vault"

# If the persistent path already has a non-git directory, archive it first.
if [ -d "$VAULT" ] && [ ! -d "$VAULT/.git" ]; then
  mv "$VAULT" "$VAULT.bak.$(date +%s)"
fi
git clone https://<github_pat>@github.com/<user>/<repo>.git "$VAULT"
cd "$VAULT"
git config user.email "<[email protected]>"
git config user.name "<User Name>"

# Always recreate the legacy symlink so older prompts still work
ln -snf "$VAULT" "$LEGACY"

# Pull every 5 minutes:
( crontab -l 2>/dev/null; echo "*/5 * * * * cd $VAULT && git pull --rebase --autostash >> $VAULT/.gitsync.log 2>&1" ) | crontab -

Push Back to GitHub (when the bot writes notes)

Push runs immediately after each Obsidian-skill tool call that mutates the vault — no cron-only delay. Install a small helper script once:

VAULT="$HOME/.openclaw/workspace/obsidian-vault"
mkdir -p "$VAULT/.bot"
cat > "$VAULT/.bot/sync-push.sh" <<'EOF'
#!/bin/sh
set -eu
VAULT="$HOME/.openclaw/workspace/obsidian-vault"
cd "$VAULT" 2>/dev/null || exit 0
git add -A
git diff --cached --quiet && exit 0
git commit -m "bot: ${1:-auto-commit}"
# flock -n: skip if another push is already in flight (background or cron)
flock -n "$VAULT/.git/.push.lock" git push >> "$VAULT/.gitsync.log" 2>&1 || true
EOF
chmod +x "$VAULT/.bot/sync-push.sh"

At the END of every mutating Obsidian tool call (write, append, update), invoke:

"$HOME/.openclaw/workspace/obsidian-vault/.bot/sync-push.sh" "<one-line summary of the change>" &
disown 2>/dev/null || true

The & puts it in the background so the bot doesn't block on network. flock -n inside the helper makes overlapping calls safe — they no-op instead of fighting over the index.

Keep an hourly safety-net cron in case a push was killed mid-flight (image upgrade, container restart, network blip):

( crontab -l 2>/dev/null; echo "0 * * * * $HOME/.openclaw/workspace/obsidian-vault/.bot/sync-push.sh hourly-retry" ) | crontab -

Configuration

Set the vault path: OBSIDIAN_VAULT_PATH=$HOME/.openclaw/workspace/obsidian-vault

Search Notes

# Search note titles
find "{vault_path}" -name "*.md" | xargs grep -l "{query}" 2>/dev/null | head -10

# Full-text search with context
grep -rn --include="*.md" -C 2 "{query}" "{vault_path}" | head -50

Read a Note

cat "{vault_path}/{note_name}.md"

Find Backlinks

# Find all notes that link to a given note
grep -rl --include="*.md" "\[\[{note_name}\]\]" "{vault_path}" | head -20

List Recent Notes

find "{vault_path}" -name "*.md" -type f -mtime -7 | sort | head -20

List Tags

grep -roh --include="*.md" "#[a-zA-Z0-9_-]\+" "{vault_path}" | sort | uniq -c | sort -rn | head -20

Guidelines

• Always verify the vault path exists before searching
• Respect the user's note organization — don't modify notes without permission
• When presenting search results, show note title and relevant context
• For large vaults, use targeted searches rather than listing everything
• Handle wikilinks ([[note]]) and tags (#tag) in Obsidian format
• Summarize relevant notes rather than dumping full content