server-api.md

Claw Guard Server API

Purpose

Claw_Guard collects security events inside OpenClaw. Claw_Guard_Server can evaluate those events synchronously and can also receive them asynchronously for audit or offline analysis.

Transport

• Protocol: HTTP/1.1 + JSON
• Encoding: UTF-8
• Content-Type: application/json
• Default endpoint: https://api.clawguard.cc
• Auth: optional Authorization: Bearer <apiKey>
• Default timeout: 2000ms
• Versioning: URL prefix /v1

Compatibility rules:

• the server should ignore unknown fields
• existing fields should only be extended, not renamed in place
• Claw_Guard may keep richer internal mode semantics and translate them into the current wire mode values for server compatibility

Decision Terms

Product language:

• block
• warning
• pass

Wire format:

• block
• warn
• allow

Mapping:

• block -> high-risk action, block in enforce
• warn -> continue but audit and warn
• allow -> continue normally

Plugin compatibility note:

• internal plugin modes are enforce, standard, and ignore
• wire mode stays compatible with the current server contract
• plugin mapping:
  • internal enforce -> wire enforce
  • internal standard -> wire enforce
  • internal ignore -> wire audit

SecurityPolicyRequest

{
  "ts": "2026-03-14T05:30:00.000Z",
  "pluginId": "claw-guard",
  "mode": "enforce",
  "event": {
    "kind": "command",
    "source": "before_tool_call",
    "instruction": "openclaw plugins install ./evil-plugin",
    "labels": ["install_operation", "plugin_install", "command_execution"],
    "toolName": "exec"
  }
}

Fields:

• ts: ISO 8601 timestamp
• pluginId: fixed as claw-guard
• mode: enforce or audit
• event.kind: command, file, url, tool_call, or message
• event.source: before_tool_call, after_tool_call, or message_received
• event.instruction: normalized text for policy evaluation
• event.labels: plugin-side classification labels
• event.*Ids and event.metadata: optional context only

SecurityPolicyResponse

{
  "decision": "warn",
  "risk": "medium",
  "reasons": ["flagged:plugin_install"],
  "policyTags": ["plugin_install"]
}

Fields:

• decision: allow, warn, or block
• risk: low, medium, or high
• reasons: matched reasons
• policyTags: matched rule tags

Default no-hit response:

{
  "decision": "allow",
  "risk": "low",
  "reasons": ["allow:default"],
  "policyTags": []
}

SkillHashCheckRequest

Purpose: upload a skill archive or installed skill directory hash for fast reputation lookup.

{
  "ts": "2026-03-16T05:30:00.000Z",
  "pluginId": "claw-guard",
  "source": "before_tool_call",
  "action": "skill_install",
  "hashAlgorithm": "sha256",
  "hash": "4d9f4c7c...",
  "artifactType": "file",
  "artifactPath": "/workspace/demo-skill.zip",
  "artifactName": "demo-skill.zip",
  "instruction": "openclaw skills install ./demo-skill.zip",
  "labels": ["install_operation", "skill_install", "skill_hash_lookup"]
}

Fields:

• source: before_tool_call, after_tool_call, or message_received
• action: skill_install or skill_download
• hashAlgorithm: currently sha256
• hash: normalized artifact hash
• artifactType: file or directory
• artifactPath and artifactName: optional operator context
• instruction: original install/download command
• labels: plugin-side classification labels

SkillHashCheckResponse

{
  "decision": "block",
  "risk": "high",
  "reasons": ["blocked:skill_hash_match"],
  "policyTags": ["skill_hash_match"],
  "matched": true
}

Default no-hit response:

{
  "decision": "allow",
  "risk": "low",
  "reasons": ["allow:unknown_skill_hash"],
  "policyTags": [],
  "matched": false
}

SkillReportUploadHashRequest

Purpose: upload the local skill safety verdict using the original skill-report hash API contract.

{
  "uuid": "9d7f5fe4-5f11-40d8-8f50-29b4fbbcf67a",
  "hash": "sha256:4d9f4c7c...",
  "reportedStatus": "unsafe"
}

Fields:

• uuid: per-upload id generated by the plugin
• hash: canonical skill hash sent to the server
• reportedStatus: safe or unsafe

SkillReportUploadHashResponse

{
  "exist": false,
  "hash": "sha256:4d9f4c7c...",
  "reportId": 12,
  "createdAt": "2026-03-18T08:00:01.000Z"
}

Endpoints

GET /healthz

Health check for operators and dashboard integrations.

Example response:

{
  "ok": true,
  "date": "2026-03-14T05:30:00.000Z",
  "policy": {
    "configPath": "/abs/path/config/policy.json",
    "loadedAt": "2026-03-14T05:20:00.000Z",
    "usingDefaultConfig": false
  }
}

POST /v1/guard/evaluate

Purpose: synchronous policy decision.

Request body: SecurityPolicyRequest

Success:

• 200 OK with SecurityPolicyResponse

Failure body:

{
  "error": "internal_error",
  "detail": "Error: ..."
}

Expected status codes:

• 200: decision returned
• 401: auth failed
• 404: route not found
• 500: internal failure

Plugin-side handling:

• block: block in plugin standard and enforce
• warn: warn in plugin standard; block in plugin enforce; ignore in plugin ignore
• request failure:
  • block if mode=enforce and intel.failClosed=true
  • otherwise fallback to the local rule engine only

POST /v1/guard/events

Purpose: asynchronous event upload.

Request body: SecurityPolicyRequest

Success:

• 202 Accepted

Example response:

{
  "ok": true
}

POST /v1/guard/skill-hash

Purpose: synchronous skill artifact hash lookup.

Request body: SkillHashCheckRequest

Success:

• 200 OK with SkillHashCheckResponse

Expected status codes:

• 200: hash verdict returned
• 401: auth failed
• 404: route not found
• 500: internal failure

Plugin-side handling:

• block: local path installs can be blocked before execution in plugin standard and enforce
• warn: continue but warn in plugin standard; block in plugin enforce; ignore in plugin ignore
• post-download checks discovered only after the install completes should warn and audit immediately

POST /v1/skill-report/upload-hash

Purpose: upload the agent-authored local skill review verdict using the original uuid/hash/reportedStatus JSON contract.

Request body: SkillReportUploadHashRequest

Success:

• 200 OK with SkillReportUploadHashResponse

Plugin-side handling:

• before_prompt_build injects a mandatory review contract and the local skill-reports/ directory path
• the agent must compute the skill hash first and then write one JSON record file per skill, named by the hash hex
• after_tool_call uploads as soon as a skill-reports/*.json file is written successfully
• if upload-hash returns exist=false, the plugin immediately follows with POST /v1/skill-report/upload-file using the original archive or a temporary zip created from the skill directory