elevenlabs-twilio-memory-bridge

面向 ElevenLabs + Twilio 语音代理的个性化 Webhook 服务，支持持久化主叫方记忆。

功能说明

当来电接入您的 Twilio 号码时，ElevenLabs 原生集成将触发该 Webhook。本桥接服务会查询主叫方历史记录，加载长期记忆事实与每日上下文笔记，并将其与可定制的“灵魂/人格”模板融合，最终以系统提示词（system prompt）覆盖形式返回全部内容，使您的代理能在每次应答时携带完整上下文信息。

架构设计

• 不代理音频流 — ElevenLabs 与 Twilio 直接处理媒体传输
• 仅提供 Webhook 接口 — 每次呼入仅调用一次，用于注入上下文
• 基于文件的持久化存储 — 数据以 JSON 格式存于 ./data/ 目录，无任何外部依赖
• 兼容 OpenClaw — 支持任意与 OpenAI 兼容的 LLM 接口端点

接口端点

部署步骤

1. 克隆代码仓库，执行 pip install -r requirements.txt
2. 将 .env.example 复制为 .env，并填入密钥信息
3. 在 ElevenLabs 中配置代理，设置 Custom LLM 指向您的 OpenClaw 实例
4. 在代理的 Security 设置中启用 system prompt 与首条消息（first message）覆盖功能
5. 在 ElevenLabs 设置中填写 Webhook URL：https://your-domain/webhook/personalize
6. 在 ElevenLabs 控制台中导入您的 Twilio 号码
7. 运行服务：uvicorn app:app --host 0.0.0.0 --port 8000

必需的环境变量

• ELEVENLABS_API_KEY — 已限定作用域的 ElevenLabs API 密钥
• ELEVENLABS_AGENT_ID — 您的代理 ID
• OPENCLAW_API_BASE_URL — 您的 OpenClaw 实例地址
• PUBLIC_BASE_URL — 本服务对外可访问的公共 URL
• ADMIN_API_KEY — 管理接口认证所用密钥
• PHONE_HASH_SALT — 电话号码哈希加盐值。建议使用 openssl rand -base64 32 生成。修改该值将导致所有现有主叫方数据失效。
• WEBHOOK_SECRET — 用于 HMAC Webhook 验证的共享密钥。生产环境中必须设置。

可选的环境变量

安全机制

• 确定性电话号码哈希 — 存储前，电话号码使用 PHONE_HASH_SALT 作为密钥进行 HMAC-SHA256 哈希。更改 salt 将导致现有主叫方数据不可访问。
• 静态数据加密 — 当设置了 DATA_ENCRYPTION_KEY 时，记忆与笔记将通过 Fernet 加密；未配置时则以明文 JSON 形式存储。
• 强制 Webhook 验证 — 生产环境中必须设置 WEBHOOK_SECRET。若未配置该密钥，则拒绝所有 Webhook 请求（fail-closed 策略）。
• 请求频率限制 — 管理接口（/api/memory、/api/notes）限速为每分钟 30 次；Webhook 接口限速为每分钟 60 次。
• 文件锁机制 — JSON 文件的读写操作使用 POSIX 建议性锁（fcntl），防止并发访问下的竞态条件。
• 严格权限控制 — 数据目录（DATA_DIR）创建时权限设为 0o700；JSON 文件写入时权限设为 0o600。
• 仅从环境变量加载密钥 — 源码中不硬编码任何凭据。
• 适用于公开 GitHub 仓库 — 所有敏感配置均通过环境变量加载。

从 v1.1.x 升级至 v1.2.x 的迁移指南

v1.2.0 引入了破坏性安全变更：

1. PHONE_HASH_SALT 现为必需项 — 此前电话号码使用无盐 SHA-256 哈希；现强制要求使用带盐的 HMAC-SHA256。由于哈希密钥变更，升级后原有主叫方数据将无法访问。您需接受数据丢失并重新开始（v1.2.0 使用不同哈希算法）。

2. WEBHOOK_SECRET 现为必需项 — 此前开发环境可选；现要求所有环境均必须配置。未携带有效密钥的 Webhook 请求将被拒绝。

3. DATA_ENCRYPTION_KEY 为可选项，但强烈推荐启用 — 若已配置，所有新增的记忆与笔记将在静态状态下加密；已有未加密数据仍可正常读取。

迁移检查清单

1. 生成 salt：openssl rand -base64 32
2. 生成 Webhook 密钥：openssl rand -hex 32
3. 生成加密密钥（可选）：python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
4. 将上述全部值加入 .env 文件
5. 检查 CORS 配置 — ALLOWED_ORIGINS 默认现已禁用
6. 在 ElevenLabs Webhook 设置中更新 WEBHOOK_SECRET
7. 注意：v1.2.0 要求全新数据 — 现有主叫方会话将在首次来电时重建