名称： clawdtalk-client
版本： 2.0.0
描述： ClawdTalk — 为 Clawdbot 提供语音通话、短信和 AI 任务
元数据： {"clawdbot":{"emoji":"📞","primaryEnv":"CLAWDTALK_API_KEY","homepage":"https://github.com/team-telnyx/clawdtalk-client","requires":{"env":["CLAWDTALK_API_KEY"],"bins":["bash","node","jq","python3"],"config":["skill-config.json","~/.openclaw/openclaw.json","~/.clawdbot/clawdbot.json"]}}}

ClawdTalk

⚠️ 首次设置？ 请先阅读本目录下的 SETUP.md 文件。它将引导你完成完整的配置流程。

为 Clawdbot 提供语音通话、短信和 AI 任务。通过电话呼叫你的机器人、发送短信，或运行自主的多步骤外联活动——这一切都由 ClawdTalk 驱动。

信任声明： 使用此技能时，语音转录、短信内容和任务数据将被发送到 clawdtalk.com（由 Telnyx 运营）。仅在你信任此服务处理你的对话数据时才安装。

外部端点

安全与隐私

• 语音转录和短信内容会被传输到 clawdtalk.com。
• 任务状态和事件存储在服务器端，用于跟踪和分析。
• setup.sh 会读取网关配置以提取连接详情；经确认后，它会添加一个语音代理并将 sessions_send 添加到 gateway.tools.allow。
• API 密钥存储在 skill-config.json 中——使用环境变量 CLAWDTALK_API_KEY 或 ${CLAWDTALK_API_KEY} 引用以避免明文存储。

⚠️ 关键：标识符一致性

init 命令会根据任务名称自动生成一个标识符（小写，空格替换为连字符）。
每个接受标识符的命令（setup-agent、save-memory、complete）都必须使用完全相同的标识符。

标识符不匹配 = 代理未链接 = 前端看不到计划的事件。

# 执行 init 后，务必确认标识符：
python scripts/telnyx_api.py list-state
# 输出示例：find-window-washing-contractors: Find window washing contractors [running]
#         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 复制粘贴这个。切勿缩写。

⚠️ 关键：你负责管理任务生命周期

服务器不会自动更新计划步骤或任务状态。 这是你作为机器人的职责。如果你不更新步骤并完成任务，UI 将永远显示“运行中”，且所有步骤都显示“待处理”。

你的职责

对于每个任务，你必须：
1. 更新计划步骤 — 将每个步骤标记为 in_progress → completed（或 failed）
2. 记录事件 — 每次重要操作后
3. 轮询完成状态 — 检查计划的通话/短信是否完成
4. 完成任务 — 将运行标记为 succeeded 或 failed
5. 清理 — 任务结束时移除所有轮询的 cron 作业

UI 会精确反映你告知它的内容。你不更新，屏幕就不会更新。

🚨 强制要求：每次操作后必须保存到记忆

每次重要操作成功后，必须立即使用 save-memory 或 append-memory 进行持久化。 前端从服务器内存读取数据。如果你不保存，它就不会显示。仅使用 log-event 是不够的。

规则：如果你做了某事，就把它保存到记忆。没有例外。不要“我稍后再做”。现在就做。

示例（安排短信）：

# 1. 安排短信
python scripts/telnyx_api.py schedule-sms $AID "$TO" "$FROM" "$DATETIME" "$MESSAGE" $MID $RID $STEP_ID

# 2. 立即保存到记忆
python scripts/telnyx_api.py append-memory "$SLUG" "scheduled_events" \
  '{"event_id": "<id>", "type": "sms", "to": "<to>", "message": "<msg>", "scheduled_at": "<dt>", "step_id": "<step>"}'

# 3. 然后记录事件
python scripts/telnyx_api.py log-event $MID $RID custom "Scheduled SMS event_id=<id>" $STEP_ID

跳过第 2 步是导致“前端什么也不显示”问题的首要原因。

🚨 强制要求：每个步骤后检查任务状态

在完成或失败任何步骤后，你必须检查任务是否应该被完成或标记为失败。 当任务实际已完成或死亡时，切勿让其停留在“运行中”状态。

规则：每次步骤变更后，问自己：这个任务完成了吗？

决策树（每次步骤后运行）：

步骤完成 →
  ├── 成功？
  │     ├── 所有步骤都完成？ → 完成任务 (update-run succeeded)
  │     ├── 还有更多步骤？ → 继续下一个步骤
  │     └── 只剩下验证步骤？ → 设置轮询 cron 作业
  └── 失败？
        ├── 可恢复（重试/重新安排）？ → 重试
        └── 不可恢复？ → 立即标记任务失败：
              1. update-step <step_id> failed
              2. log-event error "Failed: <reason>" <step_id>
              3. save-memory "$SLUG" "error_<step_id>" '{"error": "...", "recoverable": false}'
              4. update-run $MID $RID failed
              5. save-memory "$SLUG" "result" '{"status": "failed", "reason": "...", "failed_step": "..."}'
              6. 清理所有轮询的 cron 作业

任务实际已完成或死亡却仍停留在“运行中”状态是一个错误。用户看到后会认为工作仍在进行。

架构概述

各部分如何协同工作

┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│   你（机器人）  │────▶│  ClawdTalk 服务器  │────▶│  Telnyx API  │
│              │     │  (开发/生产)       │     │  (云端)      │
│ telnyx_api.py│     │  本地数据库 + 代理  │     │  执行通话/短信 │
│              │     │  到 Telnyx        │     │              │
└──────────────┘     └──────────────────┘     └──────────────┘

• telnyx_api.py — Python CLI 脚本。你运行的每个命令都通过它。它与 ClawdTalk 服务器通信，从不直接与 Telnyx 通信。
• ClawdTalk 服务器 — Node.js 后端。在本地 Postgres 数据库中存储任务、助手和事件。将请求代理到 Telnyx API。
• Telnyx API — 云服务。在预定时间实际拨打电话和发送短信。

关键文件

两套 ID

每个实体存在于两个地方，拥有不同的 ID：
- 本地数据库 ID — ClawdTalk 服务器返回的 ID（例如 3df24dde-...）
- Telnyx ID — Telnyx API 内部使用的 ID

脚本始终使用本地 ID。你无需担心 Telnyx ID。

快速开始

1. 注册 clawdtalk.com
2. 在设置中添加你的电话号码
3. 从仪表板获取 API 密钥
4. 运行设置：./setup.sh

   setup.sh 会读取你的网关配置以提取连接详情，将语音代理添加到 agents.list，并（经确认后）将 sessions_send 添加到 gateway.tools.allow。网关配置位于 ~/.openclaw/openclaw.json 或 ~/.clawdbot/clawdbot.json。

5. 启动连接：./scripts/connect.sh start

语音通话

WebSocket 客户端将呼叫路由到网关的主代理会话，提供对记忆、工具和上下文的完全访问。

./scripts/connect.sh start     # 启动连接
./scripts/connect.sh stop      # 停止
./scripts/connect.sh status    # 检查状态

外呼

让机器人呼叫你或他人：

./scripts/call.sh                              # 呼叫你的电话
./scripts/call.sh "嘿，最近怎么样？"            # 带问候语的呼叫
./scripts/call.sh --to +15551234567            # 呼叫外部号码*
./scripts/call.sh --to +15551234567 "你好！"   # 带问候语的外部呼叫
./scripts/call.sh status <call_id>             # 检查呼叫状态
./scripts/call.sh end <call_id>                # 结束呼叫

*外部呼叫需要付费账户和专用号码。AI 在呼叫外部号码时将处于隐私模式（不会透露你的私人信息）。

短信

发送和接收短信：

./scripts/sms.sh send +15551234567 "你好！"
./scripts/sms.sh list
./scripts/sms.sh conversations

AI 任务（通过 Python 完全跟踪）

对于需要完全跟踪、状态持久化、重试和对话分析的复杂多步骤任务，请使用基于 Python 的任务 API。

必需：Python 3.7+、CLAWDTALK_API_KEY 环境变量。可选设置 CLAWDTALK_API_URL 以覆盖默认端点（默认为 https://clawdtalk.com/v1）。

python scripts/telnyx_api.py check-key    # 验证设置

关键：频繁保存状态

每次重要操作后，你必须保存进度。 如果会话崩溃或重启，未保存的工作将丢失。

双层持久化：记忆 + 事件

始终保存到两者：
1. 本地记忆 (.missions_state.json) - 快速，重启后保留
2. 事件 API (云端) - 永久审计跟踪，本地文件丢失后仍保留

何时保存（每次操作后！）

记忆命令（本地备份）

# 保存单个值
python scripts/telnyx_api.py save-memory "<slug>" "key" '{"data": "value"}'

# 追加到列表（适用于收集多个项目）
python scripts/telnyx_api.py append-memory "<slug>" "contractors" '{"name": "ABC 公司", "phone": "+1234567890"}'

# 检索记忆
python scripts/telnyx_api.py get-memory "<slug>"           # 获取所有记忆
python scripts/telnyx_api.py get-memory "<slug>" "key"     # 获取特定键

事件命令（云端备份）

# 记录事件（step_id 是必需的 - 将事件链接到计划步骤）
python scripts/telnyx_api.py log-event <mission_id> <run_id> <type> "<summary>" <step_id> '[payload_json]'

# 事件类型：tool_call, custom, message, error, step_started, step_completed
# step_id: 使用你计划中的 step_id（例如 "research", "setup", "calls"）
#          如果事件不属于特定步骤，使用 "-"

何时使用任务

此技能有两种模式：完整任务（跟踪、多步骤）和简单通话（一次性，无任务开销）。选择正确的模式。

在以下情况使用完整任务：

• 任务涉及多次通话或短信（批量外联、调查、扫荡）
• 你需要完整的审计跟踪，包含事件、计划和状态跟踪
• 任务是多步骤的，需要跨阶段付出大量努力
• 重试和失败跟踪很重要
• 你需要比较多次通话的结果

示例：
- “为我找到芝加哥的窗户清洁承包商，打电话给他们并协商价格”
- “联系此列表中的所有线索并安排演示”
- “呼叫 10 个气象站，找出最热的一个”

在以下情况不要使用任务：

• 任务是单个外呼 — 只需创建（或重用）一个助手并直接安排通话
• 是一次性短信 — 安排它，然后完成
• 任务不需要跟踪、计划或状态恢复
• 你本应创建一个只有一个步骤和一次通话的任务 — 这是过度设计

对于简单通话，只需：

# 重用或创建一个助手
python scripts/telnyx_api.py list-assistants --name=<相关名称>
# 安排通话
python scripts/telnyx_api.py schedule-call <assistant_id> <to> <from> <datetime> <mission_id> <run_id>
# 轮询完成状态
python scripts/telnyx_api.py get-event <assistant_id> <event_id>
# 获取见解
python scripts/telnyx_api.py get-insights <conversation_id>

无需任务、运行或计划。保持简单。

状态持久化

脚本自动管理 .missions_state.json 中的状态。这能在重启后保留，并支持多个并发任务。

python scripts/telnyx_api.py list-state                              # 列出所有活跃任务
python scripts/telnyx_api.py get-state "find-window-washing-contractors"  # 获取特定任务的状态
python scripts/telnyx_api.py remove-state "find-window-washing-contractors" # 从状态中移除任务

核心工作流程

阶段 1：初始化跟踪

步骤 1.1：创建任务

python scripts/telnyx_api.py create-mission "简短描述性名称" "任务的完整描述"

保存返回的 mission_id — 你将在所有后续调用中需要它。

步骤 1.2：启动运行

python scripts/telnyx_api.py create-run <mission_id> '{"original_request": "确切的用户请求", "context": "任何相关上下文"}'

保存返回的 run_id。

步骤 1.3：创建计划

在执行之前，概述你的计划：

python scripts/telnyx_api.py create-plan <mission_id> <run_id> '[
  {"step_id": "step_1", "description": "在线研究承包商", "sequence": 1},
  {"step_id": "step_2", "description": "为通话创建语音代理", "sequence": 2},
  {"step_id": "step_3", "description": "安排与每个承包商的通话", "sequence": 3},
  {"step_id": "step_4", "description": "监控通话完成情况", "sequence": 4},
  {"step_id": "step_5", "description": "分析结果并选择最佳选项", "sequence": 5}
]'

步骤 1.4：将运行设置为运行中

python scripts/telnyx_api.py update-run <mission_id> <run_id> running

高级替代方案：一次性初始化所有内容

使用 init 命令一步创建任务、运行、计划并设置状态：

python scripts/telnyx_api.py init "寻找窗户清洁承包商" "在芝加哥寻找承包商，打电话给他们，协商价格" "用户想要窗户清洁报价" '[
  {"step_id": "research", "description": "在线查找承包商", "sequence": 1},
  {"step_id": "setup", "description": "创建语音代理", "sequence": 2},
  {"step_id": "calls", "description": "安排并进行通话", "sequence": 3},
  {"step_id": "analyze", "description": "分析结果", "sequence": 4}
]'

如果已存在同名任务，此命令也会自动恢复。

⚠️ 执行 init 后，立即运行 list-state 并复制确切的标识符。在所有后续命令中使用它。

阶段 2：语音/