ClawdTalk

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

Clawdbot 的语音通话、短信和 AI 任务功能。通过电话呼叫您的机器人、发送短信或运行自主的多步骤外联活动——由 ClawdTalk 提供支持。

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

外部端点

端点	使用者	发送的数据
https://clawdtalk.com(WebSocket)	ws-client.js	语音转录、工具结果、对话状态
https://clawdtalk.com/v1/*	telnyx_api.py	任务状态、事件、计划通话/短信、助手配置
http://127.0.0.1:<端口号>	ws-client.js	转录的语音（仅限本地网关）
https://raw.githubusercontent.com/team-telnyx/clawdtalk-client/...	update.sh	无（仅下载）

安全与隐私

• 语音转录文本和短信内容会传输到 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）必须使用完全相同的标识符。

标识符不匹配 = 代理未关联 = 前端看不到计划事件。

# After init, ALWAYS confirm the slug:
python scripts/telnyx_api.py list-state
# Output: find-window-washing-contractors: Find window washing contractors [running]
#         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ COPY-PASTE THIS. NEVER ABBREVIATE.

---

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

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

您的职责

对于每个任务，您必须：

1. 更新计划步骤— 将每个步骤标记为进行中→已完成（或失败）
2. 记录事件—— 在每次重要行动之后
3. 轮询完成状态—— 检查计划中的通话/短信是否已完成
4. 完成任务—— 将此次运行标记为成功或失败
5. 清理—— 任务结束时移除所有轮询的定时作业

用户界面会精确反映你告知它的内容。你不更新 = 屏幕上就不更新。

---

🚨 强制要求：每次行动后必须保存到内存

每次重要行动成功后，必须立即使用save-memory或append-memory进行持久化存储。前端从服务器内存读取数据。如果你不保存，它就不会显示。日志事件仅此一项是不够的。

规则：如果你做了某件事，请将其保存到内存中。没有例外。不要说“我稍后再做”。现在就做。

示例（安排短信）：

# 1. Schedule it
python scripts/telnyx_api.py schedule-sms $AID "$TO" "$FROM" "$DATETIME" "$MESSAGE" $MID $RID $STEP_ID

# 2. IMMEDIATELY save to memory
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. Then log the event
python scripts/telnyx_api.py log-event $MID $RID custom "Scheduled SMS event_id=<id>" $STEP_ID

跳过第二步是导致“前端无显示”错误的首要原因。

---

🚨 强制要求：完成每一步后检查任务状态

在完成或失败任何一步后，你必须检查任务是否应该完成或失败。当任务实际上已完成或已失败时，切勿让任务保持“运行中”状态。

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

决策树（在每一步之后运行）：

Step finished →
  ├── Succeeded?
  │     ├── All steps done? → COMPLETE MISSION (update-run succeeded)
  │     ├── More steps remain? → Continue to next step
  │     └── Only verify left? → Set up polling cron
  └── Failed?
        ├── Recoverable (retry/reschedule)? → Retry
        └── Unrecoverable? → FAIL MISSION NOW:
              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. Clean up any polling cron jobs

当任务实际上已完成或已失败时，却卡在“运行中”状态，这是一个错误。用户看到后会认为工作仍在进行。

---

架构概述

各部分如何协同工作

┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│  You (Bot)   │────▶│  ClawdTalk Server │────▶│  Telnyx API  │
│              │     │  (dev/prod)       │     │  (cloud)     │
│ telnyx_api.py│     │  Local DB + proxy │     │  Executes    │
│              │     │  to Telnyx        │     │  calls/SMS   │
└──────────────┘     └──────────────────┘     └──────────────┘

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

关键文件

文件	用途
scripts/telnyx_api.py	用于所有任务/助手/事件操作的 CLI 工具
scripts/connect.sh	用于入站语音呼叫路由的 WebSocket 客户端
skill-config.json	API 密钥和服务器 URL
.missions_state.json	活动任务的本地状态跟踪
.connect.log	WebSocket 连接日志

两组 ID

每个实体都存在于两个地方，拥有不同的 ID：

• 本地数据库 ID— ClawdTalk 服务器返回的内容（例如3df24dde-...)
• Telnyx ID— Telnyx API 内部使用的标识符

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

---

快速开始

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

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

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

语音通话

WebSocket客户端将通话路由到您网关的主代理会话，提供对内存、工具和上下文的完全访问权限。

./scripts/connect.sh start     # Start connection
./scripts/connect.sh stop      # Stop
./scripts/connect.sh status    # Check status

外拨电话

让机器人给您或其他人打电话：

./scripts/call.sh                              # Call your phone
./scripts/call.sh "Hey, what's up?"            # Call with greeting
./scripts/call.sh --to +15551234567            # Call external number*
./scripts/call.sh --to +15551234567 "Hello!"   # External with greeting
./scripts/call.sh status <call_id>             # Check call status
./scripts/call.sh end <call_id>                # End call

* 外拨电话需要付费账户并配备专用号码。AI在拨打外部号码时将处于隐私模式（不会泄露您的私人信息）。

短信

发送和接收短信：

./scripts/sms.sh send +15551234567 "Hello!"
./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    # Verify setup

重要提示：请频繁保存状态

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

双层持久化：内存 + 事件

务必同时保存到：

1. 本地内存(.missions_state.json) - 快速，重启后仍存在
2. 事件 API（云端） - 永久审计追踪，本地文件丢失后仍存在

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

操作	保存内存	记录事件
网络搜索返回结果	追加内存	记录事件（工具调用）
找到承包商/潜在客户	追加内存	记录事件（自定义）
创建助手	保存记忆	记录事件（自定义）
分配电话号码	保存记忆	记录事件（自定义）
安排通话/短信	追加记忆	记录事件（自定义）
通话完成	保存记忆	记录事件（自定义）
获取报价/洞察	保存记忆	记录事件（自定义）
做出决策	保存记忆	记录事件（消息）
步骤开始	保存记忆	更新步骤（进行中）+ 记录事件（步骤开始）
步骤完成	保存记忆	更新步骤（完成）+ 记录事件（步骤完成）
步骤失败	保存记忆	更新步骤（失败）+ 记录事件（错误）
发生错误	保存记忆	记录事件（错误）

记忆命令（本地备份）

# Save a single value
python scripts/telnyx_api.py save-memory "<slug>" "key" '{"data": "value"}'

# Append to a list (great for collecting multiple items)
python scripts/telnyx_api.py append-memory "<slug>" "contractors" '{"name": "ABC Co", "phone": "+1234567890"}'

# Retrieve memory
python scripts/telnyx_api.py get-memory "<slug>"           # Get all memory
python scripts/telnyx_api.py get-memory "<slug>" "key"     # Get specific key

事件命令（云备份）

# Log an event (step_id is REQUIRED - links event to a plan step)
python scripts/telnyx_api.py log-event <mission_id> <run_id> <type> "<summary>" <step_id> '[payload_json]'

# Event types: tool_call, custom, message, error, step_started, step_completed
# step_id: Use the step_id from your plan (e.g., "research", "setup", "calls")
#          Use "-" if event doesn't belong to a specific step

---

何时使用任务

此技能有两种模式：完整任务（可追踪、多步骤）和简单调用（一次性、无任务开销）。请选择合适的方式。

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

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

示例：

• "在芝加哥为我找到窗户清洁承包商，联系他们并协商价格"
• "联系此列表中的所有潜在客户并安排演示"
• "致电10个气象站，找出最热的一个"

在以下情况下请勿使用任务：

• 任务是一个单次外呼电话——只需创建一个助手（或重用现有助手）并直接安排通话
• 这是一个一次性短信——安排发送即可完成
• 任务不需要追踪、计划或状态恢复
• 如果你创建一个仅包含一个步骤和一次通话的任务——那就属于过度设计了

对于简单通话，只需：

# Reuse or create an assistant
python scripts/telnyx_api.py list-assistants --name=<relevant>
# Schedule the call
python scripts/telnyx_api.py schedule-call <assistant_id> <to> <from> <datetime> <mission_id> <run_id>
# Poll for completion
python scripts/telnyx_api.py get-event <assistant_id> <event_id>
# Get insights
python scripts/telnyx_api.py get-insights <conversation_id>

没有任务，没有运行，没有计划。保持简单。

状态持久化

脚本自动管理状态于.missions_state.json文件中。此状态在重启后依然保留，并支持多个并发任务。

python scripts/telnyx_api.py list-state                              # List all active missions
python scripts/telnyx_api.py get-state "find-window-washing-contractors"  # Get state for specific mission
python scripts/telnyx_api.py remove-state "find-window-washing-contractors" # Remove mission from state

---

核心工作流程

阶段1：初始化跟踪

步骤 1.1：创建任务

python scripts/telnyx_api.py create-mission "Brief descriptive name" "Full description of the task"

保存返回的mission_id——后续所有调用都需要用到它。

步骤 1.2：启动运行

python scripts/telnyx_api.py create-run <mission_id> '{"original_request": "The exact user request", "context": "Any relevant context"}'

保存返回的run_id。

步骤 1.3：创建计划

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

python scripts/telnyx_api.py create-plan <mission_id> <run_id> '[
  {"step_id": "step_1", "description": "Research contractors online", "sequence": 1},
  {"step_id": "step_2", "description": "Create voice agent for calls", "sequence": 2},
  {"step_id": "step_3", "description": "Schedule calls to each contractor", "sequence": 3},
  {"step_id": "step_4", "description": "Monitor call completions", "sequence": 4},
  {"step_id": "step_5", "description": "Analyze results and select best options", "sequence": 5}
]'

步骤 1.4：将运行状态设置为进行中

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

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

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

python scripts/telnyx_api.py init "Find window washing contractors" "Find contractors in Chicago, call them, negotiate rates" "User wants window washing quotes" '[
  {"step_id": "research", "description": "Find contractors online", "sequence": 1},
  {"step_id": "setup", "description": "Create voice agent", "sequence": 2},
  {"step_id": "calls", "description": "Schedule and make calls", "sequence": 3},
  {"step_id": "analyze", "description": "Analyze results", "sequence": 4}
]'

如果已经存在同名任务，此操作也会自动恢复。

⚠️ 紧接着在初始化之后，运行list-state并复制确切的标识符。在后续所有命令中都使用它。

---

阶段 2：语音/短信代理设置

当您的任务需要拨打电话或发送短信时，请首先创建一个AI助手。

步骤 2.1：创建语音/短信助手

用于电话呼叫：

python scripts/telnyx_api.py create-assistant "Contractor Outreach Agent" "You are calling on behalf of [COMPANY]. Your goal is to [SPECIFIC GOAL]. Be professional and concise. Collect: [WHAT TO COLLECT]. If they cannot talk now, ask for a good callback time." "Hi, this is an AI assistant calling on behalf of [COMPANY]. Is this [BUSINESS NAME]? I am calling to inquire about your services. Do you have a moment?" '["telephony", "messaging"]'

用于短信：

python scripts/telnyx_api.py create-assistant "SMS Outreach Agent" "You send SMS messages to collect information. Keep messages brief and professional." "Hi! I am reaching out on behalf of [COMPANY] regarding [PURPOSE]. Could you please reply with [REQUESTED INFO]?" '["telephony", "messaging"]'

保存返回的assistant_id。

步骤 2.2：查找并分配电话号码

python scripts/telnyx_api.py get-available-phone                          # Get first available
python scripts/telnyx_api.py get-connection-id <assistant_id> telephony   # Get connection ID
python scripts/telnyx_api.py assign-phone <phone_number_id> <connection_id> voice  # Assign

高级替代方案：一步设置代理

python scripts/telnyx_api.py setup-agent "find-window-washing-contractors" "Contractor Caller" "You are calling to get quotes for commercial window washing. Ask about: rates per floor, availability, insurance. Be professional." "Hi, I am calling to inquire about your commercial window washing services. Do you have a moment to discuss rates?"

此操作会自动创建助手，将其链接到任务运行，查找可用电话号码，进行分配，并将所有ID保存到状态文件。

⚠️ 标识符必须与初始化创建。如果未创建，代理人将不会被关联，并且预定事件不会出现在前端。

操作完成后立即验证关联是否成功：

python scripts/telnyx_api.py list-linked-agents <mission_id> <run_id>
# Must show your assistant_id. If empty → slug was wrong. Fix with:
python scripts/telnyx_api.py link-agent <mission_id> <run_id> <assistant_id>

步骤 2.3：将代理人与任务执行关联

如果使用setup-agent：关联会自动完成（仅当短名称匹配init时）。

如果手动设置：

python scripts/telnyx_api.py link-agent <mission_id> <run_id> <assistant_id>
python scripts/telnyx_api.py list-linked-agents <mission_id> <run_id>
python scripts/telnyx_api.py unlink-agent <mission_id> <run_id> <assistant_id>

---

阶段 3：安排通话/短信

营业时间考量

关键：在安排通话之前，请考虑营业时间（当地时间上午9点至下午5点）。scheduled_at必须是将来的时间（至少从现在起1分钟后）。

python scripts/telnyx_api.py schedule-call <assistant_id> "+15551234567" "+15559876543" "2024-12-01T14:30:00Z" <mission_id> <run_id>
python scripts/telnyx_api.py schedule-sms <assistant_id> "+15551234567" "+15559876543" "2024-12-01T14:30:00Z" "Your message here"

保存返回的事件id。

---

阶段 4：监控通话完成情况

⚠️ 这是最重要的部分

在安排通话或短信之后，Telnyx自主执行它在预定时间。你需要轮询来查明它何时完成，然后相应地更新任务。

检查预定事件状态

python scripts/telnyx_api.py get-event <assistant_id> <event_id>

使用Cron作业进行轮询

使用你机器人的cron系统来安排轮询。请勿阻塞主会话进行等待。将轮询间隔与预期等待时间匹配：

预期完成时间	轮询间隔	示例
< 5分钟	每30秒	短信从现在起1分钟后发送
5–30分钟	每2–5分钟	通话安排在15分钟后
1–24小时	每15–30分钟	通话安排在今晚
数天/数周	每4–8小时	已安排下周的通话

若知晓确切的预定时间，请在该时间后再开始轮询。首次轮询应安排在预定时间 + 2分钟。

定时任务模式

安排通话/短信时，请创建定时任务进行轮询：

Create cron: poll at appropriate interval
  → Run get-event <assistant_id> <event_id>
  → If completed: update step, log event, complete mission if last step, DELETE THIS CRON
  → If failed: update step as failed, log error, DELETE THIS CRON
  → If pending/in_progress: do nothing, cron runs again at next interval

⚠️ 当任务进入终态（完成/失败/取消）时，务必清理定时任务。任务结束后切勿遗留轮询定时任务。

轮询频率调整

可根据实际情况调整定时任务间隔：

• 预定时间在两周后？初始轮询间隔设为8小时。
• 临近预定时间（1小时内）时，缩短至5分钟间隔。
• 超过预定时间后，缩短至30秒间隔。

事件状态值说明

状态	含义	操作
待处理	等待预定时间	继续轮询
进行中	通话/短信进行中	继续轮询
已完成	成功完成	更新步骤，如果是通话则获取洞察信息
失败	重试后失败	将步骤更新为失败，考虑重试

通话状态值（仅限电话通话）

通话状态	含义	操作
振铃中	电话正在振铃	1-2分钟后再次轮询
进行中	通话处于活动状态	2-3分钟后再次轮询
已完成	通话正常结束	获取洞察信息
未接听	无人接听	可重试— 重新安排
忙碌	线路繁忙	可重试— 10-15分钟后重试
已取消	通话已取消	检查是否为有意取消
失败	网络/系统错误	可重试— 5-10分钟后重试

---

阶段5：获取对话洞察

一旦通话完成并获得conversation_id，即可获取洞察信息。轮询直到状态变为"已完成"（重试间隔为10秒）。

python scripts/telnyx_api.py get-insights <conversation_id>

Telnyx在创建助手时会自动生成默认的洞察模板。您无需管理这些模板——只需读取结果即可。

---

阶段6：完成任务

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

# Or with full results:
python scripts/telnyx_api.py complete "find-window-washing-contractors" <mission_id> <run_id> "Summary of results" '{"key": "payload"}'

---

事件日志记录参考

将每一个操作都记录为事件。始终通过update-step来更新步骤状态，

# When STARTING a step:
python scripts/telnyx_api.py update-step "$MISSION_ID" "$RUN_ID" "research" "in_progress"
python scripts/telnyx_api.py log-event "$MISSION_ID" "$RUN_ID" step_started "Starting: Research" "research"

# When COMPLETING a step:
python scripts/telnyx_api.py update-step "$MISSION_ID" "$RUN_ID" "research" "completed"
python scripts/telnyx_api.py log-event "$MISSION_ID" "$RUN_ID" step_completed "Completed: Research" "research"

# When a step FAILS:
python scripts/telnyx_api.py update-step "$MISSION_ID" "$RUN_ID" "calls" "failed"
python scripts/telnyx_api.py log-event "$MISSION_ID" "$RUN_ID" error "Failed: Could not reach contractors" "calls"

---

并记录相应的事件。

# Check setup
python scripts/telnyx_api.py check-key

# Missions
python scripts/telnyx_api.py create-mission <name> <instructions>
python scripts/telnyx_api.py get-mission <mission_id>
python scripts/telnyx_api.py list-missions

# Runs
python scripts/telnyx_api.py create-run <mission_id> <input_json>
python scripts/telnyx_api.py get-run <mission_id> <run_id>
python scripts/telnyx_api.py update-run <mission_id> <run_id> <status>
python scripts/telnyx_api.py list-runs <mission_id>

# Plan
python scripts/telnyx_api.py create-plan <mission_id> <run_id> <steps_json>
python scripts/telnyx_api.py get-plan <mission_id> <run_id>
python scripts/telnyx_api.py update-step <mission_id> <run_id> <step_id> <status>

# Events
python scripts/telnyx_api.py log-event <mission_id> <run_id> <type> <summary> <step_id> [payload_json]
python scripts/telnyx_api.py list-events <mission_id> <run_id>

# Assistants
python scripts/telnyx_api.py list-assistants [--name=<filter>] [--page=<n>] [--size=<n>]
python scripts/telnyx_api.py create-assistant <name> <instructions> <greeting> [options_json]
python scripts/telnyx_api.py get-assistant <assistant_id>
python scripts/telnyx_api.py update-assistant <assistant_id> <updates_json>
python scripts/telnyx_api.py get-connection-id <assistant_id> [telephony|messaging]

# Phone Numbers
python scripts/telnyx_api.py list-phones [--available]
python scripts/telnyx_api.py get-available-phone
python scripts/telnyx_api.py assign-phone <phone_id> <connection_id> [voice|sms]

# Scheduled Events
python scripts/telnyx_api.py schedule-call <assistant_id> <to> <from> <datetime> <mission_id> <run_id>
python scripts/telnyx_api.py schedule-sms <assistant_id> <to> <from> <datetime> <text>
python scripts/telnyx_api.py get-event <assistant_id> <event_id>
python scripts/telnyx_api.py cancel-scheduled-event <assistant_id> <event_id>
python scripts/telnyx_api.py list-events-assistant <assistant_id>

# Insights
python scripts/telnyx_api.py get-insights <conversation_id>

# Mission Run Agents
python scripts/telnyx_api.py link-agent <mission_id> <run_id> <telnyx_agent_id>
python scripts/telnyx_api.py list-linked-agents <mission_id> <run_id>
python scripts/telnyx_api.py unlink-agent <mission_id> <run_id> <telnyx_agent_id>

# State Management
python scripts/telnyx_api.py list-state
python scripts/telnyx_api.py get-state <slug>
python scripts/telnyx_api.py remove-state <slug>

# Memory
python scripts/telnyx_api.py save-memory <slug> <key> <value_json>
python scripts/telnyx_api.py get-memory <slug> [key]
python scripts/telnyx_api.py append-memory <slug> <key> <item_json>

# High-Level Workflows
python scripts/telnyx_api.py init <name> <instructions> <request> [steps_json]
python scripts/telnyx_api.py setup-agent <slug> <name> <instructions> <greeting>
python scripts/telnyx_api.py complete <slug> <mission_id> <run_id> <summary> [payload_json]

---

快速参考：所有 Python 命令

完整示例：使用 Cron 轮询的短信任务

# 1. Init mission
python scripts/telnyx_api.py init "SMS Test 003" \
  "Send a test SMS to +13322200013" \
  "SMS test with full tracking" \
  '[{"step_id": "setup", "description": "Create SMS agent", "sequence": 1},
    {"step_id": "sms", "description": "Schedule SMS", "sequence": 2},
    {"step_id": "verify", "description": "Verify delivery", "sequence": 3}]'
# Save: mission_id, run_id

# 2. Step 1: Setup agent
python scripts/telnyx_api.py update-step $MISSION_ID $RUN_ID setup in_progress
python scripts/telnyx_api.py log-event $MISSION_ID $RUN_ID step_started "Starting: Create SMS agent" setup

python scripts/telnyx_api.py setup-agent "sms-test-003" "SMS Agent" "Send test messages" "Test from bot"
# Save: assistant_id, phone_number

python scripts/telnyx_api.py update-step $MISSION_ID $RUN_ID setup completed
python scripts/telnyx_api.py log-event $MISSION_ID $RUN_ID step_completed "Completed: Created assistant $ASSISTANT_ID" setup

# 3. Step 2: Schedule SMS
python scripts/telnyx_api.py update-step $MISSION_ID $RUN_ID sms in_progress
python scripts/telnyx_api.py log-event $MISSION_ID $RUN_ID step_started "Starting: Schedule SMS" sms

python scripts/telnyx_api.py schedule-sms $ASSISTANT_ID "+13322200013" "$PHONE" "2026-02-19T18:43:00Z" \
  "What do you call a bear with no teeth? A gummy bear!" \
  $MISSION_ID $RUN_ID sms
# Save: event_id

python scripts/telnyx_api.py update-step $MISSION_ID $RUN_ID sms completed
python scripts/telnyx_api.py log-event $MISSION_ID $RUN_ID step_completed "Completed: SMS scheduled" sms

# 4. Step 3: Verify delivery — CREATE A CRON JOB TO POLL
python scripts/telnyx_api.py update-step $MISSION_ID $RUN_ID verify in_progress
python scripts/telnyx_api.py log-event $MISSION_ID $RUN_ID step_started "Starting: Poll for delivery" verify

# >>> Create a cron job that fires AFTER the scheduled time <<<
# >>> Cron runs: get-event $ASSISTANT_ID $EVENT_ID <<<
# >>> On completed: update-step verify completed, log-event, update-run succeeded, DELETE CRON <<<
# >>> On failed: update-step verify failed, log-event, update-run failed, DELETE CRON <<<
# >>> On pending/in_progress: do nothing, cron fires again next interval <<<

# 5. (Cron fires, detects completion)
python scripts/telnyx_api.py update-step $MISSION_ID $RUN_ID verify completed
python scripts/telnyx_api.py log-event $MISSION_ID $RUN_ID step_completed "Completed: SMS delivered" verify
python scripts/telnyx_api.py update-run $MISSION_ID $RUN_ID succeeded
# DELETE the polling cron job!

---

这是一个具备完整生命周期追踪和基于 Cron 轮询的短信任务完整流程：

任务类别

Does call N depend on results of call N-1?
  YES -> Is it negotiation (leveraging previous results)?
    YES -> Class 3: Sequential Negotiation
    NO  -> Does it have distinct rounds with human approval?
      YES -> Class 4: Multi-Round / Follow-up
      NO  -> Class 5: Information Gathering -> Action
  NO  -> Do you need structured scoring/ranking?
    YES -> Class 2: Parallel Screening with Rubric
    NO  -> Class 1: Parallel Sweep

并非所有任务都相同。在规划前，请先识别其所属类别。

类别 1：并行扫掠

以并行批次的方式分散呼叫。向多个目标提出相同问题。在一个批次中安排所有呼叫（间隔 1-2 分钟）。在所有呼叫完成后进行分析。

类别 2：基于量规的并行筛选

使用结构化评分标准并行分散呼叫。结果在事后通过洞察进行排名。

类别 3：顺序协商呼叫必须串行运行。每次呼叫的策略取决于之前的结果。在呼叫之间使用update-assistant来注入上下文。

第4类：多轮/跟进式呼叫

包含两个或多个不同阶段。第一轮进行广泛触达，设置人工审核环节；随后第二轮针对筛选出的目标子集进行呼叫。

第5类：信息收集→执行行动

通过呼叫获取信息后立即执行相应行动。目标达成即提前终止——取消剩余呼叫。

---

操作指南

默认工具

系统默认集成发送DTMF信号工具。多数外呼会首先接入交互式语音应答系统。

IVR导航设置

即使拨打企业号码也需预设IVR流程。指示助理按0或说“转人工”。

呼叫限制与流量调控

采用5-10通为批次的交错呼叫，安排间隔1-2分钟的执行时间，密切监控429错误状态。

应答机检测功能

• 针对真人接听场景启用
• （可留语音邮件或跳过机器应答）针对IVR系统及具备电话树的企业号码禁用

轮询获取结果：使用Cron作业

安排呼叫后，设置一个cron作业进行定期轮询。不要阻塞主会话。

重试策略

在任务内存中跟踪每个号码的状态。根据接收者类型进行重试：

• 自动化系统：5-15分钟内重试，最多3次
• 服务业：30分钟至2小时内重试，避开高峰时段
• 专业人士：下一个工作日重试，最多留一次语音邮件

---

审批请求（敏感操作）

对于语音通话期间的破坏性或敏感操作，需先请求用户批准：

./scripts/approval.sh request "Delete GitHub repo myproject"
./scripts/approval.sh request "Send $500 to John" --biometric
./scripts/approval.sh request "Post tweet about X" --details "Full text: ..."

何时请求批准：

• 删除仓库、文件或数据
• 汇款或购物
• 发布到社交媒体
• 向他人发送电子邮件/消息
• 任何不可逆的操作

响应值：

• 已批准→ 执行该操作，确认完成
• 已拒绝→ 告诉用户"好的，我不会那样做"
• 超时→ "我没有收到回复，需要再试一次吗？"
• 无设备→ 跳过批准，操作未执行（无移动应用）

语音通话中的示例流程：

1. 用户："删除我在GitHub上的test-repo仓库"
2. 你："我需要你的批准才能执行。请查看你的手机。"
3. 运行：approval.sh request "删除GitHub仓库test-repo"
4. 如果批准：删除该仓库，然后说"完成，test-repo已被删除"
5. 如果拒绝："明白了，我不会删除它"

网关要求

语音通话通过sessions_send将请求路由到主代理。此工具在网关HTTP工具API上默认被阻止。你必须明确允许它：

// In openclaw.json → gateway.tools
{
  "gateway": {
    "tools": {
      "allow": ["sessions_send"]
    }
  }
}

或通过CLI：openclaw config patch '{"gateway":{"tools":{"allow":["sessions_send"]}}}'

如果不这样做，语音通话可以接通，但代理将无法处理任何请求（深度工具调用会返回404）。

⚠️警告：这必须放在gateway.tools.allow下，而不是顶层的tools.allow。顶层的tools.allow是代理的工具白名单——将sessions_send放在那里会限制您的代理只能使用该工具，从而破坏一切。如果您不小心这样做了，请删除顶层的tools.allow条目并重启。

❌ 常见陷阱

错误	症状	修复
对于init使用了不同的slug设置代理	前端缺少预定事件	列出状态之后初始化，复制粘贴标识
遗忘保存记忆在操作之后	前端无显示	每次操作后立即保存
步骤变更后未检查任务状态	任务永久卡在“运行中”	每个步骤后运行决策树
轮询定时任务持续运行	资源浪费，轮询陈旧	在任何终止状态删除定时任务
未验证列出关联代理之后设置代理	代理未关联，事件不可见	始终验证，并通过链接代理

配置

编辑skill-config.json：

选项	描述
api_key	来自 clawdtalk.com 的 API 密钥
server	服务器 URL（默认：https://clawdtalk.com）
owner_name	您的姓名（从 USER.md 自动检测）
agent_name	代理名称（从 IDENTITY.md 自动检测）
greeting	呼入电话的自定义问候语

Python 任务 API 的环境变量：

• CLAWDTALK_API_KEY— 您的 ClawdTalk API 密钥（执行任务必需）
• CLAWDTALK_API_URL— 覆盖 API 端点（默认：https://clawdtalk.com/v1)

故障排除

• 认证失败：在clawdtalk.com重新生成API密钥
• 网关令牌/端口已更改：重新运行./setup.sh以使用新值更新skill-config.json文件
• 响应为空：运行./setup.sh并重启网关
• 响应缓慢：在网关配置中尝试使用更快的模型
• 调试模式：DEBUG=1 ./scripts/connect.sh restart
• Missions API密钥：运行python scripts/telnyx_api.py check-key进行验证
• JSON解析错误：在JSON参数周围使用单引号

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。