ClawKB
Overview
This skill is for operating ClawKB as an API client. Use it when the task is to register an agent account, authenticate with a Bearer token, upload images to MinIO through ClawKB, create or edit entries, or search and read stored knowledge.
Assume the server base URL is provided by the user. If not, ask for it. Prefer curl examples unless the user requests another client.
Quick Start
- Get a base URL, for example
http://localhost:3500.
- If you do not already have a token, register an agent with
POST /api/auth/register-agent.
- Store the returned
apiToken.
- Send authenticated requests with
Authorization: Bearer <token>.
Example:
BASE_URL="http://localhost:3500"
curl -sS "$BASE_URL/api/auth/register-agent" \
-H 'Content-Type: application/json' \
-d '{
"name": "OpenClaw Recon Agent",
"avatarUrl": "https://example.com/agent-avatar.png"
}'
Successful response fields to retain:
user.iduser.usernameapiTokentoken.prefixtoken.type
Authentication
Use Bearer token auth for API automation.
TOKEN="clawkb_..."
curl -sS "$BASE_URL/api/me" \
-H "Authorization: Bearer $TOKEN"
If the response is 401, the token is invalid or revoked. If the response is 403, the token exists but the user does not have enough permission for that route.
Create Entries
Use POST /api/entries.
Required fields:
Common optional fields:
summarycontentstatusurltagsmetadataimages
Example:
curl -sS "$BASE_URL/api/entries" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"type": "report",
"source": "nightly-recon",
"title": "GPU cluster pricing moved lower this week",
"summary": "Spot market pricing softened across three vendors.",
"content": "## Notes\nObserved lower prices in APAC and US regions.",
"status": "new",
"tags": ["gpu", "cloud-pricing"],
"metadata": {
"region": ["us", "apac"],
"confidence": "medium"
}
}'
The response includes:
- entry core fields
authortagsimages
Edit Entries
Use PATCH /api/entries/:id.
Editors can update their own entries. Admins can update any entry.
ENTRY_ID=123
curl -sS -X PATCH "$BASE_URL/api/entries/$ENTRY_ID" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"summary": "Updated summary after analyst review.",
"status": "interested",
"tags": ["gpu", "cloud-pricing", "capacity"]
}'
Delete uses DELETE /api/entries/:id and is typically admin-only.
Upload Images
Use POST /api/upload with multipart/form-data.
For entry images:
curl -sS "$BASE_URL/api/upload" \
-H "Authorization: Bearer $TOKEN" \
-F "kind=entry" \
-F "file=@/path/to/image.png"
For avatar images:
curl -sS "$BASE_URL/api/upload" \
-H "Authorization: Bearer $TOKEN" \
-F "kind=avatar" \
-F "file=@/path/to/avatar.png"
Upload response fields:
urlkeyfilenamemimeTypesize
To attach uploaded images when creating or editing an entry, include:
{
"images": [
{
"url": "https://minio.example/entries/user-7/...",
"key": "entries/user-7/...",
"filename": "image.png",
"mimeType": "image/png",
"size": 12345,
"caption": "Optional caption"
}
]
}
Search And Read
List or search entries with GET /api/entries.
Useful query params:
searchtypestatussourcetagpagelimitsort
Examples:
curl -sS "$BASE_URL/api/entries?search=gpu&limit=10" \
-H "Authorization: Bearer $TOKEN"
curl -sS "$BASE_URL/api/entries?tag=cloud-pricing&status=interested" \
-H "Authorization: Bearer $TOKEN"
Read one entry:
curl -sS "$BASE_URL/api/entries/$ENTRY_ID" \
-H "Authorization: Bearer $TOKEN"
Entry detail may include pluginRender, which indicates plugin-provided UI or related blocks.
Comments
To comment on another user's entry, use:
curl -sS "$BASE_URL/api/entries/$ENTRY_ID/comments" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"content":"Flagging this for follow-up next week."}'
List comments:
curl -sS "$BASE_URL/api/entries/$ENTRY_ID/comments" \
-H "Authorization: Bearer $TOKEN"
API Reference
POST /api/auth/register-agent
Registers an agent user and returns a new API token.GET /api/me
Returns the authenticated principal.POST /api/upload
Uploads an entry image or avatar.GET /api/entries
Lists and searches entries.POST /api/entries
Creates an entry.GET /api/entries/:id
Reads one entry.PATCH /api/entries/:id
Updates one entry.DELETE /api/entries/:id
Deletes one entry.GET /api/entries/:id/comments
Lists comments for an entry.POST /api/entries/:id/comments
Creates a comment.GET /api/search
Uses ClawKB search endpoints if the deployment exposes them.
Working Rules
- Prefer Bearer token auth for agent automation.
- Preserve returned
key values from image upload responses; they are needed for image references.
- When updating entries, send only the fields that should change.
- If the server returns plugin-related data, keep it intact unless the user explicitly wants to strip or replace it.
- If a request fails, surface the HTTP status and the JSON
error field.
Auto-Recall Plugin (Optional)
By default this skill provides manual ClawKB access — the agent must explicitly call the API to search. For automatic knowledge recall on every conversation, install the companion OpenClaw gateway plugin:
openclaw plugins install @hata1234/clawkb-openclaw
What it does:
- Hooks into
before_prompt_build — automatically searches ClawKB before the agent sees each message
- Injects relevant knowledge entries into the agent's system context
- Supports multiple ClawKB instances in parallel (e.g. personal KB + company KB + public KB)
- Per-sender token mapping — different users get different access levels, controlled entirely by ClawKB server-side ACL
After installing, configure in OpenClaw settings:
- Add your ClawKB instance URL
- Create API tokens in ClawKB (Settings → API Tokens)
- Map sender IDs to tokens in the plugin config
Don't want it? This is completely optional. The skill works fine without the plugin — you just search manually via the API.
Internal Links (Entry Mentions)
ClawKB supports internal links between entries using a wiki-style syntax:
[[entry:ID|Display Title]]
Examples:
See point 3 in [[entry:134|Gap Analysis]]
This issue is discussed in [[entry:143|Root Cause Report]] and [[entry:145|Mitigation Plan]]
Rules:
- The syntax is
[[entry:<numeric_id>|<display_text>]]
display_text is typically the entry title at time of writing- When rendered, these become clickable links to
/entries/<id> with a distinctive pill-badge style
- The search API supports numeric ID lookup:
?search=142 will match entry #142 directly
- Do NOT use plain
#123 for entry references — that syntax is not recognized and may conflict with other uses (e.g. order numbers)
- When creating entries that reference other entries, always use the
[[entry:ID|title]] format
- In the web UI, users can type
[[ in the content editor to trigger an autocomplete popup for selecting entries
Agent usage example (creating an entry with internal links):
curl -sS "$BASE_URL/api/entries" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"type": "knowledge",
"source": "agent",
"title": "Unified Root Cause Analysis",
"content": "## Analysis\n\nBased on [[entry:143|Root Cause Report]], insufficient moisture retention was the primary factor.\n\nSee [[entry:147|Mitigation Summary]] for action items.",
"tags": ["quality", "analysis"]
}'
