Transport Layer

Tool Registration, Request/Response Contracts & Error Normalization

Tool Registration Flow

Plugin Lifecycle: Install → Register → Serve
1. INSTALL
openclaw plugins install clawhub:obsidian-rag
→ Downloads plugin, reads openclaw.plugin.json
2. REGISTER
Plugin.register(tools) → OpenClaw Tool Registry
→ 4 tools registered: search, index, status, memory_store
→ Each tool declares: name, description, parameterSchema, requiredPermissions
3. SERVE
OpenClaw Agent → tool_call(obsidian_rag_search, {query: "..."}) → Plugin
Plugin → structured response → OpenClaw Agent
4. HEALTH CHECK
Plugin.onLoad() → probe Ollama, probe LanceDB, probe Vault
→ Reports status: healthy | degraded | unavailable

Standardized Response Envelope

All tool responses use this envelope
{
  "status": "healthy" | "degraded" | "unavailable",
  "data": T | null,
  "error": {
    "code": string,       // e.g. "OLLAMA_UNREACHABLE"
    "message": string,    // human-readable
    "recoverable": bool,  // can the agent retry?
    "suggestion": string  // e.g. "Run obsidian-rag index first"
  } | null,
  "meta": {
    "query_time_ms": number,
    "chunks_scanned": number,
    "index_version": string,
    "vault_mtime": string   // ISO 8601
  }
}

Error Normalization Matrix

How each failure maps to status + error
Failure Status Code Recoverable
Ollama down degraded OLLAMA_UNREACHABLE yes — retry after start
Empty vault / no index unavailable INDEX_NOT_FOUND yes — run index first
LanceDB corrupted unavailable INDEX_CORRUPTED yes — run reindex
Path traversal attempt unavailable SECURITY_VIOLATION no
Sensitive content blocked degraded SENSITIVE_FILTERED yes — with confirmation
Indexer CLI crash unavailable INDEXER_FAILED yes — retry once

Key Design Points

Why this works

  • OpenClaw agent never sees raw exceptions — all errors normalized
  • Three-state health (healthy/degraded/unavailable) lets agent adapt behavior
  • Recoverable flag lets agent decide whether to retry or inform user
  • Suggestion field gives agent context to offer remediation

Trade-offs

  • Envelope adds ~200 bytes per response (negligible)
  • Agent must handle three status states, not just success/fail
  • Health check on load adds ~1s startup latency