ThunderPhone 2.0 正式上线。全程自助，低至2美分/分钟。查看发布公告
立即开始

Getting Started

View as Markdown
Open in
ClaudeChatGPTCursor

ThunderPhone CLI

通过终端登录、管理语音智能体和通话、配置 MCP 客户端以及搭建项目脚手架。

CLI 要求 Node.js 18.18 或更高版本。使用 npx 运行，或全局安装：

npm install -g thunderphone
thunderphone --help

登录

npx thunderphone login
thunderphone whoami --json

登录会输出验证码、打开浏览器，并等待授权。 在无头设备上使用 --no-browser，然后在其他设备上打开输出的 URL。 设备登录要求 API 已启用 OAuth 设备流程。您也可以在 THUNDERPHONE_API_KEY 中使用组织 API 密钥对命令进行身份验证，该密钥优先于已存储的登录凭据。

凭据按配置文件存储在 ~/.config/thunderphone/credentials.json 中， 文件权限为 0600。XDG_CONFIG_HOME 和 THUNDERPHONE_CONFIG_DIR 会覆盖该 目录。访问令牌会自动刷新，轮换的刷新令牌会以原子方式保存。登录绝不会输出令牌。

thunderphone login --profile work
thunderphone agents list --profile work --json
thunderphone logout --profile work

THUNDERPHONE_PROFILE 用于设置默认配置文件。注销会删除本地凭据； 不会撤销服务器授权。默认 API 为 https://api.thunderphone.com。 如需使用其他 API，请使用 --api-base-url 或 THUNDERPHONE_API_BASE_URL。某个配置文件的令牌 无法发送到不同的已配置 API URL；请使用单独的配置文件登录该 URL。

命令

每个命令都接受 --json。成功数据会输出到 stdout；错误会输出到 stderr， 并使用非零退出代码。不使用 --json 时，输出为紧凑表格或字段列表。 JSON 会保留 API 响应结构，但凭据字段会被脱敏。MCP 服务会为 MCP 协议 保留 stdout。

命令用途
login [--no-browser] [--scope "scopes"]通过设备代码授权
logout, whoami移除本地凭据；列出可访问的组织
agents list, agents get ID读取智能体
agents create --file agent.json创建智能体
agents update ID --file agent.json保存智能体草稿
agents deploy ID, agents delete ID部署草稿；删除智能体
numbers list读取电话号码
numbers provision --country US --area-code 415开通美国入站号码
numbers assign NUMBER_ID --agent ID分配入站智能体
sms send TO --from FROM --body TEXT --idempotency-key KEY通过客户已连接的运营商号码发送短信，并支持安全重放
sms list [--limit N], sms get UUID列出或查看短信记录
call TO --agent ID --from FROM [--wait]发起外呼；可选择等待其转录文本
calls list [--limit N] [--agent ID]列出通话（限制为 1–200）
calls get ID, calls transcript ID读取单次通话或其转录文本
test run AGENT_ID [--scenario ID] --consent-to-charge使用网页渠道运行可计费的已保存场景
test status RUN_ID [--agent ID]查看批次；提供智能体时会显示场景详情
import VENDOR export.json准备供应商 JSON 导入以供审核
imports get UUID, imports commit UUID查看导入；审核后提交选定的智能体
mcp setup, mcp serve配置客户端；启动 stdio 桥接
init [directory]生成项目脚手架

外呼需要支持外呼的号码。THUNDERPHONE_FROM_NUMBER 可以 提供 --from。客户 VoIP 号码仍支持外呼。 ThunderPhone 开通的号码起初仅支持入站；组织管理员可以在“电话号码”页面 请求启用外呼，每项请求都会经过人工审核。--wait 默认超时为一小时；设置 --timeout SECONDS 可进行更改。超时会停止等待，但不会结束通话。

短信还需要您已连接的 Twilio 或 Telnyx 账户中具备短信功能的号码。短信绝不会通过 ThunderPhone 所有的号码发送。仅当重试完全相同的发件人、收件人和正文时， 才重复使用幂等键。

导入支持 vapi、retell、elevenlabs 和 bland。第二个参数是 供应商 JSON 导出的路径，而不是远程供应商 ID。API 会异步准备映射； 使用 imports get UUID 查看，仅在映射准备就绪且您已审核映射字段和警告后 再提交。请参阅智能体导入。

MCP 设置

thunderphone mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY
thunderphone mcp setup --client codex --scope user --api-key-env THUNDERPHONE_API_KEY
thunderphone mcp setup --client claude-desktop --scope user

支持的客户端：claude-code、codex、cursor、vscode、gemini、claude-desktop 和 windsurf。默认使用项目作用域。桌面客户端和 Windsurf 需要使用用户作用域。 省略 --client 可从项目中检测单个客户端；如果检测结果不明确，将以交互方式提示您，或在非交互会话中失败并显示说明。 设置会输出其写入的文件，并保留无关的服务器。现有 JSON 必须是有效的严格 JSON；Codex TOML 值会被保留，但注释可能会被重新格式化。

设置优先使用直接远程 HTTP。使用 --api-key-env 时，它会写入变量 引用，绝不会写入密钥。未使用该选项时，直接 HTTP 依赖客户端的 OAuth 支持；它不会使用 CLI 凭据文件。若要在任何支持 stdio 的客户端中复用 thunderphone login 凭据，请使用：

{
  "mcpServers": {
    "thunderphone": {
      "command": "npx",
      "args": ["-y", "@thunderphone/mcp"]
    }
  }
}

该包装器会先检查 THUNDERPHONE_API_KEY，然后检查当前 CLI 配置文件（必要时会刷新）， 接着将 OAuth 委托给 mcp-remote。THUNDERPHONE_MCP_URL 会覆盖 端点。它不会发送遥测数据。安装 @thunderphone/mcp 全局版本后，也可以通过 npx -y @thunderphone/mcp setup --client cursor 或 thunderphone-mcp setup 使用独立设置功能。

创建项目

npx create-thunderphone-agent my-receptionist
npx create-thunderphone-agent my-outbound --template python --agent-type outbound
# Equivalent:
thunderphone init my-receptionist --template node --agent-type receptionist

模板包括 node 和 python；智能体类型包括 receptionist、outbound 和 custom。默认智能体是配备明确演示事实的英语/西班牙语牙科接待智能体。项目包含 agent.json、部署脚本、适用于 Claude Code、Cursor 和 VS Code 的 MCP 配置、智能体指令、.env.example 以及 README。 脚手架生成可离线完成，并且不会覆盖非空目录。

部署前请编辑业务事实。按照生成的 README 中的说明，导出 API 密钥、已连接的主叫号码 以及您的测试接收号码。npm run deploy 或 python deploy.py 会创建或更新智能体、部署其草稿，并发起一次计费测试通话。 这些脚本使用 API 密钥认证；CLI 和 stdio MCP 包装器也支持设备登录。Python 脚本需要 Python 3.9 或更高版本。