VoiceOS Instagram 集成

通过 Mac 的灵动岛用语音运行你的 Instagram 账户。询问账户表现如何、阅读评论和私信，以及通过将照片拖到灵动岛并说出配文来发布照片或轮播图。

需要企业或创作者账户。 Instagram 的 API 不向个人账户开放数据洞察、评论、私信或发布功能——这是 Meta 的规定，不是我们的，且没有绕过办法。

转换方法：Instagram 应用 → 你的个人主页 → ☰ 菜单 → 设置与隐私 → 账户类型和工具 → 切换到专业账户。选择创作者或企业，然后按照提示操作。这是免费的、可逆的，并且如果你的账户原本是私密账户，切换后也不会变为公开。之后重新连接此集成。

设置

共六步。只有在你想要发布时才需要第 3 步和第 4 步；仅阅读则不需要。

1. 安装依赖

cd instagram
bun install

2. 通过 Composio 连接 Instagram

Composio 是此集成所依赖的认证和 API 传输层。

1. 从 Composio 控制台 获取 API 密钥。

2. 在你的 Composio 项目中添加 Instagram 应用。这将创建连接流程所需的认证配置。

你将在第 6 步批准实际的 Instagram OAuth——这里无需操作。

3. 创建照片中转存储桶（Cloudflare R2）

Instagram 从不接受图片字节。Meta 的爬虫改为获取一个公开 URL。因此，你拖到灵动岛上的照片会上传到你自己的 R2 存储桶，以链接形式交给 Instagram，并在几秒后被删除。

在 Cloudflare 控制台 → R2 中：

1. 创建一个存储桶。

2. 打开它 → 设置 → 公开开发 URL → 启用。复制该 URL。存储桶必须是公开的，否则 Meta 无法获取照片。

3. 管理 API 令牌 → 创建 API 令牌，范围限定为该存储桶，权限为对象读写。密钥只显示一次——请立即复制。

4. 可选但建议：添加生命周期规则，在 1 天后删除对象。集成本身会删除每张照片；此规则是兜底措施。

如果你只需要阅读，可以跳过整个步骤。 account_pulse、post_insights、activity 和 dm_thread 都不需要存储桶。只有 create_post 和 schedule_post 需要。

4. 为服务器提供密钥

在此文件夹中创建一个 .env 文件：

COMPOSIO_API_KEY=

# Cloudflare R2 — publishing only, leave blank if you are read-only
R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET=
R2_PUBLIC_URL=

R2_ACCOUNT_ID 位于 Cloudflare R2 → 概览页面右上角。R2_PUBLIC_URL 是第 3 步中的公开开发 URL。

如果 VoiceOS 在设置字段中提示你输入这些值，以该提示为准；此文件仅作为独立运行服务器时的后备方案。

5. 安装到 VoiceOS

先退出 VoiceOS。 它会在内存中持有 config.json 并在退出时重写，因此在其运行期间写入的任何内容都会被静默丢弃——完全不会报错。如果检测到 VoiceOS 正在运行，安装程序会拒绝执行。

osascript -e 'quit app "VoiceOS"'
python3 install-into-voiceos.py
open -a VoiceOS

该命令将此文件夹复制到 ~/Library/Application Support/VoiceOS/custom-mcps/，并将密钥从第 4 步带入，同时注册该集成。仅使用 cp 是不够的——VoiceOS 还需要在 config.json 中写入两个条目（一个说明如何启动服务器，一个携带清单）。脚本会先备份 config.json。

--update 每次都会从清单重新推导 confirmTools。这一点比看起来更重要：它是 VoiceOS 用来决定哪些工具需要确认卡片的列表。如果重命名后残留了过期的条目，帖子可能会在没有任何确认卡片的情况下发布。

6. 连接你的账户

说 "我的 Instagram 怎么样了？" 如果尚未连接 Instagram，你会收到一张连接 Instagram 卡片，上面带有 OAuth 链接。批准一次即可完成设置。

如果卡片显示账户是个人账户，请返回本页顶部的说明框进行转换。

工具

将照片拖到灵动岛上，然后一口气说出指令——"把这两张照片发到 Instagram 上，配文是关于黑客马拉松的"。两个发布工具都会在卡片上向你展示照片、配文以及（对于定时发布）确切时间，然后才会真正发布。

你的照片如何处理

值得一读，因为有一个环节会让人意外。

1. 照片会在你的 Mac 上通过 sips（macOS 内置工具）转换为 JPEG。Instagram 不接受其他格式。

2. 照片会上传到你的 R2 存储桶，使用一个随机且不可猜测的名称，并且仅在几秒内可公开读取。这是不可避免的：Meta 的爬虫是匿名的，无法登录，因此公开 URL 是 Instagram 获取照片的唯一方式。

3. Instagram 获取照片并发布帖子。

4. 文件会从存储桶中删除——无论成功还是失败，都在 finally 块中执行。第 3 步中的生命周期规则是兜底措施。

存储桶是你的。没有任何内容存储在他人的服务器上，此集成也不会保留你的照片副本。

定时帖子在你的 Mac 上运行，而不是在 Instagram 的服务器上——Instagram 没有调度 API。macOS 的 launchd 定时器会在你指定的分钟数后唤醒并发布。因此 Mac 必须处于开机且唤醒状态。如果到时间时 Mac 处于关机状态，帖子会被记录为未发布，而不是延迟数小时后才发布；instagram_activity 会在下次你询问时告诉你。

不在 v1 中

提前说明，以免你白费功夫：

• 发送私信。 Meta 通过 Composio 的共享 Instagram 应用阻止 API 私信发送——即使 24 小时窗口明确开启，它也会返回"超出允许窗口"的错误。此集成读取私信，但无法发送。请直接在 Instagram 应用中回复。

• 回复评论。 同样的传输层限制。

• 视频和 Reels。 仅支持照片和照片轮播图。视频发布需要可断点续传的上传路径，此版本不具备。

• 快拍。 工具包未开放此功能。

• 定时超过 24 小时。 这个上限是刻意为之：每多一小时，就多一种方式让延迟任务在无人可见之处腐烂——照片被删除、密钥被轮换、连接被撤销。

• 读取其他账户。 仅限你已连接的账户。

故障排查

开发

bun install
bun test          # 224 unit and failure-injection tests
bunx tsc --noEmit -p tsconfig.json

测试旨在保护三条规则，编辑前值得了解：

• stdout 是 MCP 的通信线路。 发布代码中只要有一个 console.log，VoiceOS 就无法解析 JSON-RPC 流，集成会从路由中静默消失，直到应用重启。所有日志都通过 console.error 输出；stdoutGuard.ts 是 server.ts 中的第一个导入，并为不遵守此规则的依赖重新绑定控制台。

• 绝不要用文件路径构建 shell 字符串。 照片来自用户将文件拖到灵动岛上。只使用 execFile(cmd, [args])——一个名为 holiday.png; rm -rf ~ 的文件对 sips 来说只是一个不透明的参数，test/media-paths.test.ts 对此有断言。

• 工具名称和描述必须与清单完全一致，双向都要匹配。server.ts 和 voiceos.integration.json 是同一份契约的两个副本。

confirmations/post_composer.html 是发布前卡片的唯一事实来源；清单中以字符串形式携带其副本。编辑 HTML 后必须重新生成副本，否则在不可逆发布前显示的卡片将是过期的版本。