Self-Hosted / Open Agents

0. You bring the agent, we keep the gate

The platform provides context (threads, orders, knowledge, the forbidden-commitments list); your agent reasons with its own model; the platform safety gate re-checks every draft. High-risk decisions (refund / replacement / complaint / chargeback / safety) are always human — no scope combination bypasses this. One key reaches exactly one workspace. Every call is audited. Reads and draft submissions consume zero platform AI credits (BYOB).

This page applies equally to OpenClaw, Hermes, and any client that speaks MCP or plain HTTP; product-specific config file locations iterate quickly (pending validation) — everything below is the generic shape.

1. MCP connection (any MCP client)

Raw file: /agent-packs/open-agent/mcp-config.example.json

{
  "mcpServers": {
    "kefuagent": {
      "type": "http",
      "url": "https://kefuagents.com/api/gateway/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_GATEWAY_KEY"
      }
    }
  }
}

• Works with any client supporting remote MCP (Streamable HTTP + custom headers); where to paste it depends on your agent's docs (formats are all close variants of the same three fields: URL, transport, Authorization header).
• After connecting, tools/list should return 17 tools (1:1 with the OpenAPI operationIds).

2. Plain HTTP (agents without MCP)

• Download the OpenAPI description: https://kefuagents.com/gateway/openapi.json (the single contract source; tool name = operationId).
• Three-call curl loop:

BASE=https://kefuagents.com/api/gateway/v1
AUTH="Authorization: Bearer $KEFUAGENT_GATEWAY_KEY"

# 1. what needs handling
curl -s $BASE/cards -H "$AUTH"

# 2. full reply context for one thread (note contextVersion and constraints)
curl -s $BASE/threads/$THREAD_ID/reply-context -H "$AUTH"

# 3. draft with your own model, then submit behind the safety gate
curl -s -X POST $BASE/threads/$THREAD_ID/drafts -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"idempotencyKey":"'$(uuidgen)'","declaredContextVersion":"'$CTX'",
       "bodyText":"...","agentLabel":"my-agent"}'

• Errors are always {success:false, code, message, traceId, ...}; DRAFT_REJECTED carries violations[], RATE_LIMITED carries retryAfterSec — branch on code, never parse prose.

3. Webhook wake-up (do not poll)

Raw file: /agent-packs/open-agent/register-webhook.example.sh

curl -s -X POST https://kefuagents.com/api/gateway/v1/webhooks \
  -H "Authorization: Bearer $KEFUAGENT_GATEWAY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"idempotencyKey":"'$(uuidgen)'",
       "url":"https://your-agent.example.com/kefuagent-webhook",
       "eventTypes":["task.created","task.updated"]}'
# 响应里的 secret 只显示这一次，立即保存。

Five receiver rules:

1. Verify |now - X-KefuAgent-Timestamp| <= 300s;
2. Recompute HMAC-SHA256("{timestamp}.{rawBody}", secret) and constant-time compare against the v1= value of X-KefuAgent-Signature;
3. Deduplicate by X-KefuAgent-Event-Id (at-least-once delivery);
4. Respond 2xx within 10 seconds; do the work asynchronously;
5. Events are thin snapshots (ids/type/status only) — always read content through the authenticated get_reply_context.

URLs must be https:// and publicly reachable (private/loopback addresses are rejected with WEBHOOK_URL_INVALID).

4. Minimum-scope guidance (self-hosted agents: start minimal)

• Even with gateway:approve enabled, approving a high-risk reply is always refused (HIGH_RISK_REQUIRES_HUMAN) — a structural platform guarantee, not a setting.
• Keys can be revoked at any time in the settings panel, effective immediately; the panel shows each key's recent calls (tool, time, outcome, trace id).
• The self-hosted ecosystem churns fast: this page depends on only two stable contracts — the MCP endpoint and the OpenAPI document. Swap your agent, keep the config.