OpenClaw

OpenClaw is an agent gateway: it runs agents that connect to MCP servers. Once OpenKnowledge is registered as one of them, 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.

Auto-sync your meetings. The gateway has a built-in scheduler and a webhook listener, so once OpenKnowledge is registered it can run tasks against your knowledge base unattended. The headline example is keeping meeting notes flowing in on their own. See Ingest meetings for the cron recipe and the recorder list. The webhook mechanics, for running an agent the moment a meeting event fires, are documented below.

Install

There are two ways to connect OpenClaw, depending on how you run OpenKnowledge:

• macOS desktop app. The first time you open a project, a consent dialog detects OpenClaw and configures it for you. To re-trigger the dialog, choose File → Set up OpenKnowledge integrations….
• Web app / terminal (Linux, Windows, Intel Mac — see the web app guide). Run ok init in your project: it registers the OpenKnowledge MCP server with OpenClaw and the other editors it detects. Every ok start repairs the entry if it has drifted (it never adds one you removed).

After ok init writes the config, restart the OpenClaw gateway so running agents pick up the entry — openclaw mcp reload refreshes the current CLI process only. ok start isn't needed here, since OpenClaw manages its own server lifecycle.

ok init writes the OpenKnowledge server into ~/.openclaw/openclaw.json under mcp.servers, using the same resilient launcher every other editor gets — it finds ok whether you installed the desktop app or the npm CLI, so there's no PATH to configure.

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 launched the server and its tools enumerate:

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:

OpenClaw should call the OpenKnowledge exec tool and respond with some of your documents.

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 restart the gateway.

Initialize a knowledge base

ok init turns a folder into a knowledge base (and, on the same run, registers the MCP server above):

cd /path/to/your/knowledge-base && ok init

Smoke test

Point an OpenClaw agent at a fresh knowledge base and have it do the following steps:

Smoke-test the current OpenKnowledge project, one step at a time:

1. Discover your tools — if the open-knowledge tools aren't listed yet, run tool discovery.
2. Read the resolved config and list the project root, to confirm you're pointed at the right project.
3. Write a notes folder, a README, and a note linking to a second doc you'll create next (its broken-link warning is expected).
4. Create that second doc, so the link resolves.
5. Read both docs back — you should get content plus frontmatter, backlinks, and history.
6. Audit dead links (it should be empty now), then search for the two new docs.
7. Return the preview URL for one of the docs.

That sequence exercises every layer — discovery, config, read, write, link graph, search, and preview — in one pass.

Trigger runs from external events

Besides the cron poll (see Ingest meetings), the gateway can run an agent the moment something happens elsewhere. Enable the hooks listener in the gateway config:

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

The token is a dedicated secret, separate from your gateway auth token. Every request must carry it as Authorization: Bearer <token> (recommended) or x-openclaw-token: <token>. Query-string tokens are rejected.

Ingest a meeting the moment its transcript is ready:

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"A meeting transcript is ready. Pull it from the recorder MCP and write it into the meetings/ folder of this project as meetings/<source>-<source_meeting_id>.","name":"OK meeting ingest"}'

Prep a doc the moment a meeting starts:

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"A meeting just started. Create its doc in the meetings/ folder from the prep template and link each attendee to their people/ dossier.","name":"OK meeting prep"}'

Which event you send matters more than the plumbing. Ingest meetings covers which recorder emits what, and why a transcript-ready event drives ingestion while meeting.started drives prep.

One practical constraint: a vendor cannot POST to 127.0.0.1. Keep hook endpoints behind loopback, a private network, or a trusted reverse proxy, which means a locally-run gateway needs a tunnel or a relay to receive vendor webhooks. That is why the cron poll is the default and webhooks are the upgrade. Restrict hooks.allowedAgentIds to limit which agents an external caller can target, and treat every inbound payload as untrusted.

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 for the full semantics.

Agent contract

The OpenKnowledge skill — the authoritative agent contract for tool use, grounding, and linking — is project-scoped, written for Claude, Cursor, Codex, and OpenCode; OpenClaw has no project skill directory to receive it. The bundles OpenKnowledge installs to ~/.agents/skills/ (which OpenClaw loads) cover discovery and skill authoring, not tool use — so for OpenClaw agents, the contract is these two 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.

Troubleshooting

New to OpenKnowledge itself? Start with the quickstart for ok init and ok start.