@ontos-ai/knowhere-claw

Knowhere for OpenClaw

Knowhere is an OpenClaw plugin that parses documents and URLs with Knowhere, stores extracted Knowhere files in OpenClaw state, and gives agents a browse-first toolset for grounded document work.

Quick mental model:

• Install the plugin
• Restart the Gateway
• Configure plugins.entries."knowhere-claw".config
• Ask an agent to read, search, or compare a document
• Let the bundled knowhere and knowhere_memory skills steer the agent toward the right tools

Where It Runs

This plugin runs inside the OpenClaw Gateway process.

If your agents talk to a remote Gateway, install and configure the plugin on the machine running that Gateway, then restart that Gateway.

What You Get

• Ingest local files or document URLs with Knowhere
• Store parsed documents inside OpenClaw-managed state
• Preview document structure, search chunks, and inspect raw result files
• Reuse stored documents across session, agent, or global scope
• Ship bundled knowhere and knowhere_memory skills so agents prefer this toolchain for document-heavy tasks and knowledge-base lookups

Install

openclaw plugins install @ontos-ai/knowhere-claw

Restart the Gateway afterwards.

Config

Set config under plugins.entries."knowhere-claw".config:

{
  plugins: {
    allow: ["knowhere-claw"],
    entries: {
      "knowhere-claw": {
        enabled: true,
        config: {
          // apiKey is optional
        },
      },
    },
  },
}

Config notes:

• apiKey: optional Knowhere API key. If omitted, the plugin falls back to KNOWHERE_API_KEY and any API key previously stored with knowhere_set_api_key.
• If no API key is available when the agent first needs Knowhere, the plugin guides the user to the Knowhere API key page at https://knowhereto.ai/api-keys.
• baseUrl: optional Knowhere API base URL. Falls back to KNOWHERE_BASE_URL and defaults to https://api.knowhereto.ai.
• storageDir: optional directory for persisted parsed documents. By default, the plugin stores data under the OpenClaw state directory for knowhere-claw.
• scopeMode: document sharing boundary. Supported values are session, agent, and global. If omitted, the plugin defaults to session.
• pollIntervalMs, pollTimeoutMs, requestTimeoutMs, uploadTimeoutMs: optional tuning for job polling, API calls, and large uploads.
• An explicit storageDir such as /home/<user>/.openclaw/plugin-state/knowhere makes stored documents easier to inspect, back up, or clean up.

How OpenClaw Uses It

Once the plugin is enabled, you can ask an OpenClaw agent to:

• summarize a local document
• read a document URL
• find a table or section in a previously ingested document
• compare a new document with documents already stored in scope

The bundled knowhere skill teaches agents to use the knowhere_* tools instead of raw file reads when document parsing matters.

The bundled knowhere_memory skill teaches agents to treat previously parsed Knowhere content as a knowledge base when users ask to search their materials, look something up, or summarize what data they already have.

If you use skill filters or allowlists in OpenClaw, keep the bundled knowhere and knowhere_memory skills enabled or the tools will load without their intended usage guidance.

If your agent runtime uses a tool allowlist, include knowhere_* so agents can actually call the plugin tools.

Scope And Storage

scopeMode controls who can reuse parsed documents:

• session: only the current session can reuse the stored documents
• agent: all conversations for the same agent can reuse them
• global: all agents on the same Gateway can reuse them

Within each scope, the plugin keeps:

• an index.json cache of stored document summaries
• a metadata/ directory with one JSON record per stored document
• the extracted Knowhere result files directly inside each document directory

Common Workflow

• Provide a file path or URL to the agent.
• The agent ingests it into Knowhere. By default this starts parsing asynchronously and returns a job ID; when the current turn needs the parsed result immediately, the agent can call knowhere_ingest_document with blockUntilComplete: true.
• Follow-up questions reuse stored results from the current scope.
• When needed, the agent can preview structure, search chunks, read raw result files, or clear stored documents.

Schema v2.1 Media Handling

• knowhere_read_chunks now treats [images/...] and [tables/...] path references in chunks.json content as the primary media enrichment path.
• Standalone image and table chunks resolve their real asset locations from metadata.file_path.
• Assets without metadata.file_path are ignored by the runtime enrichment and delivery pipeline.

Troubleshooting

• Missing API key: apiKey config is optional. You can set plugins.entries."knowhere-claw".config.apiKey, export KNOWHERE_API_KEY, or let the plugin guide the user to https://knowhereto.ai/api-keys and store the key with knowhere_set_api_key.
• Documents are not shared between conversations: change scopeMode from session to agent or global.
• The plugin is enabled but agents do not reach for Knowhere: check that the bundled knowhere skill is not filtered out.
• Large documents time out: increase pollTimeoutMs or uploadTimeoutMs.

Developer Docs

Contributor-oriented architecture, workflow, and packaging notes live in DEVELOPMENT.md at the repository root.

Release-process details for maintainers live in docs/release-workflow.md.