better-call-claude

Better Call Claude

通过语音通话、SMS 和 WhatsApp 与 Claude Code 双向通信。
用手机呼叫 Claude 以启动任务，并在 Claude 需要输入或想要分享状态时接收回拨。

📞 “嘿，Claude，重构身份验证模块，完成后或需要我做决定时给我打电话。”

[20 分钟后，手机响起]

🤖 “我已完成重构，但发现了一个安全问题。要我现在修复，还是创建一个工单？”

💬 也可以通过 SMS/WhatsApp：

你：“Claude，部署进展如何？”

Claude：“部署完成。已更新 3 项服务，所有健康检查均已通过。”

功能

• 📱 呼入电话 - 用手机呼叫 Claude Code 以启动任务
• 📲 呼出电话 - Claude 会在完成、遇到阻碍或需要做决定时给你打电话
• 💬 SMS 消息 - 与 Claude 收发短信
• 📱 WhatsApp - 完整的 WhatsApp Business 集成
• 🔄 跨渠道上下文 - 从语音开始，并在 WhatsApp 上无缝继续
• 🔗 持久会话 - Claude 会保持运行，等待 WhatsApp 消息
• 🔒 安全传输 - 使用 Tailscale Funnel，并提供引导式自动设置
• 🗣️ 自然对话 - 在所有渠道中进行多轮交互
• 🔧 工具组合 - Claude 在通信时也可以使用其他工具
• ⚡ 自动更新 Webhook - URL 变更时自动更新 Twilio Webhook
• 🆓 通过 Baileys 免费使用 WhatsApp - 使用个人 WhatsApp，零 API 费用，无需商业验证
• ⌚ 随处可用 - 手机、智能手表或任何设备

⚠️ 测试状态

渠道	提供商	状态
语音	Twilio	✅ 已测试，可用
WhatsApp	Twilio Sandbox	✅ 已测试，可用
SMS	Twilio	⏳ 等待 A2P 10DLC 验证
语音	Telnyx	🔬 尚未测试
SMS	Telnyx	🔬 尚未测试
WhatsApp	Telnyx	🔬 尚未测试
WhatsApp	Baileys（免费）	🔬 新功能，欢迎测试

欢迎贡献，测试其他提供商与渠道的组合！

快速开始

1. 选择你的设置方式

只想使用 WhatsApp？ 跳转至 选项 C：Baileys——无需账户、无需 API 密钥，完全免费。

2. 设置电话服务提供商

git clone https://github.com/sns45/better-call-claude
cd better-call-claude
bun install

bun run baileys:pair

{
  "mcpServers": {
    "better-call-claude": {
      "command": "bun",
      "args": ["run", "/path/to/better-call-claude/src/index.ts"],
      "env": {
        "BETTERCALLCLAUDE_WHATSAPP_PROVIDER": "baileys",
        "BETTERCALLCLAUDE_USER_PHONE_NUMBER": "+1234567890"
      }
    }
  }
}

{
  "env": {
    "BETTERCALLCLAUDE_PHONE_PROVIDER": "twilio",
    "BETTERCALLCLAUDE_WHATSAPP_PROVIDER": "baileys",
    "BETTERCALLCLAUDE_PHONE_ACCOUNT_SID": "your-account-sid",
    "BETTERCALLCLAUDE_PHONE_AUTH_TOKEN": "your-auth-token",
    "BETTERCALLCLAUDE_PHONE_NUMBER": "+15551234567",
    "BETTERCALLCLAUDE_USER_PHONE_NUMBER": "+15559876543",
    "BETTERCALLCLAUDE_OPENAI_API_KEY": "sk-..."
  }
}

如果使用仅 Baileys 模式（选项 C），请跳过此步骤。Baileys 不需要 Webhook。

Tailscale Funnel 可提供免费、稳定的公开 URL，用于接收电话服务提供商发送的 Webhook。

为什么选择 Tailscale？ 免费且不限量的隧道、稳定的 URL（没有随机子域名）、企业级安全性。

路径： Better Call Claude 使用 /bcc 路径（例如：https://your-hostname.ts.net/bcc），以避免与其他服务冲突。

首次设置（自动化）：

首次启动 MCP 服务时，它会引导你完成设置：

1. 安装 Tailscale（如果尚未安装）：

   # macOS
   brew install tailscale
   
   # Linux
   curl -fsSL https://tailscale.com/install.sh | sh
   

2. 进行身份验证 - 服务将自动运行 tailscale up 并打开浏览器

3. 启用 Funnel - 访问终端中显示的 URL，在你的 tailnet 上启用 Funnel（管理员仅需设置一次）

就这么简单！服务会自动处理其余设置。

4. 安装 Better Call Claude

# Quick start with bunx (recommended)
bunx better-call-claude

# Or install globally
bun install -g better-call-claude
better-call-claude

5. 添加到 Claude Code

添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "better-call-claude": {
      "command": "bunx",
      "args": ["better-call-claude"],
      "env": {
        "BETTERCALLCLAUDE_PHONE_PROVIDER": "telnyx",
        "BETTERCALLCLAUDE_PHONE_ACCOUNT_SID": "your-connection-id",
        "BETTERCALLCLAUDE_PHONE_AUTH_TOKEN": "your-api-key",
        "BETTERCALLCLAUDE_PHONE_NUMBER": "+15551234567",
        "BETTERCALLCLAUDE_USER_PHONE_NUMBER": "+15559876543",
        "BETTERCALLCLAUDE_OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

注意： 首次运行时会自动设置 Tailscale。如有需要，服务会引导你完成安装和身份验证。

重启 Claude Code。完成！

环境变量

必需变量

Baileys（免费 WhatsApp）

仅 Baileys 模式： 当 WHATSAPP_PROVIDER=baileys 且未设置 Twilio／Telnyx 凭据时，只需设置 USER_PHONE_NUMBER。不需要 Tailscale，也不需要 OpenAI 密钥。

Tailscale（可选）

可选变量

使用方法

语音通话

你 → Claude（呼入电话）

用个人手机拨打你的 Telnyx／Twilio 电话号码：

📱“嘿，Claude，我需要你为支付模块编写单元测试。完成后给我打电话。”

Claude 会确认收到并开始处理。完成后，它会回拨给你。

Claude → 你（呼出电话）

Claude 需要你提供意见时，可以主动发起通话：

🤖“我为缓存层找到了 3 种不同方案。要我给你讲讲，方便你做选择吗？”

通话中的语音指令

• “挂断”或“再见” - 结束通话
• “等一下” - Claude 会等待你继续
• “继续” - Claude 继续执行任务
• “取消” - 中止当前操作

SMS 消息

你 → Claude（呼入 SMS）

向你的 Telnyx／Twilio 号码发送短信：

💬“嘿，Claude，部署进展如何？”

Claude 会通过 SMS 回复：

🤖“部署已完成 80%。正在运行集成测试。预计还需 5 分钟。”

Claude → 你（外发短信）

Claude 可以向你发送文本更新：

🤖 “auth.ts 第 42 行构建失败。回复‘fix’以自动修复，或回复‘skip’以继续。”

WhatsApp

你 → Claude（接收 WhatsApp 消息）

向你的企业号码发送 WhatsApp 消息：

💬 “显示过去一小时的错误日志”

Claude 会在 WhatsApp 中回复：

🤖 “发现 3 个错误：\n1. 14:32 连接超时\n2. 14:45 身份验证失败\n3. 15:01 触发速率限制\n\n需要我调查其中任何一个吗？”

Claude → 你（外发 WhatsApp 消息）

Claude 可以发送内容丰富的 WhatsApp 消息：

🤖 “代码审查已完成！发现 2 个问题：\n• 第 23 行：未使用的变量\n• 第 67 行：缺少错误处理\n\n回复‘fix’以自动修复，或回复‘details’查看更多信息。”

跨渠道上下文

通过语音开始一项任务，然后无缝切换到 WhatsApp 继续——Claude 会记住所有内容。

示例流程

1. 致电 Claude：

   📞 “嘿 Claude，以开发模式运行待办事项应用，然后我们切换到 WhatsApp 继续”

2. Claude 启动应用并进入 WhatsApp 监听模式：

   🤖 “待办事项应用正在端口 5173 上运行。通过 WhatsApp 给我发消息，提供更多指示。”

3. 发送 WhatsApp 消息：

   💬 “通过 localtunnel 暴露它，并将 URL 添加到允许的主机列表”

4. Claude 通过 WhatsApp 回复：

   🤖 “完成！Localtunnel URL：https://xyz.loca.lt - 我已将它添加到 vite.config.ts 的 allowedHosts 中”

5. 继续对话：

   💬 “公共 IP 是什么？这样我就能远程访问了”

   🤖 “你的公共 IP 是 203.0.113.42。请通过 https://xyz.loca.lt 访问应用”

用于触发 WhatsApp 监听的关键短语：

• “在 WhatsApp 上继续”
• “我们在 WhatsApp 上聊”
• “监听我的 WhatsApp 消息”

WhatsApp Sandbox（Twilio）

测试时，你可以使用 Twilio 的 WhatsApp Sandbox，无需完整的 WhatsApp Business 账号。

1. 前往 Twilio Console > Messaging > WhatsApp Sandbox
2. 向 Sandbox 号码（+1 415 523 8886）发送加入代码
3. 将 webhook URL 设置为 {your-tailscale-url}/bcc/webhook/twilio/whatsapp
4. 在配置中添加：

   "BETTERCALLCLAUDE_WHATSAPP_NUMBER": "+14155238886"
   

注意： Sandbox 每隔 72 小时需要重新加入。

工作原理

┌─────────────────┐         ┌──────────────────────────────────┐
│   Your Phone    │────────>│      Phone Provider              │
│  📞 Voice       │<────────│   (Telnyx/Twilio)                │
│  💬 SMS         │         │                                  │
│  📱 WhatsApp    │         │   • Voice API                    │
└─────────────────┘         │   • Messaging API                │
                            │   • WhatsApp Business API        │
                            └──────────────┬───────────────────┘
                                           │ webhooks
                                           ▼
                            ┌──────────────────────────────────┐
                            │     Transport Layer              │
                            │     (Tailscale Funnel)           │
                            └──────────────┬───────────────────┘
                                           │
                                           ▼
┌─────────────────┐         ┌──────────────────────────────────┐
│   Claude Code   │◄──────► │   Better Call Claude MCP Server  │
│   (your IDE)    │  stdio  │   (local, port 3333)             │
└─────────────────┘         │                                  │
                            │   • Voice handling               │
                            │   • SMS handling                 │
                            │   • WhatsApp handling            │
                            │   • Conversation management      │
                            └──────────────┬───────────────────┘
                                           │
                                           ▼
                            ┌──────────────────────────────────┐
                            │         OpenAI API               │
                            │    (Whisper STT + TTS)           │
                            │    (Voice calls only)            │
                            └──────────────────────────────────┘

通信流程

语音：

1. 接收： 你拨打电话 → 提供商 → Webhook → MCP 服务 → Claude Code
2. 外发： Claude Code → MCP 服务 → 提供商 → 你的手机响铃
3. 语音： 你的声音 → Whisper STT → 文本 → Claude → TTS → 音频播放

短信：

1. 接收： 你发送短信 → 提供商 → Webhook → MCP 服务 → Claude Code
2. 外发： Claude Code → MCP 服务 → 提供商 API → 短信已送达

WhatsApp：

1. 接收： 你发送消息 → 提供商 → Webhook → MCP 服务 → Claude Code
2. 外发： Claude Code → MCP 服务 → 提供商 API → WhatsApp 消息已送达

MCP 工具

语音工具

receive_inbound_call

接听并处理用户的来电。

initiate_call

向用户发起电话呼叫。

const { callId, response } = await initiate_call({
  message: "Hey! I finished the refactor. What should I work on next?"
});

continue_call

通过后续消息继续进行中的通话。

const response = await continue_call({
  call_id: callId,
  message: "Got it. Should I also add the caching layer?"
});

speak_to_user

直接向用户讲话，无需等待回复（用于确认）。

await speak_to_user({
  call_id: callId,
  message: "Let me search for that. One moment..."
});

end_call

结束正在进行的通话。

await end_call({
  call_id: callId,
  message: "Perfect, I'll get started. Talk soon!"
});

get_call_status

查看当前通话或最近通话的状态。

const status = await get_call_status({ call_id: callId });
// { state: "active", duration: 45, transcript: [...] }

消息工具

receive_inbound_message

检查收到的短信或 WhatsApp 消息。

const result = await receive_inbound_message({
  channel: "any",      // "sms", "whatsapp", or "any"
  timeout_ms: 5000     // How long to wait
});
// { success: true, channel: "sms", conversation_id: "...", message: "Deploy now" }

send_sms

向用户发送短信。

const result = await send_sms({
  message: "Build complete! 42 tests passed.",
  wait_for_reply: true,
  timeout_ms: 180000
});
// { success: true, conversation_id: "...", reply: "Great, deploy it" }

send_whatsapp

向用户发送 WhatsApp 消息。

const result = await send_whatsapp({
  message: "Found 3 issues in code review:\n• Issue 1\n• Issue 2\n• Issue 3",
  wait_for_reply: true
});
// { success: true, conversation_id: "...", reply: "Fix issue 1 first" }

reply_to_conversation

回复现有对话（适用于语音、短信或 WhatsApp）。

const result = await reply_to_conversation({
  conversation_id: "abc-123",
  message: "Got it, fixing issue 1 now.",
  wait_for_reply: false
});

get_conversation_history

获取任意对话的完整消息历史记录。

const history = await get_conversation_history({
  conversation_id: "abc-123"
});
// { success: true, channel: "whatsapp", messages: [...], state: "active" }

费用

语音通话

典型语音对话： ~$0.03-0.05/分钟

SMS

典型 SMS 往来： ~$0.01-0.02/次

WhatsApp

典型 WhatsApp 往来： 免费（Baileys）或 ~$0.01-0.02（Twilio/Telnyx）

基础设施

安全注意事项

Tailscale Funnel 安全性

• Funnel 会创建一个公共端点，但流量通过 Tailscale 的安全网络路由
• 支持面向企业使用的 SSO/SCIM 集成
• 可在 Tailscale 管理控制台查看审计日志
• 默认验证 webhook 签名

通用

• 从不记录电话号码
• 通话转录内容是临时的（重启时清除）
• 使用环境变量，切勿将凭据硬编码

能力证明

此代码库在根目录提供了一个 smithmark 能力清单 smithmark.yaml。这是一个“信任即代码”的声明，列出了此服务进程之外涉及的所有内容：它向其发送请求的网络主机（Twilio、Telnyx、OpenAI、WhatsApp/Baileys 基础设施，以及由启动的 claude 子进程间接访问的 api.anthropic.com）、它读写的文件系统路径（Baileys 身份验证状态、启动调试日志）、它执行的二进制文件（claude、tailscale、which、open、sudo）、它读取的环境变量，以及它处理的密钥类型（Twilio、Telnyx 和 OpenAI API 密钥）。

每次发布 GitHub 版本时，.github/workflows/smithmark-attest.yml 都会对已发布的 npm 压缩包生成 无密钥 Sigstore 证明：GitHub 的 OIDC 令牌会交换为短期 Fulcio 签名证书，证明由该证书签名，签名记录在公开的 Rekor 透明度日志中。整个过程不涉及签名密钥或机密。生成的 smithmark-attestation.sigstore.json 会附加到 GitHub 发布版本中。

使用以下命令验证已发布的版本：

smithmark verify [email protected] \
  --certificate-identity "https://github.com/sns45/better-call-claude/.github/workflows/smithmark-attest.yml@refs/tags/v3.1.1" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

（将 v3.1.1 替换为实际的发布标签）

smithmark.yaml 是此服务能力范围的权威声明。smithmark lint（以及严格模式下的 verify）有意不感知主机：它会将每个网络/执行/文件系统调用点都标记为通用的“未声明”发现项，无论清单在主机级别声明了什么，因此任何访问网络的真实 MCP 服务都会报告提示性发现项。这些发现项是预期的噪声，并不意味着清单已过时；应以以上清单为准。

故障排除

语音问题

Claude 不接听来电

1. 检查 MCP 服务是否正在运行：claude --debug
2. 确认已在服务提供商控制面板中配置 webhook URL
3. 确保 Tailscale Funnel 已启用

无法拨打外呼

1. 确认 BETTERCALLCLAUDE_USER_PHONE_NUMBER 正确
2. 检查电话号码是否已通过服务提供商验证
3. 确保服务提供商账户余额充足

音频质量问题

1. 检查网络连接
2. 尝试更换 TTS 语音：BETTERCALLCLAUDE_TTS_VOICE=nova
3. 调整静音检测：BETTERCALLCLAUDE_STT_SILENCE_DURATION_MS=1000

SMS 问题

无法收到 SMS

1. 确认已在服务提供商控制面板中为你的电话号码启用 SMS
2. 检查是否已设置 SMS webhook URL：/webhook/telnyx/sms 或 /webhook/twilio/sms
3. 确认已将 Messaging Profile 分配给电话号码（Telnyx）

无法发送外发短信

1. 检查电话号码是否支持短信
2. 验证目标号码格式（E.164：+15551234567）
3. 检查服务商账户余额

WhatsApp 问题

未收到 WhatsApp 消息

1. 确认已在服务商门户中设置 WhatsApp Business
2. 检查 webhook URL：/webhook/telnyx/whatsapp 或 /webhook/twilio/whatsapp
3. 确保已完成 WhatsApp Business 验证

无法发送 WhatsApp 消息

1. 用户必须先给你发消息（WhatsApp 24 小时规则）
2. 检查 WhatsApp Business 审批状态
3. 验证消息模板是否合规（适用于主动发送的消息）

Baileys 问题

未显示二维码

二维码无法显示在 MCP 服务中（stdout 保留给 MCP 协议使用）。请单独运行配对脚本：

cd /path/to/better-call-claude
bun run baileys:pair

配对完成后，会保存会话，MCP 服务将自动连接。

“已配置 Baileys，但未找到会话”

运行 bun run baileys:pair，先配对 WhatsApp，然后重启 Claude Code。

WhatsApp 已退出登录

删除身份验证目录并重新配对：

rm -rf data/baileys-auth
bun run baileys:pair

未收到消息

1. 检查 Baileys 是否已连接（查看 stderr 中是否有 [Baileys] Connected）
2. 确保消息来自个人聊天（群组消息会被过滤）
3. 确认发送者不是关联账户本身（自己发送的消息会被过滤）

Tailscale 问题

“Tailscale 未运行”

1. macOS：从“应用程序”中打开 Tailscale 应用
2. Linux：sudo systemctl start tailscaled && tailscale up

“未启用 Funnel”

1. 访问终端中显示的 URL 以启用 Funnel
2. 或前往 https://login.tailscale.com/admin/acls 并添加 Funnel 功能

Funnel 已启动，但 webhook 无法正常工作

1. 检查 tailscale funnel status 是否显示 /bcc 指向你的端口
2. 验证电话服务商的 webhook URL 是否与 Tailscale URL 一致（包含 /bcc 路径）
3. 使用 curl https://your-hostname.ts.net/bcc/health 进行测试

开发

# Clone the repo
git clone https://github.com/sns45/better-call-claude
cd better-call-claude

# Install dependencies
bun install

# Run in development mode
bun run dev

本地测试

# Start the MCP server
bun run dev

# In another terminal, test with MCP inspector
npx @anthropics/mcp-inspector

技术栈

• 运行时：Bun - 快速的 JavaScript 运行时
• Web 框架：Hono - 轻量、快速的 Web 框架
• 电话：Telnyx / Twilio - 电话 API
• WhatsApp：Baileys - 免费的 WhatsApp Web 协议
• 语音：OpenAI Whisper - STT/TTS
• 传输：Tailscale Funnel - 公共 URL 隧道
• 协议：MCP - Model Context Protocol

贡献

欢迎提交 PR！请参阅 CONTRIBUTING.md 了解指南。

许可证

MIT