怎么用 Knockbox

任何能发一条 HTTP 请求的东西，一行命令就能把消息推到你的 iPhone 上 ——家里的自动化、网上的价格监控、你写的小脚本，或者你自己的 AI agent。

发送地址长这样
url
1https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>
扫码接入后，你会拿到一份填好 TOKEN 的同一页，每条示例旁边还多一颗「发这条」，按下去手机就响。
去接入页扫码

怎么接

装 app，扫码

下载 Knockbox，打开接入页扫二维码。不需要注册，不需要密码 ——扫完你就有了自己的收件身份和第一个频道。没有账号密码意味着设备全丢就找不回；想多一台设备，在已接入的 app 里出码给新设备扫。

一个频道一个用途

每个频道有自己独立的发送地址，也有自己的铃声、打扰级别和静音开关。给「家里」和「快递」各建一个，半夜就只有前者会把你吵醒。在 app 里点进频道 → 右上角「…」→ 频道设置，能随时回到它的发送页。

怎么发

最简单的一条

整个 body 就是正文，什么都不用配。手机上是一条纯文本通知。

bash
1curl -d "洗衣机洗完了" https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>

带标题

标题是通知的第一行，正文在下面。纯 GET 也收，方便那些只会拼 URL 的地方。

bash
1curl "https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>?title=快递到了&text=放在楼下丰巢 A 区 12 号柜"

markdown

表格、列表、引用、代码块（带行号和高亮）都渲染。正文不进推送本身，是 app 打开时单独取的，因此可以写得很长。

bash
1curl -H 'Content-Type: application/json' -d '{
2 "type": "markdown",
3 "title": "本周花销",
4 "body": "这周一共花了 **¥612**。\n\n| 分类 | 金额 |\n|---|---|\n| 吃饭 | ¥305 |\n| 交通 | ¥128 |\n\n> 比上周多了 ¥74。"
5}' https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>

列表 / 清单

无序、有序、可勾选的任务清单都支持，适合发「还差哪几件事」。

bash
1curl -H 'Content-Type: application/json' -d '{
2 "type": "markdown",
3 "title": "出门前检查",
4 "body": "- [x] 关空调\n- [x] 锁阳台门\n- [ ] 倒垃圾"
5}' https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>

卡片

有序的键值对，比表格更紧凑，适合「一件事的几个要点」。style 可以是 ok / warn / error / muted，只影响右边那个值的颜色。

bash
1curl -H 'Content-Type: application/json' -d '{
2 "type": "card",
3 "title": "这个月话费出账了",
4 "items": [
5 {"k": "金额", "v": "¥59.00"},
6 {"k": "状态", "v": "已自动扣费", "style": "ok"}
7 ]
8}' https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>

带图

通知上那块 app 图标会换成图片本身，展开是大图。图会被等比缩到长边 1600，原图不保留。

bash
1curl -F "title=昨天家里用电有点高" -F "text=14.2 度，比平时高约 60%" -F "image=@chart.png" https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>

会自己更新的通知

带同一个 collapse_id 的新通知会顶掉旧的，通知栏里始终只有最新那条，适合进度和状态刷新。连按几次这颗按钮就能看出来。另有 idem_key 用于幂等：上游重试时带同一个值不会推第二遍。

bash
1curl -H 'Content-Type: application/json' -d '{
2 "title": "快递派送中",
3 "body": "还有 3 站到你家",
4 "collapse_id": "sf-1234567890"
5}' https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>

交给 AI agent

整段提示词粘给它

整段复制给 Claude Code 或任何能执行命令的 agent。地址已经在里面了，不用改任何东西。

prompt
1我有一个 Knockbox 推送服务，可以把消息发到我的 iPhone 上。
2
3发送地址（这就是我的频道，直接用，不用替换任何东西）：
4 https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>
5
6四种写法都支持：
7 curl -d "消息正文" https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>
8 curl "https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>?title=标题&text=正文"
9 curl -F "title=标题" -F "text=正文" -F "image=@图.png" https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>
10 curl -H 'Content-Type: application/json' -d '{"type":"markdown","title":"标题","body":"正文"}' https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>
11
12字段：
13 type text | markdown | image | link | card，缺省 text
14 title 标题，通知第一行
15 body 正文，可以写得很长；markdown 支持代码块、表格、列表、引用
16 link 附一个链接，通知上可以直接打开
17 items type=card 时的键值对数组 [{"k":"分支","v":"main","style":"ok"}]，顺序稳定
18 idem_key 幂等键，重试带同一个值不会重复推送
19 collapse_id 折叠键，同一个值的新通知会顶掉旧的，适合进度刷新
20 reply 要一个答复（见下），答复不从这条连接回来，而是 POST 到你给的地址
21
22请在需要通知我的时候用它发消息：事情做完了、出了问题、需要我拿个主意。
23标题一句话说清是什么事，正文放细节；几项并列的结果用 markdown 表格或 card。
24
25要一个答复：
26 curl "https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>?title=窗帘 30 秒后自动打开&choices=打开,不要打开&reply_timeout=30&reply_webhook=https://你的地址/hook"
27
28 或者写成对象：
29 curl -H 'Content-Type: application/json' -d '{
30 "title": "要部署到生产吗？",
31 "reply": {"type":"choice","options":["部署","先别"],"webhook":"https://你的地址/hook"}
32 }' https://knockbox.miramiao.com/api/v1/send/<你的TOKEN>
33
34 type choice 出按钮点一个，multi 勾几个再提交，number 拖滑块选一个数，text 出输入框
35 options choice / multi 的选项，2 到 10 项，每项不超过 40 字
36 min max type=number 必填的范围；step 不填按 1，unit 是显示在数字后面的单位（°C / 分钟）
37 timeout 多少秒内有效，不填就一直可以回。只有「不回就会自动发生别的事」才需要设
38 webhook 必填。我点了之后，服务端把答复 POST 到这个地址
39
40 收到的内容：{"uid":"…","channel":"…","title":"…","reply":"不要打开","replied_at":1726…}
41 reply 的类型随形态变：choice / text 是字符串，multi 是字符串数组，number 是数字。
42 请求头带 X-Knockbox-Signature: sha256=<HMAC-SHA256(请求体, 频道 token)>，可以用它验来源。
43
44 没有能收 POST 的地址就别用 reply：在消息里说清你在等，然后停下来等我。

或者接成 MCP

同一个地址也说 MCP（streamable HTTP），只有一件工具：发一条通知——给执行不了命令的客户端用，也省掉每个项目粘一遍提示词。三种加法按客户端选：第一段整段发给 AI 助手，它自己会配；JSON 填进客户端的配置文件；命令在 Claude Code 里跑。这个端点的权限和发送地址完全相同：只能往这个频道发，读不到任何东西。

1请帮我添加一个 MCP 服务器：
2- 名称：knockbox
3- 传输方式：Streamable HTTP（远程 http）
4- 地址：https://knockbox.miramiao.com/mcp/<你的TOKEN>
5它只有一件工具 knock，用来给我的手机发通知。
6添加完成后调用它给我发一条测试通知。

其它

限制

  • 最多 20 个频道
  • 每 24 小时最多 500 条（滚动窗口，不是按自然日清零）
  • 消息保留 30 天，之后自动清理
  • 超了会明确返回 429 并说明多久恢复，不会静默丢消息

自己搭一个

服务端是开源的，一个二进制加一个 SQLite 文件，消息完全存在你自己的机器上。接入方式和这里一模一样，只是地址换成你自己的。

发送地址等同于往这个频道发消息的权限，别公开贴出来。泄露了就在 app 的频道设置里轮换一次，频道和历史都不受影响。