协议概述#
PocketHook 通过 HTTPS 使用简单的基于 JSON 的协议与您的服务器通信。应用发送 POST 请求并期望 JSON 响应。
认证#
PocketHook 将配置的认证令牌作为 Bearer 令牌发送：
Authorization: Bearer your-secret-token
Content-Type: application/json
请求#
标准格式#
[{
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
"action": "sendMessage",
"chatInput": "user message"
}]
| 字段 | 类型 | 说明 |
|---|---|---|
sessionId | string (UUID v4) | 唯一会话标识符 |
action | string | 始终为 "sendMessage" |
chatInput | string | 用户消息（最多 10,000 个字符） |
OpenClaw 格式#
启用 OpenClaw 模式后，PocketHook 使用 OpenAI Chat Completions 格式：
{
"model": "agent-id",
"messages": [
{ "role": "user", "content": "user message" }
]
}
附带设置为配置的代理 ID 的 x-openclaw-agent-id 头部。
响应#
单一响应#
{
"msg": "Display message",
"shortcut": "ShortcutName",
"data": { "key": "value" },
"url": "https://example.com"
}
多动作响应#
返回数组以顺序执行：
[
{ "msg": "Starting...", "shortcut": "FirstAction" },
{ "msg": "Processing...", "shortcut": "SecondAction", "data": { "input": "from-first" } },
{ "msg": "Done!", "url": "https://results.example.com" }
]
PocketHook 按顺序执行快捷指令，等待每个完成后再运行下一个。
响应字段#
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
msg | string | 是 | 聊天中显示的文本。支持 Markdown、HTML、图片和按钮语法。 |
shortcut | string | 否 | 要执行的 iOS 快捷指令名称。 |
data | object | array | 否 | 作为输入传递给快捷指令的 JSON 数据。 |
url | string | 否 | 与消息关联的 URL。 |
OpenClaw 响应#
在 OpenClaw 模式下，PocketHook 从响应内容中解析内联标记：
Here's your result! [SHORTCUT:ProcessData] [DATA:{"key":"value"}] [URL:https://example.com]
内容渲染#
msg 字段支持多种内容类型：
纯文本#
{ "msg": "Simple text message" }
Markdown#
{ "msg": "**Bold**, *italic*, `code`, and [links](https://example.com)" }
HTML#
必须以 <div 开头才能被识别为 HTML:
{ "msg": "<div><h2>Title</h2><p>Rich <strong>HTML</strong> content</p></div>" }
图片#
{ "msg": "https://example.com/image.png" }
以 .png、.jpg、.jpeg、.gif 或 .webp 结尾的任何 URL 将渲染为图片。
按钮#
在消息下方渲染的交互式按钮。格式: Button: Title | actionType: actionValue
三种操作类型:
sendMessage: text— 将文本作为新消息发送到服务器openURL: https://...— 在浏览器中打开 URLtriggerShortcut: ShortcutName— 运行 iOS 快捷指令
{ "msg": "Which one do you prefer?\nButton: Option A | sendMessage: I choose option A\nButton: Option B | sendMessage: I choose option B" }
混合操作:
{ "msg": "Here are the results:\nButton: View details | openURL: https://example.com/item\nButton: Add to cart | triggerShortcut: addToCart" }
按钮行从显示的文本中隐藏 — 只有交互式按钮显示在消息下方。
健康检查#
PocketHook 支持可选的健康检查端点：
- 方法：GET
- 预期响应：纯文本
true或false - URL：在设置中单独配置
后台轮询#
启用后，PocketHook 会定期向轮询 URL 发送 GET 请求：
- 如果响应为
true，PocketHook 会将配置的获取消息发送到主服务器 - 轮询间隔：5、15、30、60 或 120 分钟
- 需要通知权限才能进行后台提醒
Agent Server： 使用 https://your-host/jobs 作为轮询 URL。当有已完成的后台任务结果等待交付时返回 true。
SDK#
使用 pockethook-sdk npm 包通过 TypeScript 构建响应：
import { text, shortcut, responses, toResponse, parseRequest } from "pockethook-sdk";
// 解析和验证传入请求
const { sessionId, chatInput } = parseRequest(requestBody);
// 构建响应
toResponse(text("Hello!"));
toResponse(shortcut("Running...", "MyShortcut", { key: "value" }));
toResponse(responses([
{ msg: "Step 1", shortcut: "First" },
{ msg: "Step 2", shortcut: "Second" }
]));