AVA 实战：把 Asterisk/FreePBX 电话系统接入可自托管的 AI 语音 Agent
很多团队想把 AI 放进电话流程时，最先碰到的并不是「模型够不够聪明」，而是既有电话系统怎么接、语音链路如何排错、密钥与录音怎样留在自己的运行环境。直接把一个聊天接口接到 SIP 中继，通常会把音频传输、打断（barge-in）、播放回路和运营配置混在一起，后续很难维护。
AVA AI Voice Agent for Asterisk 是面向 Asterisk/FreePBX 的 MIT 许可证项目。它把电话侧与 AI 引擎连接起来：既能选择由单一供应商完成语音识别、推理和语音合成的完整语音 Agent，也能把 STT、LLM、TTS 组合成独立流水线。项目在 Hacker News 的展示帖中被描述为可自托管的 Asterisk/FreePBX AI 语音 Agent；截至本文核查时，仓库已有一千余 Star，最新 README 标注版本为 7.4.0。
本文不把它当成「一键替换人工客服」的承诺，而是从运维视角说明：什么问题适合用它、如何完成最小可验证部署，以及上线前应该检查哪些边界。
先选架构：完整 Agent 还是模块化流水线
AVA 的两种模型解决的是不同取舍。
- 完整 Agent：单个服务覆盖 STT、LLM 和 TTS。配置更少，适合希望优先降低接入复杂度、追求实时对话体验的场景。官方配置参考将 OpenAI Realtime、Deepgram Voice Agent 列为这类模式的示例。
- 模块化流水线：分别指定语音识别、语言模型和语音合成组件。它更适合需要替换某一环、控制成本，或希望把部分语音/模型能力放在本地处理的团队。
电话侧也要同时做选择。项目文档列出两条已验证路径：AudioSocket 使用 TCP 8090，ExternalMedia RTP 使用 UDP 18080。对于模块化流水线，官方将 downstream_mode: file 标为推荐且验证更充分的播放方式；对于完整 Agent，AudioSocket 搭配流式播放是文档中的已验证组合。不要只因为「流式」听起来更快就改配置：传输方式、供应商模式和播放模式需要作为一个组合测试。
从预检开始，而不是先填 API Key
下面命令来自项目 README，假设你已经有可用的 Docker Compose 主机和 Asterisk/FreePBX 环境。先克隆项目并运行预检；它会创建 .env 并生成 JWT_SECRET：
git clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git cd AVA-AI-Voice-Agent-for-Asterisk sudo ./preflight.sh --apply-fixes
然后仅启动管理界面容器：
docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui docker compose -p asterisk-ai-voice-agent logs admin_ui | grep -i password
首次启动时，管理员一次性密码会出现在容器日志中，登录后必须修改。管理界面默认监听本机的 3003 端口；若服务器可从外网或办公网访问，应该先用防火墙、VPN 或反向代理限制访问范围，再继续配置。这不是可选的「上线优化」，因为管理界面本身承载了供应商与 Agent 配置。
接下来运行交互式向导：
agent setup agent check agent config validate
agent setup 会读取基础配置与本地覆盖文件，发现当前安装中已定义的供应商或流水线，并把本地选择写入 config/ai-agent.local.yaml。这种把上游默认配置与本地运维覆盖分开的方式很实用：升级时不必把密钥和站点选择混进受 Git 追踪的主配置。
把电话路由指向受管理的 Agent
v7.4 的新路由模型以 AI_AGENT 选择后台管理的 Agent；旧的 AI_CONTEXT 仍是兼容别名。与其手写容易过期的拨号计划，不如先让 CLI 生成片段：
agent dialplan --agent sales
如果需要查看系统状态，可先启动 AI 引擎，再做健康检查：
docker compose -p asterisk-ai-voice-agent up -d --build ai_engine curl http://localhost:15000/health agent check --json
健康检查会覆盖 Docker/Compose、AI 引擎、挂载与网络、ARI 可达性和应用注册、传输匹配及配置等项目。它不能替代一通真实电话，但能在拨号计划上线前暴露大量「容器起来了、语音却走不通」的问题。
发生单通异常时，使用持久化的呼叫记录和日志做根因分析，而不是凭容器全局日志猜测：
agent rca --call--no-llm
这里的 --no-llm 会坚持使用确定性证据，适合自动化排障和事故复盘；如果使用本地 AI 服务器，还可以执行 agent check --local 验证 WebSocket、已加载的 STT/LLM/TTS 模型、GPU 状态以及语音识别和合成回路。
上线前的四个边界
第一，不要把 AI 能力与电话权限等同。为不同业务角色建立不同 Agent，并只给它们需要的转接目标、日历或语音信箱资源。项目 v7.4 的文档明确说明可以按 Agent 限制这些资源；全局禁用的工具优先于单个 Agent 的选择。
第二，把密钥与本地配置当作生产资产。.env、本地覆盖文件、Agent 数据库和呼叫历史都应进入备份范围；升级前先执行状态检查和备份，不要用强制重置覆盖现场配置。
第三，用真实通话验证回路。至少覆盖问候、连续对话、用户打断、工具调用（如有）、转接或结束语，以及网络短暂抖动。音频能接通并不代表播放和输入没有互相干扰。
第四，明确自动化的退出条件。预约、转接和留言可以自动化；涉及付款、敏感身份信息或高风险承诺时，应该把 Agent 设计为收集信息、给出说明或转交人工，而不是让模型自行扩权。
AVA 的价值不在于把电话系统「魔法化」，而在于给 Asterisk/FreePBX 环境提供一套可观察、可配置、可逐步验证的语音 AI 接入层。先用最小 Agent 跑通一条低风险呼叫链路，再扩展供应商、工具和本地推理，通常比从第一天就构建全自动呼叫中心更稳妥。