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

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

```bash
npm install -g thunderphone
thunderphone --help
```

## 登录

```bash
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` 会覆盖该
目录。访问令牌会自动刷新，轮换的刷新令牌会以原子方式保存。登录绝不会输出令牌。

```bash
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` 查看，仅在映射准备就绪且您已审核映射字段和警告后
再提交。请参阅[智能体导入](/zh/guides/import-agents)。

## MCP 设置

```bash
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`
凭据，请使用：

```json
{
  "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` 使用独立设置功能。

## 创建项目

```bash
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 或更高版本。