语音通话服务（免费版）

语音通话服务免费版让AI代理为用户拨打真实的美国电话。语音AI代理负责拨号、对话、处理简单电话菜单，并在通话结束后返回转录与结果。首次外呼可自动签发API密钥。

输入输出

输入: 用户提供目标电话号码（美国 +1XXXXXXXXXX 格式）、基础通话指令 task（含通话目标、已知事实、要问的问题、遇无人接听处理方式、回报要求）；首次外呼无需提供API密钥，响应自动签发并持久化。 输出: call_id 与 api_key（首次外呼自动签发并保存至 ~/.config/voicecall/key.json）、通话生命周期状态（queued → dialing → answered → finalized）、终态返回 outcome（电话网络结果）、talk_seconds（通话时长）、transcript（通话转录）。免费版不提供录音链接、实时转接、并行通话、入呼保留号、全局个性配置等高级能力（付费版专享）。

Base URL: https://api.voicecall.example

核心能力

电话代理只知道你作为 task 发送的通话指令。细节越相关越好。拨号前构建完整的简报，不要让用户提供你本可自行查询的公开/商业信息。

持久状态

在任何涉及语音通话服务的对话开始时，检查 ~/.config/voicecall/key.json 或宿主密钥库。若存在API密钥，作为 X-Api-Key 发送。

首次未鉴权的 POST /call 响应可能包含 api_key。立即保存：

{
  "api_key": "voicecall_sk_..",
  "user_phone_number": "+15559876543"
}

若用户提供新的语音通话服务API密钥，替换任何已保存的密钥。

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

API Key 配置

如需调用外部API，请参考环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY="your_api_key_here"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。

核心能力（免费版）

1. 基础外呼

POST /call
Content-Type: application/json
X-Api-Key: voicecall_sk_..

仅 to 与 task 必填。

响应包含：

{
  "call_id": "ba645d75-..",
  "status": "queued",
  "api_key": "voicecall_sk_."
}

若存在 api_key 则保存。

2. 轮询至终态

每 3 秒轮询一次：

GET /call/{call_id}
X-Api-Key: voicecall_sk_..

轮询直至 lifecycle = "finalized"。生命周期取值：queued、dialing、answered、finalized。

终态响应包含 outcome、talk_seconds、transcript。outcome 是电话网络结果，非任务成功。answered 的通话仍可能未达成用户目标。回报前先读转录。

3. 基础通话指令

task 是API字段名。像简报备忘录一样编写通话指令：

• 为谁拨号、如何自我介绍
• 通话目标
• 所有已知事实与参考细节
• 要问的问题
• 遇到语音信箱、无人接听、关门或转接时怎么办
• 要回报什么

4. 持久状态保存

~/.config/voicecall/key.json 保存API密钥与用户电话号码，跨会话复用。

使用流程

1. 检查持久状态：读 ~/.config/voicecall/key.json，若有 api_key 则作为 X-Api-Key 发送。
2. 侦察与准备：自行查找公开商家信息，仅向用户索取私有/决策细节。
3. 构建通话指令：编写 task，含目标、已知事实、问题、回报要求。
4. 发起外呼：POST /call，仅 to 与 task 必填。
5. 保存密钥：响应中的 api_key 立即持久化。
6. 轮询至终态：每 3 秒 GET /call/{call_id}，直至 lifecycle = "finalized"。
7. 回报结果：先给 outcome，再读 transcript 判断目标是否达成。

示例

示例1：商家询价外呼

POST /call
X-Api-Key: voicecall_sk_abc123
{
  "to": "+12125551234",
  "task": "询问该餐厅周五晚7点2人位是否可用。若可用询问可保留多久。遇语音信箱留言回拨+15559876543。回报可用性或替代时间"
}
响应：{"call_id":"ba645d75-..","status":"queued","api_key":"voicecall_sk_abc123"}
轮询：GET /call/ba645d75-..  → lifecycle: queued → dialing → answered → finalized
终态：outcome=answered, talk_seconds=42, transcript="周五7点2人位可用，可保留24小时"

示例2：订单状态查询

POST /call
X-Api-Key: voicecall_sk_abc123
{
  "to": "+18005551000",
  "task": "查询订单#A-9921的状态与预计送达时间。核验可能需订单号A-9921。回报当前状态与送达时间"
}

付费版专享能力

升级付费版解锁以下高级能力：

• 实时转接：通过 bridge_number 将用户桥接进通话，跳过等待、接通真人、处理身份核验。
• 并行通话活动：3-4路并行信息型外呼用于选项比较。
• 入呼保留号：配置保留号如何应答未来来电（需 Unlimited Reserve Plus + 活跃保留号）。
• 个性/声音/问候全局配置：voice（jessica/sarah/chris/eric）、personality、greeting 全局设置。
• 完整错误策略：reserved_number_required、inbound_plan_required、invalid_preferences、invalid_profile、invalid_handoff_number 等高级错误处理。
• 录音链接：终态响应包含 recording_url。
• 取消/挂断：POST /call/{call_id}/hangup 主动终止通话。
• 入呼历史轮询：GET /me/calls?direction=inbound 查看接到的电话。
• 账户关联：通过 https://voicecall.example/sign-in?token=<api_key> 关联代理到账户。

错误处理

常见问题

Q1：免费版试用额度如何？

新用户试用为 10 次通话与 10 分钟，以较晚结束者为准。试用通话仅在 finalized 且通话时长 ≥ 5 秒时才计数。额度用尽后需升级付费版。

Q2：电话代理知道什么？

电话代理只知道你作为 task 发送的通话指令。它不知道你的对话历史或未写入指令的上下文。细节越相关越好。

Q3：免费版支持实时转接吗？

不支持。实时转接（bridge_number）为付费版专享。免费版仅支持单向外呼与轮询。

Q4：能否并行拨打多处？

不能。并行通话活动为付费版专享。免费版仅支持串行单次外呼。

Q5：免费版能配置入呼应答吗？

不能。入呼保留号配置需 Unlimited Reserve Plus + 活跃保留号，为付费版专享。

Q6：如何升级到付费版？

参考 clawcall 付费版SKILL.md，解锁实时转接、并行活动、入呼保留号、全局个性配置、完整错误策略、录音链接、取消挂断、入呼历史与账户关联。

Q7：outcome 与任务成功有何区别？

outcome 是电话网络结果（如 answered），非任务成功。answered 的通话仍可能未达成用户目标。回报前必须读 transcript 判断。

已知限制

• 仅支持美国 +1XXXXXXXXXX 号码，不支持国际号码。
• 试用额度：10 次通话或 10 分钟，以较晚结束者为准；短于5秒不计。
• 不支持实时转接（bridge_number 为付费版专享）。
• 不支持并行通话活动（付费版上限 3-4 路）。
• 不支持入呼保留号配置（需 Unlimited Reserve Plus）。
• 不支持全局 voice/personality/greeting 配置（使用默认 jessica 声音）。
• 不提供录音链接（recording_url 为付费版专享）。
• 不支持主动取消/挂断（POST /call/{call_id}/hangup 为付费版专享）。
• 轮询间隔固定 3 秒。
• 不适用于紧急救助、医疗急救或需100%确定性的关键决策。

输出格式

{
  "success": true,
  "data": {
    "result": "语音通话服务-免费版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "clawcall"
    }
  },
  "execution_log": [
    "解析输入参数",
    "执行核心处理",
    "格式化输出结果"
  ],
  "error": null
}