OpenClaw Vault — Mac + iPhone Setup Runbook

Replaces the earlier obsidian-mac-laptop-setup.md (rclone-into-Sync), which Perplexity research proved is a documented anti-pattern. See feedback_obsidian_sync_external_changes_unreliable.md.

Architecture: VPS git repo → GitHub traewayrer/openclaw-vault (private) → Mac via Obsidian Git plugin → iPhone/iPad via Obsidian Sync (Mac is the bridge).

Plan: openclaw-obsidian-vault-2026-05-02.md

Time: ~30 min Mac (Phase 2 + 4), ~10 min iPhone (Phase 3). All on your devices.

State on VPS (already shipped): vault scaffolded, GitHub repo created + initial push, two systemd timers running:

openclaw-vault-sync.timer — every 15 min: rsync canonical → vault → commit → push
openclaw-vault-pull.timer — every 5 min: git pull (reverse flow for phone/Mac edits)

Phase 2 — Mac Bridge (~30 min)

2.1 Clone the repo

Open Terminal on your MacBook (macbooks-macbook-pro).

mkdir -p ~/Obsidian
cd ~/Obsidian
git clone https://github.com/traewayrer/openclaw-vault.git
cd openclaw-vault
ls

Expected output: AGENTS.md, CLAUDE.md, README.md, _index.md, logs/, memory/, personal/, plans/, sources/, wiki/.

If git clone fails with auth errors, you need to authenticate:

Either gh auth login (GitHub CLI — easiest), or
Generate SSH key and add to GitHub → git clone git@github.com:traewayrer/openclaw-vault.git instead.

2.2 Open in Obsidian

Launch Obsidian.
Open folder as vault → pick ~/Obsidian/openclaw-vault/
Trust the vault when prompted.

You’ll see README.md, CLAUDE.md, wiki/system-map/_mermaid-test.md, plans/ (91 plans), memory/, etc. in the left sidebar.

2.3 Verify Mermaid renders

Open wiki/system-map/_mermaid-test.md. Press cmd-E to enter Reading mode. You should see a rendered colored flow diagram (Internet → Cloudflare → Webhook Handlers → …). If you see raw graph TD text, you’re in Source mode — toggle with cmd-E.

2.4 Install community plugins

In Obsidian: Settings → Community plugins → Turn on community plugins → Browse.

Install (search the name, click Install, then Enable):

Plugin	Why
Obsidian Git	Pulls from GitHub every 5 min so I (Claude on VPS) can push updates and you see them automatically
Smart Connections	Local-embedding semantic search across your 91 plans + memory files; runs on-device, no API calls
Copilot for Obsidian	Claude API integration — ask AI questions about vault content using your Anthropic key
Local REST API	Exposes vault as HTTPS endpoints; needed for Phase 4 (MCP)

2.5 Configure Obsidian Git plugin

Settings → Obsidian Git:

Vault backup interval (minutes): 0 (disable auto-commit — VPS does the commits, not the Mac for now)
Auto pull on startup: ON
Auto pull interval (minutes): 5
Disable push: ON (Phase 5 — disabled until two-way is verified)
Pull updates on startup: ON

This makes the Mac a pure read-only follower of the VPS for now. Two-way comes in Phase 5 (re-enable push later after we verify single-direction works).

2.6 Configure Smart Connections

Settings → Smart Connections:

Embedding model: keep default (TaylorAI/bge-micro-v2 or similar — small, fast, on-device)
Wait ~5 min for initial indexing of your 91 plans + memory files. Status bar bottom-right shows progress.
Once done, in any note press cmd-P → “Smart Connections: Open” to see related notes.

2.7 Configure Copilot for Obsidian

Settings → Copilot:

Default Model: claude-opus-4-7 (or claude-sonnet-4-6 if you want cheaper)
API Provider: Anthropic
API Key: paste your Anthropic API key (from https://console.anthropic.com/)
Enable Vault QA: ON
Embedding model for Vault QA: local (Smart Connections handles this, or use Voyage)

Test it: open a note, cmd-P → “Copilot: Open Copilot Chat” → ask “summarize the OpenClaw Obsidian Vault plan.”

2.8 Enable Obsidian Sync on this vault

Critical: Settings → Sync → click “Choose remote vault”.

Create new remote vault → name it openclaw-vault
Encryption password: strong password (DIFFERENT from your Obsidian account password — this E2E encrypts the vault content). Save it in 1Password vault Aurora.
Click Continue.

In Sync settings, enable:

General: Sync deleted files, Sync .obsidian config (recommend OFF to avoid per-device state conflicts), Sync workspace.json (OFF)
Sync types: Markdown ✓, Images ✓, Audio (off unless needed), Video (off), PDFs ✓, Other (off)
Conflict resolution: “Create conflict file” ✓ ← do not skip this
Click “Start syncing”

Initial sync uploads vault to Obsidian’s servers. Should take ~30s for the current size.

2.9 Verify the pipeline end-to-end

Have me make a tiny change on VPS to prove the chain works:

(I’ll write a test file wiki/system-map/_pipeline-test-$(date).md)

Wait up to 15 min for next VPS sync, then up to 5 min for Obsidian Git pull on Mac. The file should appear. Tell me when you see it.

Phase 3 — iPhone (~10 min)

3.1 Install Obsidian on iPhone

App Store → search “Obsidian” → install. Free (the iOS app itself is free; Sync is the paid add-on you already bought).

Open Obsidian on iPhone.
Tap “Set up sync” (or Settings → Sync).
Log in with your Obsidian account email + password.
Pick remote vault openclaw-vault.
Enter encryption password from step 2.8.
Wait for sync to complete (~30-60s).

3.3 Configure iOS conflict resolution

iOS Settings → Sync:

Conflict resolution: “Create conflict file” ✓ ← MUST be on for both devices

3.4 Verify Mermaid renders on iPhone

Open wiki/system-map/_mermaid-test.md. Tap to enter Reading view (top-right icon). The diagram should render — colored boxes connected by arrows. Mobile rendering is slightly slower than desktop but works.

If text shows instead of diagram, you’re in Source view — toggle to Reading.

Phase 4 — MCP for claude.ai / Claude Desktop access (~30 min, OPTIONAL)

This lets Claude.ai (web) and Claude Desktop on Mac query your vault directly via MCP — useful for asking the LLM about your plans, memory, system state without copy-paste.

4.1 Generate API key in Local REST API plugin

In Obsidian on Mac: Settings → Community plugins → Local REST API → Settings.

Click “Generate new API key”
Note: HTTPS port (default 27124) and HTTP port (27123)
Copy the key, save in 1Password (vault Aurora, item obsidian-local-rest-api-mac)
Toggle “Enable HTTPS server” ON

4.2 Test the API works

Terminal on Mac:

curl -k -H "Authorization: Bearer <your-api-key>" \
  https://localhost:27124/vault/ | jq .

Should return JSON listing vault files.

4.3 Install the MCP server

Two options — pick one:

Option A — cyanheads/obsidian-mcp-server (most popular, simpler)

brew install node    # if you don't have it
npm install -g @cyanheads/obsidian-mcp-server

Option B — BoweyLou/obsidian-mcp-server-enhanced (Tailscale-fronted variant for remote claude.ai access)

git clone https://github.com/BoweyLou/obsidian-mcp-server-enhanced.git
cd obsidian-mcp-server-enhanced
npm install && npm run build

4.4 Add to Claude Desktop config

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (create if missing):

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "obsidian-mcp-server",
      "env": {
        "OBSIDIAN_API_KEY": "<your-api-key-from-step-4.1>",
        "OBSIDIAN_HOST": "localhost",
        "OBSIDIAN_PORT": "27124",
        "OBSIDIAN_USE_HTTPS": "true"
      }
    }
  }
}

Restart Claude Desktop.

4.5 Test from Claude Desktop

Open Claude Desktop. New conversation. Ask:

List the 5 most recent files in my Obsidian vault, and summarize what’s in plans/openclaw-obsidian-vault-2026-05-02.md.

If MCP is wired correctly, Claude reads the vault directly via the Local REST API and answers from real content. If you see “I don’t have access to your Obsidian vault,” check the config path and that Obsidian is running on Mac.

4.6 (Optional) Tailscale-front the MCP for claude.ai web access

If you want claude.ai (web) to query your vault from any device:

Install BoweyLou variant from §4.3 Option B.
Configure Tailscale Funnel to expose localhost:27124 at https://<mac-name>.tailb025a7.ts.net/obsidian/.
Add as remote MCP in claude.ai integrations.
Detailed steps: see BoweyLou/obsidian-mcp-server-enhanced README.

This is more involved — defer until you’ve used Claude Desktop MCP for a few days and confirmed you want it on web too.

Verification checklist after Phase 2 + 3

Mac vault opens cleanly in Obsidian
wiki/system-map/_mermaid-test.md renders the diagram on Mac
Smart Connections shows related notes when browsing plans
Copilot answers questions about a plan file
Obsidian Git plugin pulls every 5 min (check History tab in plugin)
Obsidian Sync uploaded vault successfully
iPhone has the same vault visible
iPhone renders Mermaid in _mermaid-test.md
“Create conflict file” enabled on both Mac and iPhone

After Phase 4 (optional):

Local REST API plugin running with HTTPS on port 27124
curl test returns vault file list
Claude Desktop connected via MCP
Claude Desktop can read vault file contents

Troubleshooting

Symptom	Cause	Fix
`git clone` auth failure	Mac doesn’t have GitHub auth	`gh auth login` then retry
Mermaid shows as raw text	Wrong view mode	`cmd-E` to toggle Reading mode
Obsidian Git “config error”	Plugin couldn’t find git binary	`brew install git` then retry
Smart Connections stuck on “indexing”	Initial pass is slow on first run	Wait — it does ~10 files/sec, full pass ~3 min for 91 plans + 120 memory files
Copilot returns API error	Wrong key or rate limit	Verify key at console.anthropic.com → Settings → API Keys
iPhone vault is empty	Sync didn’t complete	Force pull: Settings → Sync → tap remote vault name → “Re-download”
Conflict files appearing	Two devices edited offline	Open conflict file, manually merge, delete the (Conflict from X).md version
MCP “no tools available”	Claude Desktop didn’t load config	Quit Claude completely, reopen; check `~/Library/Logs/Claude/` for errors

When something goes wrong

Check VPS-side first: ssh opsadmin@100.85.89.1 'systemctl --user status openclaw-vault-sync.timer openclaw-vault-pull.timer'
Then Mac-side: Obsidian Settings → Obsidian Git → “View source control”
Then Sync: Settings → Sync → “View sync log”
Tell me what you see and I’ll debug.

Reference: file paths cheat-sheet

Mac:
~/Obsidian/openclaw-vault/                                          # vault root
~/Library/Application Support/Claude/claude_desktop_config.json     # MCP config
~/Library/Logs/Claude/                                               # Claude Desktop logs

VPS (do not edit these from Mac — they sync via git):
/home/opsadmin/openclaw-vault/                                      # canonical vault
/home/opsadmin/.openclaw/tools/openclaw-vault-{sync,pull}.sh        # sync scripts
/home/opsadmin/.openclaw/logs/openclaw-vault-{sync,pull}.log        # logs
/home/opsadmin/.config/systemd/user/openclaw-vault-*.{service,timer} # systemd units

GitHub:
https://github.com/traewayrer/openclaw-vault   (private)

Quartz 4

Explorer

obsidian-vault-setup

OpenClaw Vault — Mac + iPhone Setup Runbook

Phase 2 — Mac Bridge (~30 min)

2.1 Clone the repo

2.2 Open in Obsidian

2.3 Verify Mermaid renders

2.4 Install community plugins

2.5 Configure Obsidian Git plugin

2.6 Configure Smart Connections

2.7 Configure Copilot for Obsidian

2.8 Enable Obsidian Sync on this vault

2.9 Verify the pipeline end-to-end

Phase 3 — iPhone (~10 min)

3.1 Install Obsidian on iPhone

3.3 Configure iOS conflict resolution

3.4 Verify Mermaid renders on iPhone

Phase 4 — MCP for claude.ai / Claude Desktop access (~30 min, OPTIONAL)

4.1 Generate API key in Local REST API plugin

4.2 Test the API works

4.3 Install the MCP server

4.4 Add to Claude Desktop config

4.5 Test from Claude Desktop

4.6 (Optional) Tailscale-front the MCP for claude.ai web access

Verification checklist after Phase 2 + 3

Troubleshooting

When something goes wrong

Reference: file paths cheat-sheet

Graph View

Table of Contents

Backlinks

Quartz 4

Explorer

obsidian-vault-setup

OpenClaw Vault — Mac + iPhone Setup Runbook

Phase 2 — Mac Bridge (~30 min)

2.1 Clone the repo

2.2 Open in Obsidian

2.3 Verify Mermaid renders

2.4 Install community plugins

2.5 Configure Obsidian Git plugin

2.6 Configure Smart Connections

2.7 Configure Copilot for Obsidian

2.8 Enable Obsidian Sync on this vault

2.9 Verify the pipeline end-to-end

Phase 3 — iPhone (~10 min)

3.1 Install Obsidian on iPhone

3.2 Sign in to Obsidian Sync

3.3 Configure iOS conflict resolution

3.4 Verify Mermaid renders on iPhone

Phase 4 — MCP for claude.ai / Claude Desktop access (~30 min, OPTIONAL)

4.1 Generate API key in Local REST API plugin

4.2 Test the API works

4.3 Install the MCP server

4.4 Add to Claude Desktop config

4.5 Test from Claude Desktop

4.6 (Optional) Tailscale-front the MCP for claude.ai web access

Verification checklist after Phase 2 + 3

Troubleshooting

When something goes wrong

Reference: file paths cheat-sheet

Graph View

Table of Contents

Backlinks