openagent 接入 BlueBubbles 发送与管理 iMessage：message 工具全动作实战指南

人工智能大模型AI 应用AI AgentRAGMCP Clients交互助手浏览器控制【免费下载链接】openagent⚡️next-generation personal AI assistant powered by LLM, RAG and agent loops, supporting computer-use, browser-use and coding agent, demo: https://demo.openagentai.org项目地址https://gitcode.com/gh_mirrors/ca/openagent点击查看免费下载本文面向在 openagent 中通过 BlueBubbles 网关收发 iMessage 的开发场景围绕message工具channel: bluebubbles讲解文本发送、tapback 回应、编辑/撤销、线程回复、附件与 iMessage 特效等全部动作并补充网关配置与 skill 加载机制的原理解析。读完本文你将能完整掌握用 openagent 的 Agent 能力驱动 iMessage 对话的配置方法与调用姿势。一、BlueBubbles 在 openagent 中的定位BlueBubbles 是一套运行在 macOS 上的 iMessage 服务网关openagent 官方将其列为推荐的 iMessage 集成方式见 skills/bluebubbles/SKILL.md。与直接在 macOS Messages.app 上模拟点击的方案不同BlueBubbles 通过服务端接口暴露 iMessage 的原生能力Agent 侧不需要关心 iMessage 私有协议的细节。在 openagent 中对 BlueBubbles 的调用统一走message工具通过channel参数区分目标渠道。SKILL.md 的描述字段明确写道Calls go through the generic message tool withchannelbluebubbles.这种“单一 message 工具 多 channel 路由”的模式在仓库其他 skill 中同样可见例如 skills/discord/SKILL.md 使用channel: discord、skills/slack/SKILL.md 使用独立的slack工具。从仓库pipe/目录看Discord、Slack、Telegram、WhatsApp、微信等渠道均有对应实现文件如 pipe/discord.go说明消息网关层本身就是多通道架构BlueBubbles 作为 iMessage 渠道接入同一体系。二、前置条件网关配置 channels.bluebubbles在调用任何动作之前需要确保网关配置中存在channels.bluebubbles节点。SKILL.md 的 metadata 中声明了硬性依赖requires: { config: [channels.bluebubbles] }该配置节点包含三个关键字段字段作用serverUrlBlueBubbles 网关服务地址运行 BlueBubbles 的 macOS 主机地址与端口password网关鉴权密码webhookPath接收入站消息的 webhook 路径从仓库的配置迁移逻辑看OpenClaw 风格配置中包含agents、gateway、channels、skills、mcp等顶层键见 migration/source_openclaw.gochannels.bluebubbles正是channels键下的渠道条目而gateway键对应网关服务的端口与鉴权设置。启动时可通过openagent gateway等价于serve见 internal/cli/cli.go拉起网关进程使渠道配置生效。需要说明BlueBubbles 插件本体运行在网关侧仓库内以 SKILL 指令形式描述其调用协议插件级实现细节如 webhook 的认证头格式以网关插件包的 README 为准本文不展开编造。三、调用前需要收集的输入Skill 在 Agent 决策链路中扮演“指令手册”角色。openagent 通过load_skill工具将 skill 全文注入上下文见 tool/skill.go 的NewLoadSkillBuiltin与SkillLoader因此 Agent 在调用message工具前会先读取本 SKILL 并收集以下输入target消息目标。优先使用chat_guid:...形式尤其群聊也可用 E.164 格式手机号如15551234567或 Apple ID 邮箱userexample.com。message文本内容用于 send / edit / reply。messageId消息 GUID用于 react / edit / unsend / reply 等针对既有消息的动作。附件本地文件用path字段base64 数据用bufferfilename组合。当用户指令模糊例如只说“给我妈发条消息”时Agent 应主动向用户确认接收方 handle/chat guid 与确切文本而不是凭猜测发送。四、全部动作详解含完整 JSON 示例所有动作统一通过message工具发起channel固定为bluebubbles。以下逐一给出可复制的调用样例。4.1 发送文本消息send最基本的动作。action: send加上target与message即可{ action: send, channel: bluebubbles, target: 15551234567, message: hello from openagent }4.2 Tapback 回应reactiMessage 的“点按回应”对指定消息附加表情{ action: react, channel: bluebubbles, target: 15551234567, messageId: message-guid, emoji: ❤️ }4.3 移除回应react remove对同一messageId与emoji传入remove: true即可撤销之前的 tapback{ action: react, channel: bluebubbles, target: 15551234567, messageId: message-guid, emoji: ❤️, remove: true }4.4 编辑已发送消息edit修改此前由本渠道发送的消息文本{ action: edit, channel: bluebubbles, target: 15551234567, messageId: message-guid, message: updated text }注意编辑属于较“新”的 iMessage 能力存在 macOS 版本依赖。SKILL.md 明确指出 edit 在 macOS 26 Tahoe 上可能不可用遇到失败时应降级为“重新发送更正后的消息”并如实告知用户。4.5 撤销发送unsend撤回此前发送的消息iMessage 的“取消发送”{ action: unsend, channel: bluebubbles, target: 15551234567, messageId: message-guid }4.6 回复特定消息reply在会话内针对某条消息开启线程式回复replyTo指向目标消息 GUID{ action: reply, channel: bluebubbles, target: 15551234567, replyTo: message-guid, message: replying to that }4.7 发送附件sendAttachment发送本地文件并附带简短说明文字{ action: sendAttachment, channel: bluebubbles, target: 15551234567, path: /tmp/photo.jpg, caption: here you go }若附件数据来自 base64则改用bufferfilename字段。4.8 带 iMessage 特效发送sendWithEffect为消息附加全屏特效如balloons气球{ action: sendWithEffect, channel: bluebubbles, target: 15551234567, message: big news, effect: balloons }除文档示例中的balloons外其他可用 effect 名称以网关插件支持为准调用前可先查询插件 README 中声明的枚举。五、使用要点与坑位提醒优先chat_guid目标群聊场景下手机号/邮箱无法唯一定位会话持有 chat guid 时应始终优先使用chat_guid:...形式避免发错群。消息 ID 持久性网关可能同时暴露短 ID 与完整 ID完整 ID 在网关重启后更稳定。Agent 在记录待编辑/待撤销消息时应保存完整message-guid。能力边界随系统版本浮动edit、unsend 等动作能否成功取决于 macOS 与 BlueBubbles 版本调用失败不要重试轰炸应给出可理解的错误说明。明确向用户确认目标不清晰时先询问杜绝向错误号码发送消息。六、源码视角SKILL 如何驱动 message 工具理解 BlueBubbles skill 的工作链路有助于排查“为什么 Agent 不按指令调用”。整个链路分为三层Skill 注入层openagent 通过load_skill内置工具按需加载 skill 文本工具实现在 tool/skill.go。load_skill接受skill名称与可选的reference文件名把 SKILL.md 内容以纯文本返回给模型相当于把本指南“喂”给 Agent。工具注册层所有内置工具实现 tool/builtin_tool/builtin_tool.go 的BuiltinTool接口GetName/GetDescription/GetInputSchema/Execute并注册进ToolRegistry注册后的工具可被统一转换为 MCP 协议格式GetToolsAsProtocolTools。装配与执行层object/message_tool.go的buildToolSetForBuiltinTool将指定内置工具包装成 MCPToolSet含快照与资源包装随后经model.QueryTextWithTools在模型推理中触发工具调用见 object/message_tool.go。也就是说本文给出的 JSON 示例并不是“手动粘贴执行”的脚本而是模型在读到load_skill注入的 SKILL.md 后按GetInputSchema定义的参数结构生成的工具调用参数。这与 Discord skill 共用同一套message工具路由渠道由channel字段区分。七、可立即上手的三个实战场景SKILL.md 的 “Ideas to try” 给出了低风险验证方案建议按顺序演练Tapback 确认收到用户请求后用react加一个 tapback如 ✅ / ❤️表示“已收到”这是最低成本的功能冒烟测试。线程回复当用户明确引用某条消息时用replyreplyTo保持话题上下文而不是另起一条独立消息。附件 短说明用sendAttachment发送本地文件并配一句 caption覆盖文件类任务截图、文档、图片的交付场景。这三个场景分别覆盖了“回应类”“回复类”“发送类”动作足以验证网关连通性、消息 ID 解析与附件通道是否正常。八、小结BlueBubbles 是 openagent 推荐的 iMessage 集成路径配置好channels.bluebubblesserverUrl / password / webhookPath后Agent 即可通过message工具完成发送、tapback、编辑、撤销、线程回复、附件与特效等全套操作。实际使用时牢记两点目标优先用chat_guid消息 ID 优先保存完整 GUID同时留意 macOS 版本对 edit/unsend 能力的限制。想深入了解 skill 注入与工具装配机制可继续阅读 tool/skill.go 与 object/message_tool.go想对比其他消息渠道的调用约定可参考 skills/discord/SKILL.md 与 skills/slack/SKILL.md。赞分享人工智能大模型AI 应用AI AgentRAGMCP Clients交互助手浏览器控制【免费下载链接】openagent⚡️next-generation personal AI assistant powered by LLM, RAG and agent loops, supporting computer-use, browser-use and coding agent, demo: https://demo.openagentai.org项目地址https://gitcode.com/gh_mirrors/ca/openagent点击查看免费下载相关推荐RocketRide tool_n8n 节点将 n8n 工作流接入 RocketRide 管道与 Agent 工具实战指南RocketRide tool_n8n 节点将 n8n 工作流接入 RocketRide 管道与 Agent 工具实战指南 tool_n8n 是 Rocket人工智能大模型数据工程后端RAG本地部署MCP 服务前端DriverStore Explorer 管理工具实用指南高效驱动管理与安全操作DriverStore Explorer 管理工具实用指南高效驱动管理与安全操作 DriverStore Explorer简称DSE是一款专为Window桌面应用运维Automatisch 中 Mailchimp 集成实战Campaign 创建与发送动作完全指南Automatisch 中 Mailchimp 集成实战Campaign 创建与发送动作完全指南 导读 本文聚焦 Automatisch 开源工作流自动化平台工作流自动化后端前端低代码任务调度上一篇CANN/pypto-gym交错RoPE算子下一篇多Store架构设计Teaful如何优雅管理复杂React应用状态创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考