Byted SMS Sender

火山引擎短信服务API，版本2026-01-01

何时使用

当用户有以下需求时，使用本skill：

发送短信场景：

• - 需要发送验证码短信
• 需要发送通知类短信
• 需要发送营销类短信
• 用户说发短信发送验证码发通知时

查询场景：

• - 需要查询可用的消息组（子账号）
• 需要查询已审核通过的短信签名
• 需要查询已审核通过的短信模板
• 需要查询短信发送记录
• 需要查询发送统计（成功率等）

使用前检查

检查是否已配置以下凭证：

• - ARKSKILLAPIKEY - API 密钥
• ARKSKILLAPIBASE - API 基础地址

这些凭证由 ArkClaw 预先配置在终端环境中，配置文件位置：/root/.openclaw/.env

检查方式：
bash
echo $ARKSKILLAPI_KEY
echo $ARKSKILLAPI_BASE

如果缺少凭证：

1. 1. 检查配置文件 /root/.openclaw/.env 是否存在
2. 如果仍然找不到，请联系 oncall 获取帮助

6个接口说明

1. send_sms - 发送短信

场景： 用户需要发送验证码、通知、营销短信

使用方式：

bash
python3 scripts/volcsms.py sendsms \
--sub-account 消息组ID \
--signature 签名 \
--template-id 模板ID \
--mobiles 手机号 \
--template-param {code:123456}

参数说明：

• - --sub-account：消息组ID（必填），从 listsubaccount 获取
• --signature：短信签名（必填），从 listsignature 获取
• --template-id：模板ID（必填），从 listsms_template 获取
• --mobiles：手机号（必填），多个用逗号分隔
• --template-param：模板参数（可选），JSON格式

2. listsubaccount - 查询消息组

场景： 需要知道可以用哪个消息组发送短信

使用方式：

bash
python3 scripts/volcsms.py listsub_account

参数说明：

• - --sub-account-name：可选，按名称模糊搜索

3. list_signature - 查询签名

场景： 需要知道可以用哪个签名，或者查询签名是否审核通过

使用方式：

bash
python3 scripts/volcsms.py listsignature --signature 火山引擎

参数说明：

• - --signature：可选，按签名模糊搜索
• --sub-accounts：可选，按子账号过滤
• --page：页码，默认1
• --page-size：每页数量，默认20

4. listsmstemplate - 查询模板

场景： 需要知道可以用哪个模板，或者查询模板参数

使用方式：

bash
python3 scripts/volcsms.py listsms_template --signatures 火山引擎

参数说明：

• - --template-id：可选，按模板ID模糊搜索
• --signatures：可选，按签名过滤
• --sub-accounts：可选，按子账号过滤
• --page：页码，默认1
• --page-size：每页数量，默认20

5. listsmssend_log - 查询发送记录

场景： 需要查看某条短信的发送状态，或批量查询发送历史

使用方式：

bash
python3 scripts/volcsms.py listsmssendlog \
--sub-account 消息组ID \
--from-time 1773113285 \
--to-time 1773213285

参数说明：

• - --sub-account：必填，消息组ID
• --from-time：开始时间戳（秒）
• --to-time：结束时间戳（秒）
• --mobile：可选，按手机号过滤
• --template-id：可选，按模板ID过滤
• --signature：可选，按签名过滤
• --message-id：可选，按消息ID精确查询
• --page：页码，默认1
• --page-size：每页数量，默认100

6. listtotalsendcountstat - 查询发送统计

场景： 需要查看发送成功率、接收成功率等统计信息

使用方式：

bash
python3 scripts/volcsms.py listtotalsendcount_stat \
--start-time 1773113285 \
--end-time 1773213285

参数说明：

• - --start-time：必填，开始时间戳（秒）
• --end-time：必填，结束时间戳（秒）
• --sub-account：可选，按消息组过滤
• --channel-type：可选，通道类型
• --signature：可选，按签名过滤
• --template-id：可选，按模板ID过滤

返回字段：

• - TotalSendCount：总发送数
• TotalSendSuccessCount：发送成功数
• TotalSendSuccessRate：发送成功率
• TotalReceiptSuccessCount：接收成功数
• TotalReceiptSuccessRate：接收成功率

典型使用流程

第一次发送短信

1. 1. 查询可用的消息组

1. 2. 查询可用的签名

1. 3. 查询可用的模板

1. 4. 发送短信

查询发送状态

bash
python3 scripts/volcsms.py listsmssendlog \
--sub-account 77da1acf \
--from-time 1773113285 \
--to-time 1773213285

常见错误码

• - RE:0001：账号短信服务未开通
• RE:0003：子账号不存在（消息组ID错误）
• RE:0004：签名错误（签名不存在或未审核通过）
• RE:0005：模板错误（模板不存在或未审核通过）
• RE:0006：手机号格式错误
• RE:0010：账号欠费
• ZJ10200：请求参数错误

注意事项

1. 1. 签名和模板：必须使用已审核通过的签名和模板
2. 手机号格式：

1. 3. 批量限制：单次最多200个手机号
2. 签名子账号匹配：签名和消息组需要匹配，可从 listsignature 的 SubAccounts 字段确认
3. 模板签名匹配：模板和签名需要匹配，可从 listsms_template 的 Signature 字段确认

故障排查

• - 缺少凭证：检查 /root/.openclaw/.env 文件，如仍找不到请联系 oncall
• 发送失败：先用 listsubaccount、listsignature、listsms_template 确认参数正确
• 鉴权失败：检查自己配置的 AK/SK 是否开通正确
• 权限错误：检查凭证是否正确，如问题持续请联系 oncall
• 欠费错误：请联系 oncall 处理