OpenClaw Obsidian Integration — AI Agent for Your Knowledge Base

What Is Obsidian?

Obsidian is a popular knowledge management tool built around plain Markdown files stored locally on your device. It is local-first — your notes are just .md files in a folder, which makes Obsidian easy to back up, version with git, and integrate with other tools.

Wikilinks, backlinks, tags, frontmatter, and the graph view make Obsidian a favorite for researchers, developers, writers, and anyone who keeps a long-running personal wiki.

Why Connect OpenClaw to Obsidian?

A vault with hundreds or thousands of notes is hard to search by hand. By giving your OpenClaw agent access to it, you can:

• Search and read notes — ask in natural language, get answers drawn from your vault
• Create new notes from chat — meeting summaries, daily logs, quick captures
• Summarize long notes or whole folders into key takeaways
• Find connections between notes you forgot were related
• Append to daily notes from any messaging channel your bot is on

Quickstart on OpenClaw Launch

The fastest path: install the Obsidian skill from the dashboard — the bot will create and manage a vault for you inside its container, no configuration needed.

1. Open /dashboard/skills, search obsidian, and install the Obsidian skill. The skill covers both vault design (folders, templates, plugin recommendations) and day-to-day operation (search, read, write, sync), so a single install gets you the full workflow.
2. Message your bot: “add a note titled Hello to my vault”. On first use the bot creates ~/.openclaw/workspace/obsidian-vault, writes the note, and confirms.
3. From then on, ask the bot to search, read, list recent notes, or add new ones in plain language.

The vault lives at ~/.openclaw/workspace/obsidian-vault inside your instance. You don't need to configure a path — the skill handles it.

I Already Have a Vault on My Desktop

If you keep notes in Obsidian on your laptop and want your bot to read (and optionally write to) the same vault, you need a sync layer. Four options, ordered by how most people end up using them:

Option A: Obsidian Headless Sync (Official, Paid)

In February 2026 Obsidian released obsidian-headless, an official command-line client for Obsidian Sync. It runs as a background daemon on your bot, syncs notes, settings, and plugins end-to-end encrypted, and stays in perfect agreement with the Obsidian apps on your laptop, phone, and tablet. Best fidelity if you already pay (or are willing to pay) for Obsidian Sync.

On your bot (one-time setup):

1. Tell your bot: “Install obsidian-headless globally with npm, then log in to my Obsidian account.” The bot runs npm install -g obsidian-headless and then ob login — you complete the device-code flow in a browser on your laptop.
2. Pick the vault to sync: ob sync-list-remote shows your remote vaults, then ob sync-setup --vault "<name>" --path ~/.openclaw/workspace/obsidian-vault binds it.
3. Run continuous sync: ob sync --path ~/.openclaw/workspace/obsidian-vault --continuous. Ask the bot to start it with nohup or via the cron-helper skill so it stays running after the chat ends.

Pros: official, real-time, encrypted, syncs settings and community plugins (not just notes), no git or cloud account needed. Cons: requires an active Obsidian Sync subscription, the daemon must stay alive, and image upgrades on hosted instances will reinstall it — ask the bot to re-run the setup once after any major upgrade.

Option B: Obsidian Git (Free, Recommended)

Your vault lives in a private GitHub repo. The bot creates the repo and pushes a seed commit; your desktop Obsidian clones it and auto-syncs from there. Free, two-way, works on desktop and mobile, no cloud subscription required.

On your bot — Terminal for login, chat for everything else:

1. Open /dashboard/skills and install the GitHub skill. This teaches the bot the right pattern for gh commands — it does not install the binary itself. Tell your bot in chat: “Install the GitHub CLI globally.”
2. Open your instance card on /dashboard, click the Terminal button, and run:

   gh auth login        # GitHub.com → HTTPS → Login with a web browser

   Copy the 8-character code, open github.com/login/device in your browser, paste it, and authorize. When the Terminal prints “Logged in as <you>” you can close it — this is the only step that needs an interactive shell.
3. Back in chat, ask the bot: “Set up git sync for my Obsidian vault into a new private repo called my-vault.” The bot reuses the gh auth from the Terminal step and does everything — gh repo create, clone into ~/.openclaw/workspace/obsidian-vault, set your git config, push the seed commit, install the 5-minute pull cron, and drop a small .bot/sync-push.sh helper that commits and pushes (under a flock) the instant any tool call writes to the vault — with an hourly fallback cron in case a push gets killed mid-flight by an image upgrade or restart. Two-way sync is the default; ask for pull-only if you don't want the bot to push back.

Already have a repo? Just paste the clone URL into chat and ask the bot to use it — it will back up the existing ~/.openclaw/workspace/obsidian-vault, clone the repo in its place, and confirm the contents in one turn.

Why split it like that? gh auth login's browser-based device flow is interactive: it shows a menu and waits for you to paste a code. The bot's chat exec is non-interactive, so it would hang. Once the login has written its credential file, every other gh command (gh repo create, gh repo clone, etc.) is a single non-interactive call — the bot can handle all of those from chat.

Bot says “not authenticated” right after Terminal login? Wait 10–15 seconds and ask the bot to retry. The CLI prints “Logged in as…” before it has finished writing ~/.config/gh/hosts.ymlto disk, so a chat command fired immediately after can read stale state.

On your desktop — point Obsidian at the repo the bot created:

Heads up on the vault folder: Obsidian treats whatever folder you opened as a vault, and Obsidian Git will sync everything in it. Don't point this at a code project (a Next.js app, a monorepo, etc.) — you'll push secrets, build output, and node_modules straight to GitHub. Use a dedicated notes folder like ~/Documents/MyVault.

1. Clone the repo to your Mac. The cleanest way is via GitHub CLI (it handles auth without you copying tokens around):

   brew install gh                       # if you don't already have it
   gh auth login                         # one-time device-code flow
   gh repo clone YOUR-GH-USERNAME/my-vault ~/Documents/MyVault

   Plain git clone https://… over HTTPS will fail with “Password authentication is not supported” — GitHub disabled that in 2021. If you'd rather avoid CLI entirely, install GitHub Desktop and clone from there — same result.
2. Open Obsidian: File → Open another vault → Open folder as vault → pick the freshly cloned ~/Documents/MyVault. You'll see the seed README.md the bot pushed.
3. Settings → Community plugins. On a fresh vault you'll see Obsidian's Restricted Mode page first — click Turn on community plugins to exit it. Then click Browse and search git. The plugin you want is the top result: Git by Vinzent (often called “Obsidian Git” in docs — same thing, ~2.4M downloads). Install and enable it. The plugin auto-detects the existing .git directory in the vault folder.
4. Open the plugin's settings and turn on these four:
   • Auto commit-and-sync interval (minutes) → set to 5 (in the Automatic section)
   • Pull on startup
   • Push on commit-and-sync
   • Pull on commit-and-sync
   Every 5 minutes the plugin will commit, pull, and push. Edits flow desktop → GitHub → bot, and bot → GitHub → desktop.

Option C: Remotely Save (Cloud Storage)

The Remotely Save community plugin syncs your vault to S3, Dropbox, Google Drive, OneDrive, WebDAV, or several other backends. The bot reads from the same backend. Easier than git if you already have one of those accounts.

1. Install Remotely Save in Obsidian and configure the backend of your choice.
2. Run an initial sync from the desktop so the cloud copy is populated.
3. On the bot side, give it credentials for the same backend and ask it to download the vault into ~/.openclaw/workspace/obsidian-vault on a schedule (cron + the matching CLI, e.g. aws s3 sync or rclone).

Option D: Obsidian Local REST API + Tunnel (Live Access)

The Obsidian Local REST API community plugin exposes your live vault over HTTP from your desktop. Pair it with a Cloudflare or Tailscale tunnel and your bot can call into the running Obsidian app directly — no sync delay, always fresh. Best fidelity, most setup, only works while your Obsidian app is open.

1. Obsidian → Settings → Community plugins → install Local REST API. Note the API key and port (default 27124).
2. Expose it to the internet via Cloudflare Tunnel or Tailscale Funnel — both give you an HTTPS URL without port forwarding.
3. Tell the bot to call the tunnel URL (with the API key as a header) when it needs to search or read notes. An MCP server such as cyanheads/obsidian-mcp-server does this cleanly if you prefer structured tools over raw HTTP.

What Your Agent Can Do

Once your vault is reachable, you can ask things like:

• “Search my vault for notes about machine learning.”
• “Summarize my research notes on quantum computing.”
• “Add a note titled ‘Meeting with X’ to Notes/ with these bullet points.”
• “Append today's tasks to my daily note.”
• “What overlaps between project-alpha and project-beta?”
• “Generate flashcards from my biology notes.”

The agent works with your existing folder structure, tags, and frontmatter — no reorganization required.

Troubleshooting

Bot says it has no vault path

On a hosted instance, the Obsidian skill defaults to ~/.openclaw/workspace/obsidian-vault and creates the directory on first use. If your bot still asks for a path, your installed skill is an older version — uninstall and reinstall it from /dashboard/skills.

Git pull fails with authentication error

• Run gh auth status in your bot. If it says you're logged out, ask the bot to re-run gh auth login and complete the device-code flow again on github.com.
• Confirm the GitHub account you authenticated with actually has access to the vault repo — the bot will quietly fail if you logged in as a different account than the one that owns it.

Bot says “GitHub skill installed: yes, gh CLI: not installed”

The GitHub skill ships the playbook the bot follows when you ask it to do GitHub things, but it does not bundle the gh binary itself. On a fresh container the binary is missing until you ask the bot to install it. Just say: “Install the GitHub CLI globally.”

Chat asked me to run gh auth login and went silent

gh auth login is interactive — it expects arrow-key menu input and a one-time code pasted back into a real terminal. Your bot's chat exec is non-interactive, so the command starts and then waits forever. Open the Terminal button on your instance card (/dashboard) instead and run gh auth login there — that's a real PTY and the device-code flow completes in a few seconds.

Tunnel returns 401

• The Local REST API plugin uses an API key, not a username/password. Send it as the Authorization: Bearer <key> header.
• Check the plugin is enabled and the desktop Obsidian app is actually running.

Notes look fine on desktop but the bot can't find them

• Confirm your sync layer actually ran — force a manual sync and inspect the contents inside the bot: “list everything under ~/.openclaw/workspace/obsidian-vault”.
• Hidden folders like .obsidian/ and .git/ are normal and safe to leave in place.

Self-Hosted OpenClaw

If you self-host OpenClaw on the same machine as your Obsidian app, you can skip the sync layer entirely — point an MCP filesystem server (or the Obsidian skill) at your existing vault directory directly. See our MCP guide and best MCP servers for the configuration snippets.

Frequently Asked Questions

Do I need an Obsidian Sync subscription?

No. Obsidian Git, Remotely Save, and the Local REST API plugin are all free community plugins. Obsidian Sync is optional — but if you do pay for it, the official obsidian-headless CLI (released February 2026) lets your bot run Sync as a background daemon and gives you the cleanest cross-device experience — notes, settings, and plugins all stay in lockstep with your laptop and phone.

Can the bot write to my vault?

Yes. The Obsidian skill can create notes, append, and update frontmatter. With git sync, the bot can also commit and push changes back to your repo, so notes it writes show up in your desktop Obsidian on the next pull.

Where does the vault live on a hosted instance?

At ~/.openclaw/workspace/obsidian-vault inside your container — the only directory that survives image upgrades. Older guides referenced ~/.obsidian-vault; that path still works as a compatibility symlink, so prompts and scripts using the short form keep functioning. If you want the vault on your laptop too, use one of the sync options above — a hosted bot can't reach into your local file system on its own.

Which sync method should I pick?

Pay for Obsidian Sync? Use the official headless client — fastest, encrypted, syncs settings and plugins too. Don't want a subscription? Obsidian Git is the best free option: durable, version-controlled, works on desktop and mobile. Remotely Save if you already use S3, Dropbox, or similar and don't want to deal with git. Local REST API + tunnel only if you specifically need live access with no sync delay and are comfortable exposing a service from your desktop.

Is my data private?

Notes inside ~/.openclaw/workspace/obsidian-vault live in your instance's persistent storage. With git sync, copies also live in your private GitHub repo. The AI model only sees note content the agent retrieves in response to your queries — not the whole vault. See Security for details on instance isolation.

What's Next?

• Skills — install the Obsidian skill in one click on your instance
• MCP Guide — how MCP servers work and when to use one
• Best MCP Servers — other servers worth pairing with your vault
• See pricing — deploy your Obsidian-connected agent starting at $3/month