ThunderPhone v3 現已上線。自助開通,價格低至每分鐘 2¢。查看公告

Getting Started

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 會設定預設設定檔。登出會移除本機憑證; 但不會撤銷伺服器授權。更改或重設密碼,或更改帳戶電郵地址, 則會撤銷授權;請再次執行 thunderphone login。預設 API 為 https://api.thunderphone.com。 如要使用其他 API,請使用 --api-base-url 或 THUNDERPHONE_API_BASE_URL。某個設定檔的權杖 不能傳送至另一個已設定的 API URL;請以獨立設定檔登入該 URL。

指令

每項指令均接受 --json。成功資料會輸出至 stdout;錯誤會輸出至 stderr, 並附帶非零結束代碼。不使用 --json 時,輸出會是精簡表格或欄位清單。 JSON 會保留 API 回應結構,並遮蔽憑證欄位。MCP 服務會保留 stdout 作 MCP 通訊協定使用。

指令用途
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,並支援安全重試
sms list [--limit N], sms get UUID列出或檢視 SMS 記錄
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 可作更改。逾時只會停止等候,不會結束通話。

SMS 亦需要你已連接的 Twilio 或 Telnyx 帳戶中具備 SMS 功能的號碼。 系統絕不會使用 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。預設為專案範圍。Desktop 及 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 可覆寫 端點。程式不會發出遙測資料。你亦可透過 npx -y @thunderphone/mcp setup --client cursor,或在全域安裝 @thunderphone/mcp 後使用 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 或以上版本。