ai-phone이란?
ai-phone은 컴퓨터에서 실행되는 AI 전화 에이전트입니다. 수신 전화를 받고, 발신 전화를 걸며, 작성된 지침에 따라 대화를 진행하고, 외부 에이전트와 통합할 수 있도록 단계별 명령을 제공합니다.
현재 릴리스는 Apple Silicon 기반 macOS용으로 설계되었습니다. 대화형 언어 모델이 원격에서 실행되는 경우에도 음성 인식과 음성 합성은 MLX를 통해 로컬에서 처리됩니다. ai-phone을 호스팅하는 컴퓨터는 지원되는 Mac이어야 하지만, 발신자는 모든 전화기나 SIP 클라이언트를 사용할 수 있습니다.
주요 기능
- 수신 및 발신 전화: 설정 중 한 방향만 구성하거나 두 방향을 모두 활성화할 수 있습니다.
- 로컬 음성 처리: 음성 인식과 음성 합성은 Mac에서 처리됩니다.
- 유연한 언어 모델: 로컬 MLX 모델, Claude Code 또는 Codex 구독, OpenAI 호환 엔드포인트를 사용할 수 있습니다.
- SIP 및 전화 연결: 직접 SIP 주소로 테스트하거나 SIP 트렁크, Telnyx 계정 또는 Twilio 계정에 연결해 전화번호를 사용할 수 있습니다.
- 명령줄 자동화: 프롬프트로 전화를 시작하고 결과 트랜스크립트를 받을 수 있습니다.
- 릴레이 모드: 다른 셸 사용 가능 에이전트가 대화의 각 차례를 제어하도록 할 수 있습니다.
- 음성 선택: 기본 제공 영어 음성이 포함된 Phonon 또는 미국식·영국식 음성과 속도 조절을 지원하는 Kokoro를 사용할 수 있습니다.
ai-phone은 현재 영어와 동시 통화 1건만 지원합니다.
요구 사항
지원 플랫폼
Apple Silicon이 탑재된 Mac이 필요합니다. 음성 백엔드가 MLX에 의존하고 설치 과정에 플랫폼별 통합 기능이 포함되어 있으므로 Intel Mac, Linux, Windows는 현재 지원되지 않습니다.
메모리 및 저장 공간
- 8GB RAM: 설치 과정에서 더 작은 2B 모델을 제공합니다.
- 16GB RAM: 기본 4B 모델에 권장됩니다.
- 32GB RAM: 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 클라이언트를 루프백 주소의 에이전트에 연결하므로, 전화 서비스 제공업체를 구성하기 전에 기본 수신 전화 흐름을 검증할 수 있습니다.
릴레이 모드로 통화 제어
릴레이 모드는 셸 액세스 권한이 있는 외부 에이전트를 위한 기능입니다. 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를 통해 전송됩니다.
고급 구성 팁
요구 사항이 변경되면 설정 다시 실행
음성, 모델, 활성화할 통화 방향 또는 발신자 ID를 변경하려면 설정을 다시 실행하세요.
uv run ai-phone setup구성을 변경한 후 데몬을 다시 시작해야 새 설정이 적용됩니다.
통신사를 추가하기 전에 로컬 SIP로 시작
먼저 루프백 SIP 테스트로 에이전트를 검증하세요. 로컬 통화가 작동하면 일반 전화번호가 필요한 경우 SIP 트렁크, Telnyx 또는 Twilio를 구성하세요. 네트워크 관련 문제는 프로젝트의 NAT 체크리스트를 확인하세요.
사용 가능한 메모리에 맞는 모델 선택
가장 큰 모델을 자동으로 선택하기보다 설정 과정에서 RAM을 기준으로 제안하는 모델을 따르세요. 2B 옵션은 메모리가 적은 시스템을 위한 것이며, 기본 4B 및 더 큰 9B 모델은 더 많은 메모리가 필요합니다.
현재 지연 시간과 테스트 상태 고려
README에 따르면 최신 로컬 실행에서 메모리 압박이 큰 환경의 첫 가청 응답 중앙값은 1.50초였으며, 이는 프로젝트의 1초 목표를 충족하지 못했습니다. 로컬 통화 및 끼어들기 테스트는 실행되었지만, 실제 통신사 및 에이전트 종단 간 승인 검사는 아직 진행되지 않았습니다. 배포 준비 상태를 평가할 때는 공개된 측정 결과와 지연 시간 기록을 확인하세요.
상세 참조 문서 사용
- 회선, 착신 전환, 발신자 ID, 모델 및 CLI 명령어는 사용 가이드를 참조하세요.
- 사용 가능한 설정은 구성 예시를 참조하세요.
- 구성 요소와 통화 흐름은 아키텍처 가이드를 참조하세요.
- 네트워크 구성은 NAT 체크리스트를 참조하세요.
라이선스 고려 사항
ai-phone은 AGPL-3.0-or-later에 따라 라이선스가 부여됩니다. 기본 제공되는 PJSIP 인터페이스 파일은 GPLv2-or-later를 사용하므로, 소프트웨어를 배포하거나 통합하기 전에 프로젝트의 라이선스 참고 사항을 확인하세요.
결론
ai-phone은 Apple Silicon Mac에서 AI 전화 에이전트를 실행하기 위한 실용적인 명령줄 워크플로를 제공합니다. 설치한 후 모델과 SIP 회선을 구성하고 데몬을 시작한 다음, 통신사 통화를 시작하기 전에 로컬에서 테스트하세요. 자동화가 필요한 경우 릴레이 모드를 사용하면 JSON을 생성하는 셸 명령어를 통해 외부 에이전트가 턴 단위로 구조화된 제어를 수행할 수 있습니다.