Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
docs(open-knowledge): add OpenClaw integration guide (#2298)
mike-inkeep686b6f9da2f8
diff --git a/docs/content/integrations/meta.json b/docs/content/integrations/meta.jsonindex 146962d48..7509c42d9 100644--- a/docs/content/integrations/meta.json+++ b/docs/content/integrations/meta.json@@ -1,5 +1,5 @@{"title": "Integrations","icon": "LuPlug",- "pages": ["claude-code", "cursor", "codex", "opencode"]+ "pages": ["claude-code", "cursor", "codex", "opencode", "openclaw"]}diff --git a/docs/content/integrations/openclaw.mdx b/docs/content/integrations/openclaw.mdxnew file mode 100644index 000000000..3828602a2--- /dev/null+++ b/docs/content/integrations/openclaw.mdx@@ -0,0 +1,149 @@+---+title: OpenClaw+description: Use OpenKnowledge with OpenClaw agents over MCP.+---++OpenClaw is an agent gateway: it runs agents that connect to MCP servers. Register OpenKnowledge as one of those servers and every agent OpenClaw runs can read, search, and write your knowledge base through OK's tools — with full attribution, link-awareness, conflict-awareness, and a live browser preview. Inside an OK project, agents work markdown through those tools rather than native file access, so every edit stays attributed and previewable.++<Callout type="info">+ Unlike Cursor, Codex, and Claude Code, OpenClaw is **not** auto-detected by `ok init`. You register the OpenKnowledge MCP server in OpenClaw's own config — the JSON block below. `ok init` is still how you turn a folder into a knowledge base.+</Callout>++## Register the OpenKnowledge MCP server++Add the server to `~/.openclaw/openclaw.json` under `mcp.servers`, pointing `cwd` at the knowledge base you want agents to land in:++```jsonc+// ~/.openclaw/openclaw.json+{+ "mcp": {+ "servers": {+ "open-knowledge": {+ "command": "ok",+ "args": ["mcp"],+ "cwd": "/path/to/your/knowledge-base"+ }+ }+ }+}+```++OpenClaw can also register servers from the command line (`openclaw mcp add …`) — run `openclaw mcp add --help` for the flags on your build. The JSON block above is the path we've verified end to end.++<Callout type="warn">+ **`ok` may not be on OpenClaw's PATH.** OpenClaw's runtime shell often doesn't have `ok` on `PATH`, so `"command": "ok"` can fail to launch the server. If it does, point `command` at the absolute binary the installer drops — `~/.ok/bin/ok` on a standard install. A JSON config isn't shell-expanded, so write the path out in full rather than with `~`:++ ```jsonc+ "command": "/Users/<your-username>/.ok/bin/ok"+ ```+</Callout>++`cwd` is the default knowledge base the server targets, but you can override it per call: every OK tool accepts a `cwd` argument, so an agent can point at a different project (or a git worktree) without touching the config — pass it once and it sticks for that session.++## Reload++After editing the config, run `openclaw mcp reload` so active agents pick up the change. If your build needs a full gateway restart instead, restart it.++## Verify++Two complementary checks — the probe confirms the gateway can reach the server; the prompt confirms an agent can actually call its tools.++**Server-side** — confirm OpenClaw can launch the server and its tools enumerate:++```bash+openclaw mcp doctor --probe # -> open-knowledge: ok+openclaw mcp probe open-knowledge # -> open-knowledge: 19 tools+```++Unrelated config-health or plugin-version warnings for *other* servers don't block OpenKnowledge from probing.++**Agent-side** — open the project with an OpenClaw agent and ask:++<VerifyExec subject="OpenClaw" />++If the agent doesn't see the tool, run tool discovery — some runtimes lazy-load MCP tools and only surface them after a search, so absence from the initial list means "not discovered yet," not "not registered" — then `openclaw mcp reload`.++## Initialize a knowledge base++If the folder in `cwd` isn't an OK project yet, make it one:++```bash+ok init /path/to/your/knowledge-base+```++<Callout type="warn">+ **`ok init` resolves upward into an existing project.** Run inside a subdirectory of an existing OK project, `ok init` finds the *parent* project and refreshes that one — it does not create a nested project, and it writes no markdown in the subdirectory. To create a genuinely separate knowledge base, run `ok init` in a folder that sits **outside any existing `.ok` project tree**.+</Callout>++## Smoke test++A copy-pasteable, end-to-end check that proves the whole stack — not just "the server starts." Point an OpenClaw agent at a fresh knowledge base and have it run:++<Steps>++<Step>+### Discover the tools++If `mcp__open-knowledge__*` isn't in the agent's tool list, run tool discovery first — absence from the initial list means "not discovered yet," not "not registered."+</Step>++<Step>+### Read config, list the root++`config` (resolved OK config) and `exec("ls -A")` confirm the agent is pointed at the right project.+</Step>++<Step>+### Write a folder, a README, and a linked note++`write` a `notes` folder, a `README`, and a note that links to a second doc you'll create. A forward link to a not-yet-created target comes back as a broken-link warning — expected when you're about to create it.+</Step>++<Step>+### Read them back++`exec("cat …")` on both docs returns content plus frontmatter, backlinks, and history that plain `cat` can't.+</Step>++<Step>+### Audit links, then search++`links({ kind: "dead" })` should return `[]` once every target exists; `search({ query })` should find the new docs.+</Step>++<Step>+### Get the preview URL++`preview_url` returns the full browser URL for the doc (see [Preview](#preview)).+</Step>++</Steps>++That sequence exercises every layer — discovery, config, read, write, link graph, search, and preview — in one pass.++## Preview++Write and edit responses include a route-only preview path like `/#/notes/mcp-round-trip` — a route id, **not** a full URL. Call `preview_url` for the openable browser address, and don't screenshot the preview to confirm an edit (the tool response is the confirmation). See [MCP reference → Preview links](/docs/reference/mcp#preview-links) for the full semantics.++## Agent contract++`ok init` installs the **OpenKnowledge skill** — the authoritative agent contract for tool use, grounding, and linking — and OpenClaw loads installed skills from `~/.agents/skills/`. Rather than restate the contract here, two OpenClaw-specific reminders:++- **Markdown is MCP-owned.** Inside an OK project, read and write `.md` / `.mdx` through OK's tools (`exec`, `search`, `write`, `edit`, `links`), not native shell or file tools — native access loses attribution and skips the frontmatter, backlinks, and history OK returns.+- **Discover before concluding the MCP is missing.** Not seeing `exec` in the initial tool list isn't the escape hatch; run tool discovery first.++For the complete tool surface, see the [MCP reference](/docs/reference/mcp).++## Troubleshooting++| Symptom | Cause | Fix |+| --- | --- | --- |+| Server won't launch / `command not found` | `ok` not on OpenClaw's PATH | Point `command` at the absolute binary: `/Users/<your-username>/.ok/bin/ok` |+| `openclaw mcp probe` shows 0 tools | wrong `cwd`, or the folder isn't a KB yet | Set `cwd` to a real folder and `ok init` it |+| Agent doesn't see `mcp__open-knowledge__*` | MCP tools lazy-loaded | Run tool discovery, then `openclaw mcp reload` |+| `ok init` "refreshed" a parent project, no new KB | upward project resolution | Run `ok init` outside any existing `.ok` tree |+| Broken-link warning on a just-written doc | forward link to a not-yet-created target | Create the target, then re-check `links({ kind: "dead" })` |+| `write` / `edit` -> "Hocuspocus server is not running" | OK server not started | Run `ok start` (or leave the desktop app running) and retry |+| Preview "doesn't open" | used the route-only `/#/…` path in a browser | Call `preview_url` for the full URL |++New to OpenKnowledge itself? Start with the [quickstart](/docs/get-started/quickstart) for `ok init` and `ok start`.diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdxindex fb3c305f7..e45728553 100644--- a/docs/content/reference/mcp.mdx+++ b/docs/content/reference/mcp.mdx@@ -6,7 +6,7 @@ description: Tools the OpenKnowledge MCP server exposes to AI agents.The MCP server gives AI agents structured access to your knowledge base. Two reads are server-free: `exec` (shell-style reads, fs-direct against the disk) and `preview_url` (reads `ui.lock` directly) both work even when the editor is down. Every other read tool (`search`, `links`, `history`, etc.) and all write tools route through the Hocuspocus server, which OpenKnowledge starts for you on the first write.-The surface is **17 tools**. Three of the four write verbs — `write`, `edit`, `delete` — are native CRUD operations polymorphic over a target (`document`, `folder`, `template`, `asset`): per-target fields nest inside the address key (`write({ document: { path, content } })`), and you pass exactly one target per call. `move` is the fourth write verb but takes flat `from`/`to` paths and auto-detects whether the path is a document, folder, or asset (no `template` target).+The surface is **19 tools**. Three of the four write verbs — `write`, `edit`, `delete` — are native CRUD operations polymorphic over a target (`document`, `folder`, `template`, `asset`): per-target fields nest inside the address key (`write({ document: { path, content } })`), and you pass exactly one target per call. `move` is the fourth write verb but takes flat `from`/`to` paths and auto-detects whether the path is a document, folder, or asset (no `template` target).## Tools@@ -16,6 +16,7 @@ The surface is **17 tools**. Three of the four write verbs — `write`, `edit`,| `search` | Ranked workspace search (title boost + body BM25 + recency; same engine the cmd-K palette uses). When [semantic search](/docs/reference/configuration#semantic-search) is enabled, an embeddings signal is additionally fused into `full_text` ranking (opt-in, content egress) — pass `semantic: false` to force pure-lexical. || `links` | Wiki-link graph. `kind` selects: `backlinks`, `forward`, `dead`, `orphans`, `hubs`, or `suggest`. Accepts an array (e.g. `["dead", "orphans", "hubs"]`) to fetch several views in one call; each view nests under its own key in the response || `history` | Version timeline for a doc. Each entry carries a `version` (commit SHA) you pass to `restore_version` |+| `skills` | Find and read agent skills. Omit `name` to list every skill across Project + Global; pass `name` to read one (addressed by `name`+`scope`, never by path) || `config` | Read the effective merged config (`config({ key: "appearance.theme" })` for a sub-tree; omit `key` for the whole config) || `palette` | Markdown-native authoring forms, themed `html preview` embed starters, and theme tokens. Pass `components` for the canonical components' full JSX prop schemas || `preview_url` | Resolve the browser-reachable preview URL. Per-response `previewUrl` fields elsewhere are route-only (`/#/<doc>`); call this when you need the full openable URL |@@ -24,6 +25,7 @@ The surface is **17 tools**. Three of the four write verbs — `write`, `edit`,| `edit` | Modify a `document` (body find/replace **or** a frontmatter merge-patch), a `folder` (frontmatter merge-patch), or a `template` || `delete` | Delete a `document` (one path or an array), `folder`, `template`, or `asset` || `move` | Move or rename a `document`, `folder`, or `asset` and rewrite every affected link |+| `install` | Project an authored skill (the Draft produced by `write({ skill })`) into your editors — the Draft → Installed step || `checkpoint` | Save a project-wide version snapshot — a single restore point. Returns its `version` || `restore_version` | Restore one document to a historical `version` (the SHA from `history` or `checkpoint`) || `conflicts` | Read GitHub-sync merge conflicts. `kind: "list"` enumerates tracked conflicts; `kind: "content"` returns one file's base / ours / theirs stages |