ai-phone README

项目的 README,来自 github.com/oxnw/ai-phone。合并为一个 markdown 文件:README.md。

ai-phone

An AI phone agent that runs on your computer.

Documentation · Architecture · AGPL-3.0

ai-phone setup running in a terminal

Installation

Requirement Details
Platform macOS on Apple Silicon. Intel Macs, Linux and Windows are not currently supported.
Memory 16 GB recommended for the default 4B model; 32 GB for 9B. Setup also offers a smaller 2B model for 8 GB systems.
Dependencies Git, Homebrew and uv. The installer handles Python packages and the native SIP library.
Storage Several GB for model downloads, depending on the models selected. Setup checks available disk space.
Phone connection A SIP address for direct calls; a Telnyx, Twilio or SignalWire account, or another SIP trunk, for telephone numbers. Carrier charges apply.
git clone https://github.com/oxnw/ai-phone.git
cd ai-phone
./scripts/install.sh

The installer adds ai-phone to ~/.local/bin. If it prints a PATH command, run that command in this terminal and add it to your shell’s startup file for future terminals. Then start setup:

ai-phone setup

To add the command to an existing installation, rerun ./scripts/install.sh from your updated checkout. Keep the checkout and its .venv in place; the command uses them from any directory.

Setup lets you choose incoming calls, outgoing calls, or both, then configures the model, line and voice. It recommends a local model based on detected RAM and downloads the required weights. Use ai-phone setup --plain for plain prompts. For SignalWire, buy a number in its portal first, then connect it in setup; see the SignalWire guide.

The current speech backends use MLX on Apple Silicon, even when a cloud model handles the conversation. Supporting Linux or Windows would require different speech backends and changes to installation and platform integration. The platform requirement applies to the computer running ai-phone; callers can use any phone or SIP client.

Usage

Start the daemon after setup:

ai-phone run

Keep it running while you want to receive calls. For outgoing calls only, start it when needed and stop it with Ctrl-C afterward. Setup does not install a background service.

From another terminal, give the phone agent instructions for a call:

ai-phone call +15555550100 --json \
  --prompt "Ask whether they have a table for two at eight tonight."

Replace the example number with the number you want to call. The command returns the transcript when the call ends. Every outgoing call starts with an AI disclosure. Incoming calls use the greeting and instructions you set during setup. English and one call at a time are currently supported.

For a free local test, enable incoming calls, select A SIP address in setup, and keep the name agent:

pjsua --local-port 5070 sip:[email protected]

Run setup again to change the voice, model, call directions or caller ID, then restart the daemon.

Agent integration

An agent with shell access can use relay mode to control each turn:

ai-phone call +15555550100 --relay --json
ai-phone say "Hi, I'd like to book a table for two." --json
ai-phone listen --json
ai-phone say "Eight o'clock, please." --json
ai-phone hangup --say "Thank you. Goodbye." --json

With no active call, listen --json waits for an incoming call and handles it in relay mode. Each command with --json returns one JSON object on stdout; call also sends progress events to stderr. An unanswered relay turn times out after 25 seconds by default. See the command reference for call IDs, transcript retrieval, timeouts and exit codes.

Models

Component Options
Speech recognition Parakeet, running locally through MLX.
Language model A local MLX model, your Claude Code or Codex subscription, or an OpenAI-compatible endpoint.
Voice Phonon with its bundled English voice, or Kokoro with American and British voices and adjustable speed.

Speech recognition and synthesis stay local. A remote language model receives the call's text, instructions and conversation history. An external agent's cloud provider also sees any transcripts passed to it. Phone audio travels over SIP/RTP; carrier charges and subscription limits apply.

Documentation

Install and setup have been checked from a fresh clone. Local call and interruption tests have run. Basic calls between SignalWire and Telnyx US numbers exchanged speech in both directions; see the verification details and remaining checks. Long-running SignalWire registration and end-to-end agent acceptance checks remain pending.

The latest published local benchmark (27 October 2026) measured 1.50 s median first-audible response under heavy memory pressure; it missed the one-second target. Full conditions and earlier results are documented.

License

AGPL-3.0-or-later. The bundled PJSIP interface files use GPLv2-or-later; see the license notes.

ai-phone (oxnw/ai-phone)

正在搜索数据库…

这是什么?ai-phone 是一个运行在你自己电脑上的 AI 电话代理,它利用本地语音识别和语音合成,加上可配置的语言模型,接听和拨打 SIP 电话。
怎么把它跑起来?克隆仓库后运行设置向导。向导会检测你的内存,推荐本地模型,下载模型权重,并配置你的线路、语音和呼叫方向;之后启动守护进程即可开始处理来电。
在设置前需要先安装什么?你的机器上需要有 Git、Homebrew 和 uv;安装程序本身会处理 Python 包和原生 SIP 库。
能在所有 Mac 上运行吗?其他操作系统呢?目前只支持搭载 Apple Silicon 芯片的 macOS。Intel 芯片的 Mac、Linux 和 Windows 无法使用,因为语音后端依赖 MLX。
它到底怎么接入真实的电话号码?它使用 SIP:你可以用直接的 SIP 地址免费测试,也可以接入你自己的 SIP 中继线、Telnyx 或 Twilio 账户来获得真实电话号码,但会产生运营商费用。
需要多少内存和存储空间?默认的 4B 模型推荐 16 GB 内存(9B 选项需要 32 GB),此外还提供较小的 2B 模型,适用于 8 GB 内存的机器;模型下载需要占用好几 GB 的磁盘空间。
我的通话数据会去哪里?语音识别和语音合成始终在你的 Mac 本地完成。但如果你选择远程语言模型(Claude Code、Codex 或兼容 OpenAI 的接口),该服务提供方会收到通话的文本、指令和对话历史。
它支持哪些语言模型和语音选项?对话可以使用本地 MLX 模型、你的 Claude Code 或 Codex 订阅,或任何兼容 OpenAI 的接口;语音方面可以使用 Phonon 内置的英语语音,或 Kokoro,并可调节美式/英式口音和语速。
编程代理能直接接管通话吗?可以。中继模式允许具有 shell 访问权限的代理接听电话,并自行驱动每一轮对话;带 --json 参数的命令会以结构化 JSON 返回通话 ID、转写文本、超时信息和退出码。
通话时它的响应有多快?最近一次测量结果显示,在内存压力较大的情况下,首次可听响应的中位时间为 1.50 秒,未达到项目设定的一秒目标。
它能同时处理多少通电话或支持几种语言?一次只能处理一通电话,目前仅支持英语对话。
作者
oxnw
大小
2.3 MB
星标
463
更新
提交Nov 02
时长
22天
提交 · 90 天