什么是 ai-phone？
ai-phone 是一个运行在计算机上的 AI 电话代理。它可以接听来电、拨打电话、根据书面指令进行对话，并提供逐轮命令，以便与外部代理集成。
当前版本面向搭载 Apple Silicon 的 macOS 设计。即使对话语言模型运行在远程设备上，语音识别和语音合成也会通过 MLX 在本地运行。运行 ai-phone 的计算机必须是受支持的 Mac，但呼叫方可以使用任意电话或 SIP 客户端。
主要功能
- 接听和拨打电话：设置时可以配置其中一种，也可以同时启用两种功能。
- 本地语音处理：语音识别和语音合成均保留在 Mac 上运行。
- 灵活的语言模型：可以使用本地 MLX 模型、Claude Code 或 Codex 订阅，或兼容 OpenAI 的端点。
- SIP 和电话连接：可以使用直接 SIP 地址进行测试，也可以连接 SIP 中继、Telnyx 账户或 Twilio 账户来使用电话号码。
- 命令行自动化：使用提示启动通话，并接收通话生成的转录文本。
- 中继模式：允许另一个支持 Shell 的代理控制每一轮对话。
- 语音选择：可以使用自带英语语音的 Phonon，或使用提供美式和英式语音并支持调节速度的 Kokoro。
ai-phone 目前支持英语，并且一次只能进行一个通话。
要求
支持的平台
你需要一台搭载 Apple Silicon 的 Mac。目前不支持 Intel Mac、Linux 和 Windows，因为语音后端依赖 MLX，安装过程还包含特定于平台的集成。
内存和存储空间
- 8 GB 内存：安装设置会提供较小的 2B 模型。
- 16 GB 内存：建议使用默认的 4B 模型。
- 32 GB 内存：建议使用 9B 模型。
- 存储空间：为下载的模型权重预留数 GB 空间。安装设置会检查可用磁盘空间。
软件和电话连接
继续操作前，请安装 Git、Homebrew 和 uv。安装程序会管理所需的 Python 软件包和原生 SIP 库。
通话时，可以使用 SIP 地址进行直接连接，或提供你自己的 SIP 中继、Telnyx 账户或 Twilio 账户。可能会产生运营商费用，并受订阅限制影响。
安装 ai-phone
克隆代码仓库，进入其目录，运行安装程序，然后启动交互式设置：
git clone https://github.com/oxnw/ai-phone.git
cd ai-phone
./scripts/install.sh
uv run ai-phone setup设置过程会询问你是否需要接听来电、拨打电话，或同时启用两者。随后，它会配置语言模型、电话线路和语音。对于本地模型，设置程序会根据检测到的内存推荐一个选项，并下载所需的模型权重。
如果你的终端不适合使用标准交互式提示，请使用纯文本模式：
uv run ai-phone setup --plain启动电话守护进程
设置完成后，从代码仓库目录启动守护进程：
uv run ai-phone run想要接听电话时，请保持此进程运行。仅拨打电话时，请在拨打前启动它，并在完成后使用 Ctrl-C 停止。
设置过程不会安装后台服务。设置完成后或重启计算机后，你必须自行启动守护进程。
拨打电话
保持守护进程运行，并在代码仓库中打开另一个终端。使用 call 加上目标号码和描述任务的提示：
uv run ai-phone call +15555550100 --json \
--prompt "Ask whether they have a table for two at eight tonight."将 +15555550100 替换为你要拨打的号码。通话结束后，该命令会返回转录文本。每个拨出的电话都会以 AI 身份披露开场。
来电则会使用设置过程中保存的问候语和指令。
运行免费的本地 SIP 测试
你可以在不通过运营商拨打电话的情况下进行本地测试。运行设置程序，启用来电，选择 A SIP address，并保留默认名称 agent。在 ai-phone 守护进程运行时，执行：
pjsua --local-port 5070 sip:agent@127.0.0.1这会将本地 SIP 客户端连接到环回地址上的代理，让你在配置电话服务商之前验证基本的来电流程。
使用中继模式控制通话
中继模式面向具有 Shell 访问权限的外部代理。外部代理不必为整个对话向 ai-phone 提供一个提示，而是可以发起通话、讲话、聆听，并在每次响应后决定下一步操作。
启动中继通话
uv run ai-phone call +15555550100 --relay --json逐轮讲话和聆听
uv run ai-phone say "Hi, I'd like to book a table for two." --json
uv run ai-phone listen --json
uv run ai-phone say "Eight o'clock, please." --json结束对话
uv run ai-phone hangup --say "Thank you. Goodbye." --json每个使用 --json 的命令都会向标准输出写入一个 JSON 对象。call 命令还会向标准错误输出写入进度事件，因此集成程序应分别处理这两个数据流。
如果当前没有进行中的通话，listen --json会等待来电，并以中继模式处理通话。默认情况下，未得到应答的中继轮次会在 25 秒后超时。有关通话 ID、转录获取、可配置超时时间和退出代码，请参阅代理命令参考。
选择模型和语音
语音识别
ai-phone 通过 MLX 在本地使用 Parakeet 进行语音识别。
对话模型
语言模型可以是本地 MLX 模型、你的 Claude Code 或 Codex 订阅，也可以是兼容 OpenAI 的端点。安装设置过程会帮助你配置所选选项。
语音合成
Phonon 提供捆绑的英语语音。Kokoro 提供美国英语和英国英语语音，并支持调节语速。
如果使用远程语言模型，它会接收通话文本、指令和对话历史。如果外部代理使用云服务提供商，该提供商也可能接收发送给它的任何转录内容。语音识别和语音合成仍在本地进行，而电话音频则通过 SIP 和 RTP 传输。
高级配置提示
需求变化时重新运行设置
再次运行设置以更改语音、模型、启用的呼叫方向或主叫号码：
uv run ai-phone setup更改配置后重启守护进程，使新设置生效。
先使用本地 SIP，再添加运营商
先通过环回 SIP 测试验证代理。确认本地呼叫正常后，如需常规电话号码，再配置 SIP 中继、Telnyx 或 Twilio。对于网络相关问题，请查看项目的NAT 检查清单。
选择适合可用内存的模型
请遵循设置过程基于 RAM 给出的建议，不要自动选择最大的模型。2B 选项适用于内存较少的系统，而默认的 4B 和更大的 9B 模型需要更多内存。
考虑当前延迟和测试状态
README 报告称，在最新一次本地运行中，内存压力较大时首次可听响应的中位数为 1.50 秒，未达到项目设定的一秒目标。本地通话和打断测试已经运行，但实时运营商和端到端代理验收检查仍待完成。评估部署是否就绪时，请查看已发布的测量结果和延迟历史。
使用详细参考资料
许可证注意事项
ai-phone 采用AGPL-3.0-or-later许可证。其捆绑的 PJSIP 接口文件采用 GPLv2-or-later 许可证；在分发或集成该软件之前，请查看项目的许可证说明。
结语
ai-phone 为在 Apple Silicon Mac 上运行 AI 电话代理提供了实用的命令行工作流。安装后，配置模型和 SIP 线路，启动守护进程，并在拨打运营商电话之前进行本地测试。对于自动化场景，中继模式通过生成 JSON 的 shell 命令，为外部代理提供结构化的逐轮控制。