Skip to content
Recaply.
Sign inSubmit a tool

LearnTutorials

ObsidianTutorialsOpen Obsidian

Share your OpenClaw workspace with Obsidian Sync

Sync your OpenClaw agent's workspace to Obsidian, then hand it tasks in a shared todo.md and read its JSON and HTML files, in about 30 minutes.

By Recaply EditorsAdvanced29 min6 stepsUpdated

A hand drops a sheet of paper into an open folder that stands between two empty desk trays

What you need

Obsidian Headless is in open beta. Never run it and the Obsidian app's Sync on the same machine, or files can conflict.

  1. Step 1: Back up the workspace

    3 min

    Sync copies every change both ways, so start from a saved copy you can roll back to.

    1. On the agent machine, open a terminal in the workspace. It's ~/.openclaw/workspace by default.
    2. Move any API keys, tokens or passwords out of the folder first. OpenClaw's docs say they don't belong there.
    3. Run the commands below to save the folder in a private git repo.
    Run this
    cd ~/.openclaw/workspace
git init
git add .
git commit -m "Before Obsidian Sync"

    You should see a commit that lists files such as AGENTS.md, SOUL.md and memory/.

    Git says there's nothing to commit?

    The folder is already a repo with no new changes, which is fine. Run git log to check that a recent commit is there.

    Obsidian Sync skips hidden folders such as .git, so your history stays on this machine.

  2. Step 2: Sync the workspace from the agent machine

    7 min

    Obsidian Headless syncs a folder without the desktop app, which suits a server that runs an agent.

    1. Install Obsidian Headless, then log in with your Obsidian account.
    2. Create an end-to-end encrypted remote vault and link the workspace to it.
    3. Add the unsupported file type, which covers files such as JSON and HTML, then start continuous sync.
    Run this on the agent machine
    npm install -g obsidian-headless
ob login
ob sync-create-remote --name "OpenClaw workspace" --encryption e2ee
ob sync-setup --vault "OpenClaw workspace" --path ~/.openclaw/workspace --device-name agent
ob sync-config --path ~/.openclaw/workspace --file-types image,audio,video,pdf,unsupported
ob sync --path ~/.openclaw/workspace --continuous

    You should see the first upload finish, then sync keep running and watching for changes.

    Sync stops when you close the terminal?

    Run ob sync --continuous in a session that survives logout, such as tmux, or set it up as a system service.

    You'll choose an encryption password. Keep it in a password manager, never in a file inside the vault.

  3. Step 3: Open the vault on your computer

    5 min

    Your computer becomes the second device, so you see the agent's files as they change.

    1. In Obsidian, create a new, empty vault. Connecting a vault that already has notes merges them.
    2. In Settings > General, log in. Then in Settings > Core plugins, turn on Sync.
    3. In Settings > Sync, click Choose next to Pick remote vault, then Connect on OpenClaw workspace. Enter its password.
    4. Before you start syncing, turn on Sync all other types under Selective sync.

    You should see AGENTS.md, SOUL.md and the memory folder in the file list, and Synced in the status bar.

    JSON or HTML files are missing?

    Turn on Sync all other types in Settings > Sync, then restart Obsidian. Sync settings are set on each device.

  4. Step 4: Write USER.md and a shared to-do list

    6 min

    OpenClaw reads USER.md every session, and one shared list keeps every handoff in a single place.

    1. In Obsidian, open USER.md at the top of the vault, or create it. Add short rules like the ones below.
    2. Keep it under 4,000 characters. That's all OpenClaw loads from it each session.
    3. Create todo.md with three headings: ## For the agent, ## For me and ## Done.
    4. In AGENTS.md, add the line: Check todo.md at the start of every session.
    Your USER.md
    <!-- observed: [YYYY-MM-DD] | status: active -->

- Prefer short updates with the result first.

<!-- observed: [YYYY-MM-DD] | status: active -->

- Always write examples for [YOUR CUSTOMERS], who buy [WHAT YOU SELL].

<!-- observed: [YYYY-MM-DD] | status: active -->

- Never post or send anything outside the workspace without asking me.

    You should see both files in the vault, and Synced in the status bar a few seconds after you save.

    The agent ignores a rule you changed?

    Keep one active rule per preference. Mark the old entry superseded and edit the rule in place, instead of adding a second one.

  5. Step 5: Add viewers for JSON and HTML files

    3 min

    Agents often leave data files and dashboards, and Obsidian can't open those without help.

    1. In Settings > Community plugins, turn off Restricted mode, then click Browse.
    2. Search for Data Files Editor, click Install, then Enable. It opens .json, .txt and .xml files.
    3. Do the same for HTML Reader, which shows .html files as pages.

    You should see a JSON file opening as editable text, and an HTML dashboard showing as a page.

    JSON files still won't open?

    Only one plugin can own the .json extension. Turn off any other JSON plugin, such as JSON Editor, and restart Obsidian.

    For HTML from a source you don't trust, switch HTML Reader to Text Mode, its safest setting.

  6. Step 6: Hand off tasks on a schedule

    5 min

    A recurring job makes the agent check your list, so you don't have to message it for every task.

    1. On the agent machine, run the command below. It checks todo.md every 30 minutes between 08:00 and 22:00.
    2. In Obsidian, add a task under ## For the agent, such as a weekly analytics summary.
    3. Wait until the status bar says Synced, then leave the task to the agent.
    Run this on the agent machine
    openclaw automations add \
  --name "Todo check" \
  --every 30m \
  --session isolated \
  --message "Open todo.md. Do each unchecked task under For the agent, then tick it and add a one-line result. If none are open, reply NO_REPLY." \
  --active-hours-start 08:00 \
  --active-hours-end 22:00 \
  --active-hours-timezone user

    You should see the task ticked in todo.md within the hour, with the agent's result under it.

    Nothing changes after an hour?

    Run openclaw automations list to check the job and its next run. To test it now, run openclaw automations run with the job's ID.

You get

A shared Obsidian vault where you and your OpenClaw agent edit the same files and pass work through `todo.md`

Try next

Build an LLM wiki in Obsidian with Claude Code6 steps · 28 minMake a branded launch video with OpenClaw and Remotion6 steps · 50 minInstall agent skills in OpenCode6 steps · 5 min

Did this guide work for you?

Sources

0 of 6Next: Back up the workspace