Open in
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 workTHUNDERPHONE_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 或以上版本。