Clawcall Free

语音通话服务免费版提供基础外呼能力。AI语音代理可拨号、对话、处理简单电话菜单， 并在通话结束后返回转录与结果。首次外呼可自动签发API密钥。 核心能力： - 基础外呼：POST /call 发起通话 - 轮询至终态：GET /call/{call_id} 至 lifecycle=finalized - 基础通话指令：task 字段编写简报 - 持久状态：~/.config/voicecall/key.json 保存API密钥 升级付费版专享：实时转接、并行通话活动、入呼保留号、个性/声音/问候全局配置、完整错误策略。 适用场景：简单的商家询价、信息查询、订单状态确认。 不适用于：紧急救助、需100%确定性的关键决策。

语音通话服务（免费版）

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

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

核心能力

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

指令解析与执行

解析用户指令,执行核心操作并返回处理结果。

输入: 用户提供操作指令和必要参数。

输出: 返回操作执行的结果。

• 执行指令解析与执行操作，处理输入数据并返回结果
• 验证执行结果，确认输出符合预期格式
• 参考指令解析与执行相关配置参数进行设置

数据处理与转换

处理输入数据,执行转换操作并输出结果。

输入: 用户提供操作指令和必要参数。

输出: 返回操作执行的结果。

• 执行数据处理与转换操作，处理输入数据并返回结果
• 验证执行结果，确认输出符合预期格式
• 参考数据处理与转换相关配置参数进行设置

结果验证与输出

验证处理结果的正确性,格式化输出并返回给用户。

输入: 用户提供操作指令和必要参数。

输出: 返回操作执行的结果。

• 执行结果验证与输出操作，处理输入数据并返回结果
• 验证执行结果，确认输出符合预期格式
• 参考结果验证与输出相关配置参数进行设置

能力覆盖范围

本skill还覆盖以下能力场景: 语音代理拨打美国、真实电话的免费版、支持基础外呼与轮、每日有限试用额度、语音通话服务免费、版提供基础外呼能、语音代理可拨号、处理简单电话菜单、并在通话结束后返、回转录与结果、首次外呼可自动签、API、核心能力、基础外呼、POST、call、发起通话、轮询至终态、GET、lifecycle、finalized、基础通话指令、字段编写简报、持久状态、config、voicecall、key、json、升级付费版专享、实时转接、并行通话活动、入呼保留号、问候全局配置、完整错误策略、适用场景、简单的商家询价、信息查询、订单状态确认、不适用于、紧急救助、确定性的关键决策。这些能力在上述核心功能中均有对应处理逻辑。

持久状态

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

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

json

{
  "api_key": "voicecall_sk_...",
  "user_phone_number": "[phone]"
}

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

依赖说明

运行环境

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

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

bash

export API_KEY="your_api_key_here"

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

核心能力（免费版）

1. 基础外呼

text

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

仅 to 与 task 必填。

响应包含：

json

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

若存在 api_key 则保存。

2. 轮询至终态

每 3 秒轮询一次：

text

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 判断目标是否达成。

命令参数说明

• -Api-Key: 命令参数,用于指定操作选项
• -Type: 命令参数,用于指定操作选项

命令参数说明

• -Api-Key: 命令参数,用于指定操作选项
• -Type: 命令参数,用于指定操作选项

命令参数说明

• -Api-Key: 命令参数,用于指定操作选项
• -Type: 命令参数,用于指定操作选项

命令参数说明

• -Type: 命令参数,用于指定操作选项
• -Api-Key: 命令参数,用于指定操作选项

示例

示例1：商家询价外呼

text

POST /call
X-Api-Key: voicecall_sk_abc123
{
  "to": "[phone]",
  "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：订单状态查询

text

POST /call
X-Api-Key: voicecall_sk_abc123
{
  "to": "[phone]",
  "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> 关联代理到账户。

错误处理

错误场景	原因	处理方式
invalid_phone	to 非美国 +1XXXXXXXXXX 格式	索要有效美国号码，校验11位数字与+1前缀
missing_fields	缺 to 或 task	补全收件号码与通话指令后重发
auth_required / invalid_api_key	API密钥缺失或失效	移除坏密钥，重新发起首次外呼获取新密钥
quota_exceeded / trial_exhausted	试用10次/10分钟耗尽	升级付费版解锁更高额度
network_error	网络抖动	等待后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令一次，二次失败提示用户执行ping命令测试网络连通性,检查防火墙和代理设置
通话 answered 但目标未达成	真人未提供所需信息	读转录识别阻断项，手动回拨或升级付费版用实时转接

常见问题

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%确定性的关键决策。