---
slug: "clawcall-free"
name: "clawcall-free"
version: "1.0.0"
displayName: "语音通话服务-免费版"
summary: "AI语音代理拨打美国真实电话的免费版，支持基础外呼与轮询，每日有限试用额度。语音通话服务免费版提供基础外呼能力。AI语音代理可拨号、对话、处理简单电话菜单， 并在通话结束后返回转录与结果。首"
summary_zh: "AI语音代理拨打美国真实电话的免费版，支持基础外呼与轮询，每日有限试用额度。语音通话服务免费版提供基础外呼能力。AI语音代理可拨号、对话、处理简单电话菜单， 并在通话结束后返回转录与结果。首"
license: "MIT"
description: |-
  语音通话服务免费版提供基础外呼能力。AI语音代理可拨号、对话、处理简单电话菜单，
  并在通话结束后返回转录与结果。首次外呼可自动签发API密钥。
  核心能力：
  - 基础外呼：POST /call 发起通话
  - 轮询至终态：GET /call/{call_id} 至 lifecycle=finalized
  - 基础通话指令：task 字段编写简报
  - 持久状态：~/.config/voicecall/key.json 保存API密钥
  升级付费版专享：实时转接、并行通话活动、入呼保留号、个性/声音/问候全局配置、完整错误策略。
  适用场景：简单的商家询价、信息查询、订单状态确认。
  不适用于：紧急救助、需100%确定性的关键决策。
tags:
  - 通用办公
  - 语音通话
  - AI代理
  - 工具
  - 写作
  - 电商
  - api
  - task
  - api_key
  - call
  - answered
tools:
  - read
  - exec
  - write
homepage: ""
category: "Automation"
---
# 语音通话服务（免费版）

语音通话服务免费版让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` 发送的**通话指令**。细节越相关越好。拨号前构建完整的简报，不要让用户提供你本可自行查询的公开/商业信息。
#
## 快速开始

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

> 详细的输入输出格式请参考下方章节说明。

## 持久状态

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

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

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

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

## 依赖说明

### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
- **操作系统**: Windows / macOS / Linux

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

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

### 可用性分类
- **分类**: MD+EXEC（）

**API Key配置方式**:
```bash
export API_KEY="your_api_key_here"
```
配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。
## 核心能力（免费版）

### 1. 基础外呼

```
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 秒轮询一次：

```
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>` 关联代理到账户。

## 错误处理

| 错误场景 | 原因 | 处理方式 |
|:-----|:-----|:-----|
| `invalid_phone` | `to` 非美国 `+1XXXXXXXXXX` 格式 | 索要有效美国号码，校验11位数字与+1前缀 |
| `missing_fields` | 缺 `to` 或 `task` | 补全收件号码与通话指令后重发 |
| `auth_required` / `invalid_api_key` | API密钥缺失或失效 | 移除坏密钥，重新发起首次外呼获取新密钥 |
| `quota_exceeded` / `trial_exhausted` | 试用10次/10分钟耗尽 | 升级付费版解锁更高额度 |
| `network_error` | 网络抖动 | 等待后检查网络连接和配置后重试，二次失败提示用户检查网络连接和配置后重试 |
| 通话 `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%确定性的关键决策。

## 输出格式

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