FaceTime（实验性）

将 FaceTime 连接到你的 OpenClaw 智能体，实现双向语音通话。该插件会自动接听来自已配置 handle 的来电，并在获得批准后让你的智能体呼叫你。实时语音提供商负责语音处理，而你的 OpenClaw 智能体负责需要工具或记忆的请求。

状态：实验性功能，默认禁用。 在同一个 Mac 上、同一个已登录用户会话中运行 Gateway 和原生辅助程序。请在 plugins.entries.facetime 下配置 FaceTime，而不是将其作为消息通道。

要求¶

• 一台运行 macOS 14.4 或更高版本的 Apple Silicon Mac。
• OpenClaw 2026.9.4 或更高版本。
• FaceTime 已在 Gateway Mac 上登录你的 Apple 账户。
• 已在 /Applications/Xcode.app 安装完整的 Xcode。
• FaceTime 插件及匹配的已签名原生配套程序。
• 一个具有有效凭据的实时语音提供商。
• 一个用于音频驱动器和 Mac 设置的管理员账户。

通话中的每个人都必须同意其音频由语音提供商处理。

请保持一对一通话。已配置的 handle 仅用于授权通话；该集成不会对每个说话人进行身份验证，也不会检查组呼的成员资格。请勿在具有智能体工具访问权限的通话中添加其他参与者。

安装插件和原生配套程序¶

在 Gateway Mac 上运行以下命令：

openclaw plugins install @openclaw/facetime
brew install openclaw/tap/openclaw-facetime

原生配套程序托管在 openclaw/openclaw-facetime。请使用其匹配的已签名版本。如果包或 formula 不可用，则在发布之前无法继续安装。

配置所有者身份¶

将你的 FaceTime 电子邮件地址或完整的国际电话号码添加到 ownerHandles。只有列出的 handle 才能使用该集成。每个列出的 handle 都具有所有者权限；没有访客层级。

将此内容合并到你的 OpenClaw 配置中。保留现有插件条目，如果你使用了 plugins.allow 列表，请将 facetime 添加到其中。

{
  plugins: {
    allow: ["facetime"],
    entries: {
      facetime: {
        enabled: true,
        config: {
          ownerHandles: ["owner@example.com", "+12065550123"],
          realtime: {
            provider: "openai",
            sessionKey: "main",
            toolPolicy: "owner",
          },
        },
      },
    },
  },
}

配置语音凭据¶

示例选择了 OpenAI 用于实时语音。语音凭据与你的文本智能体登录凭据是分开的。请配置所选实时语音提供商支持的凭据；仅拥有文本智能体的订阅可能无法提供语音访问权限。

提供商身份验证使用由 realtime.sessionKey 选定的智能体。对于 OpenAI，当未配置插件特定的 API 密钥时，该智能体的 API 密钥认证配置文件可以提供语音凭据。

对于由环境变量提供支持的 OpenAI API 密钥，请合并以下附加配置：

{
  secrets: {
    providers: {
      voiceenv: { source: "env", allowlist: ["OPENAI_API_KEY"] },
    },
  },
  plugins: {
    entries: {
      facetime: {
        config: {
          realtime: {
            providers: {
              openai: {
                apiKey: { source: "env", provider: "voiceenv", id: "OPENAI_API_KEY" },
              },
            },
          },
        },
      },
    },
  },
}

确保 OPENAI_API_KEY 对 Gateway 进程可用，而不仅仅是在你的终端中可用。你也可以复用已有的文件支持或其他受支持的 SecretRef，而无需将密钥存储在配置中。

选择智能体和工具访问权限¶

realtime.sessionKey 默认为 main，用于选择默认智能体。要选择其他智能体，请使用智能体限定的密钥，例如 agent:assistant:main，并将 assistant 替换为其配置的 ID。

每次通话使用独立的咨询会话。它可以继承所选源会话的上下文，而不会将通话轮次添加到该聊天中。智能体的工作区、工具凭据和审批策略仍然适用。

选择 realtime.toolPolicy：

无效的策略值会被拒绝。即使选择受限的工具策略，也请只将你自己的身份添加到 ownerHandles。

选择语音¶

显式设置 realtime.provider 以保持提供商选择的一致性。realtime.model 和 realtime.voice 是可选的；省略时，所选提供商会提供其默认值。如果你不想跟随提供商默认语音的变化，请显式设置受支持的语音。

如果省略 realtime.provider，已注册的实时提供商会自动选择提供商。这里的 OpenAI 只是一个示例，并非插件的默认设置。

准备 Mac¶

保存配置后，重启 Gateway 并运行设置：

openclaw gateway restart
openclaw gateway call facetime.setup --json

设置会报告所需的操作，并可启动原生辅助程序、打开通话应用并附加辅助程序。它不会拨打呼叫。

启用开发者工具访问¶

在交互式管理员会话中，运行：

sudo /usr/sbin/DevToolsSecurity -enable

允许调试器附加¶

原生辅助程序需要附加到 FaceTime 和 Phone。如果设置报告 SIP 调试限制阻止了附加：

1. 关闭 Mac。
2. 按住电源按钮，直到出现启动选项，然后选择选项。
3. 在 macOS 恢复中打开实用工具 > 终端。
4. 运行：

csrutil enable --without debug

1. 重新启动进入正常用户会话，并重新运行 facetime.setup。

这会禁用 SIP 的调试限制，同时保留其其他保护。不要禁用整个 SIP 或更改它来解决无关的身份验证或音频驱动程序错误。如果设置无法确定 SIP 状态，请在做出更改前运行 csrutil status 并检查结果。

请参阅 FaceTime 恢复与移除，以在移除集成时恢复标准安全设置。

授予权限并允许来电¶

在与运行 Gateway 相同的用户会话中完成 macOS 权限提示。如果预检报告应用音频捕获被阻止，请检查系统设置 > 隐私与安全性 > 屏幕与系统音频录制。

设置还会检查专注模式或通知设置是否会阻止来电。允许 FaceTime 来电通过你当前使用的专注模式，并且如果设置报告该设置阻止通知，请在共享或镜像显示器时启用通知。

安装音频驱动程序¶

运行仅限管理员的安装程序，并完成其管理员提示：

openclaw gateway call facetime.installDriver --json
openclaw gateway call facetime.driverStatus --json

安装程序使用 Xcode 在本地构建基于 BlackHole 的固定版本驱动程序。它会在构建前检查 Xcode 安装，并且不接受手动构建的驱动程序。如果安装失败，请按照报告的错误或驱动程序恢复步骤进行操作。

选择通话音频设备¶

在 FaceTime 中，以及在处理 FaceTime 音频通话的 Phone 中，选择：

• 麦克风： OpenClaw-Mic。
• 输出： 物理扬声器或耳机。

不要选择 OpenClaw-Mic、OpenClaw-Feed、BlackHole、聚合设备或多输出设备作为通话输出。

检查并激活¶

在完成 Mac 和驱动程序步骤后重新运行设置，然后检查音频就绪状态：

openclaw gateway call facetime.setup --json
openclaw gateway call facetime.preflight --json
openclaw gateway call facetime.status --json

在拨打电话之前解决报告的设置或预检错误。这些命令不会拨打任何人。setup 和 preflight 是管理员操作，可以执行实时设置和音频检查。status 可以检查非活动运行时，而无需打开应用、暂存辅助程序或启动通话音频。

验证你的第一次通话¶

从 FaceTime 音频通话开始：

1. 确认接收设备可用，且其用户同意接听该通话。
2. 让你的 agent 呼叫一个你配置的 owner 句柄，然后批准去电。
3. 在接收设备上接听，并检查你是否能听到问候语并进行双向通话。
4. 让 agent 挂断，或由你自己结束通话。

agent 使用 facetime_call，并在拨号前请求一次性批准。你也可以从配置的 owner 句柄呼叫 Gateway Mac 的 FaceTime 账户。

拨打和结束通话¶

要作为 Gateway 操作员直接拨号：

openclaw gateway call facetime.dial \
  --params '{"handle":"owner@example.com","mode":"audio"}' \
  --json

目标必须位于 ownerHandles 中。直接拨号需要 operator.write 访问权限，并计为明确的操作员操作。

要结束通话并检查其状态：

openclaw gateway call facetime.hangup --json
openclaw gateway call facetime.status --json

在开始另一个通话之前，请等待状态显示没有活动或挂起的通话。挂断确认意味着请求已发送，并不代表通话已经结束。

挂起的呼出拨号会保留通话槽位，因此在它完成或其取消得到确认之前，来电不会自动接听。如果辅助程序断开连接或报告不确定的拨号结果，挂起状态将保持可见，直到 OpenClaw 协调该通话。

更新集成¶

更新插件和原生配套程序后，检查 facetime.driverStatus。如果驱动程序已过时，请在交互式管理员会话中更新它：

openclaw gateway call facetime.updateDriver --json

如果要升级原型配置，请运行 openclaw doctor --fix。Doctor 会将 whitelistHandles 迁移到 ownerHandles，并移除已停用的 helperHost、helperPort 和 realtime.brain 设置。

移除集成¶

结束所有进行中的通话，然后运行：

openclaw gateway call facetime.uninstall --json
openclaw plugins disable facetime

按照 FaceTime 恢复与移除 重启 Apple 通话应用，检查音频设备已移除，并恢复 SIP。

限制¶

• 一次只能有一个受管通话。
• 仅支持 FaceTime 通话。蜂窝网络、Wi-Fi 通话/PSTN、紧急呼叫和无法识别的通话类型都会被拒绝，即使号码与 owner 句柄匹配也是如此。
• 从 FaceTime 音频通话开始。视频和由 Phone 主持的 FaceTime 音频仍处于实验阶段，在不同 macOS 版本上可能表现不同。
• 使用 agent 工具的请求可能比普通语音回复花费更长时间。
• 没有 FaceTime 特定的实时模型回退；提供程序的行为和默认值来自所选的实时提供程序。

故障排除¶

在共享日志之前，删除账户标识符、凭据和私密对话内容。

相关¶

• 配置参考
• FaceTime 恢复和移除
• 插件管理
• 密钥