1. 安装 PocketHook#
从 App Store 下载 PocketHook，并在 iPhone、iPad 或 Mac 上打开。
2. 配置您的服务器#
PocketHook 需要一个 HTTPS 端点进行通信。您可以使用：
- Agent Server — 自托管 AI 代理，配备 LLM、工具、后台任务和记忆
- 您自己的 API — 任何接受 POST 请求并返回 JSON 的服务器
- n8n — 自托管工作流自动化，带有 webhook 触发器
- OpenClaw — 自托管 AI 助手，支持多渠道消息
服务器要求#
您的服务器必须：
- 接受带有 JSON 主体的 POST 请求
- 返回 JSON 响应
- 通过 HTTPS 可访问（出于安全原因，HTTP 会被拒绝）
- 可选支持 Bearer token 身份验证
3. 在 PocketHook 中连接#
- 打开 PocketHook，进入设置
- 输入您的服务器 URL（必须是 HTTPS）
- 输入您的身份验证令牌（如果您的服务器需要身份验证）
- 点击测试连接进行验证
4. 请求格式#
PocketHook 将消息作为 JSON 数组发送：
[{
"sessionId": "uuid-v4",
"action": "sendMessage",
"chatInput": "您的消息"
}]
5. 响应格式#
您的服务器应以 JSON 对象响应：
{
"msg": "显示给用户的消息",
"shortcut": "可选快捷指令名称",
"data": { "键": "值" },
"url": "https://optional-url.com"
}
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
msg | string | 是 | 在聊天中显示的文本 |
shortcut | string | 否 | 要执行的 iOS Shortcut |
data | object | array | 否 | 传递给 Shortcut 的数据 |
url | string | 否 | 要打开或显示的 URL |
对于多步自动化，返回响应数组：
[
{ "msg": "步骤 1...", "shortcut": "第一个快捷指令" },
{ "msg": "步骤 2...", "shortcut": "第二个快捷指令", "data": { "input": "值" } }
]
6. 使用 Starter 服务器快速开始#
使用我们的 starter 服务器模板，几分钟内即可开始：
git clone https://github.com/pockethook-app/pockethook-server.git
cd pockethook-server
bun install
cp .env.example .env
# 用您的密钥令牌编辑 .env
bun dev
Starter 包含内置命令（ping、hello、help、time）和触发 Shortcuts 的示例。查看 API 参考了解完整的协议规范。
7. 使用 SDK#
安装 pockethook-sdk 包来构建类型安全的响应：
bun add pockethook-sdk
import { text, shortcut, responses, toResponse } from "pockethook-sdk";
// 简单文本响应
return toResponse(text("来自我的服务器的问候！"));
// 触发快捷指令
return toResponse(shortcut("运行中...", "我的快捷指令", { 键: "值" }));
// 多步自动化
return toResponse(responses([
{ msg: "步骤 1", shortcut: "第一个" },
{ msg: "步骤 2", shortcut: "第二个" }
]));