自托管 / 开放 Agent 接入

0. 你带 agent，我们守门

平台提供上下文（线程、订单、知识、禁承诺清单），你的 agent 用自己的模型推理，平台 安全门复检每一份草稿。高风险（退款/补发/投诉/拒付/安全）永远由人决定——没有任何 scope 组合可以绕过。一把 key 只能进一个 workspace。所有调用带审计。读取与提交草稿 不消耗平台 AI 积分（BYOB）。

本页对 OpenClaw、Hermes 及任何会说 MCP 或纯 HTTP 的客户端一体适用；产品各自的 配置文件位置迭代很快（待验证），下面给出的都是通用形态。

1. MCP 接入（任何 MCP 客户端）

原始文件：/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"
      }
    }
  }
}

• 适用于 OpenClaw、Hermes 及任何支持 remote MCP（Streamable HTTP + 自定义 header） 的客户端；具体粘贴到哪个配置文件以你的 agent 文档为准（各家格式相近，服务器条目 三要素：URL、transport、Authorization header）。
• 连接后 tools/list 应返回 17 个工具（与 OpenAPI operationId 一一对应）。

2. HTTP 直连（无 MCP 的 agent）

• OpenAPI 描述下载：https://kefuagents.com/gateway/openapi.json （唯一契约源，工具名 = operationId）。
• 三步 curl 快速回路：

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

# 1. 有什么要处理的
curl -s $BASE/cards -H "$AUTH"

# 2. 拿单个线程的完整回复上下文（记下 contextVersion 和 constraints）
curl -s $BASE/threads/$THREAD_ID/reply-context -H "$AUTH"

# 3. 用你自己的模型起草后提交，平台安全门复检
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"}'

• 错误一律是 {success:false, code, message, traceId, ...}；DRAFT_REJECTED 带 violations[]，RATE_LIMITED 带 retryAfterSec——按 code 分支，不要解析文案。

3. Webhook 唤醒（别轮询）

原始文件：/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 只显示这一次，立即保存。

接收端五条规则：

1. 校验 |now - X-KefuAgent-Timestamp| <= 300s；
2. 重算 HMAC-SHA256("{timestamp}.{rawBody}", secret)，与 X-KefuAgent-Signature 的 v1= 值常量时间比较；
3. 按 X-KefuAgent-Event-Id 去重（at-least-once 投递）；
4. 10 秒内回 2xx，活儿放异步；
5. 事件是瘦快照（只有 id/类型/状态），内容永远通过 get_reply_context 认证读取。

URL 要求 https://、公网可达（内网/回环地址会被拒绝，WEBHOOK_URL_INVALID）。

4. 最小 scope 指南（自托管 agent 请从最小开始）

• 即使开启 gateway:approve，高风险回复的 approve 也会被拒绝 （HIGH_RISK_REQUIRES_HUMAN）——这是平台结构性保证，不是配置项。
• key 在设置面板可随时吊销，吊销即刻生效；面板能看到每把 key 的最近调用 （工具、时间、结果、trace id）。
• 自托管 agent 生态迭代极快：本页配置只依赖两个稳定契约——MCP 端点和 OpenAPI 文档。 你的 agent 换了，配置照抄即可。