Wonda CLI 是做什麼的？
Wonda CLI 是一款專為終端機代理程式設計的內容創作工具包。您可以使用它來生成圖片、影片、音樂與音訊；編輯和合成媒體；發布到社群平台；以及在 LinkedIn、Reddit 和 X/Twitter 上進行研究與自動化。
安裝
如果系統 PATH 中找不到 wonda，請先安裝。建議安裝方式為簽署的桌面安裝程式（CLI + 托盤圖示 + 常駐中繼，無需額外步驟）：macOS 請執行 brew install --cask degausai/tap/wonda-app（或從版本發布頁下載 wonda-macos.pkg），Windows 請使用 winget / wonda-windows-setup.exe。以下純 CLI 方式可在所有環境運作，之後可再用 wonda app install 安裝桌面應用程式：
# npm
npm i -g @degausai/wonda
# Homebrew
brew tap degausai/tap && brew install wonda
設定
- 認證：
wonda auth login（開啟瀏覽器，建議使用）或設定WONDA_API_KEY環境變數。 - 驗證：
wonda auth check
OAuth 連接器認證
Claude Web 和 Cowork 連接器使用 Wonda 的 OAuth 2.1 流程，而非 CLI API 金鑰欄位。該連接器透過瀏覽器登入 Wonda，授權要求的帳戶存取權限，並接收綁定 Wonda API 資源的 OAuth 權杖。伺服器僅在 Wonda 內部將這些權杖交換為帳戶內部 API 金鑰，因此代理程式和連接器主機永遠不會看到 sk_... 金鑰。對於 CLI 和本地 stdio MCP 路徑，請繼續使用 wonda auth login 或 WONDA_API_KEY。
Claude Cowork 本地中繼
Claude Cowork（桌面應用程式）在本機執行本地 MCP 伺服器，因此可以直接載入 .mcpb 套件或本地 stdio wonda-mcp 設定（包含 WAB 寫入功能，驗證日期 2026-07-07）。Claude Web 則無法做到。Wonda 本地中繼是替代路徑：它允許遠端連接器（Web 或 Cowork）在使用者自己的 Mac 和住宅 IP 上執行動作，無需任何本地 MCP 設定：
- 在登入狀態下開啟
https://wonda.sh/download，安裝經過公證的 Mac 套件。 - 使用
wonda relay pair或首次執行的瀏覽器交接來配對中繼。這會使用現有的cli-auth流程，並在 macOS 鑰匙圈中儲存一個中繼範圍的wrelay_...憑證。請不要要求使用者貼上 API 金鑰或裝置代碼。 - 開啟
https://wonda.sh/setup，透過有頭部的本地 WAB 連接 LinkedIn、X 和 Reddit，然後在 Claude 中批准 Wonda 連接器。
引擎策略為 auto | my_machine | cloud。auto 會在中繼在線時使用本地中繼，離線時使用雲端。my_machine 不得靜默回退：如果中繼離線，請詢問是否要切換到雲端。
組織與支出情境
Wondercat 組織是共享錢包，擁有自己的席位和帳單。成員可以透過切換情境來從組織錢包消費（而非使用個人額度）：
wonda organizations list（別名：wonda orgs list,wonda org list）— 檢視您所屬的每個組織以及您在其中的角色和席位方案。wonda use --org <slug>— 為此機器設定固定的組織情境。在每個請求上設定X-Wonda-Org；所有扣款、請款和wonda balance都會透過組織錢包進行。wonda use --personal— 切回個人情境。wonda usage— 僅顯示支出的使用摘要（總計 + 各模型 + 各專案明細），可指定期間（--month 2026-05，或--from/--to；預設為當月 UTC）。--project <name>將報告限制為單一專案。在組織情境中，它會報告組織範圍的使用情況，包含每位成員的明細 — 需要管理員/擁有者角色。管理員也可以從 Web 上的組織頁面下載完整的 Excel 報告。
專案（支出標記）
專案將支出歸因於指定的工作流程以便監控。代理程式應在任務開始時檢查當前專案（wonda use 會顯示），並在操作者按專案監控支出時為每個任務設定一個專案：
wonda use --project <name>— 固定設定：後續的每次扣款都會帶上該專案（在wonda usage、API 和組織 Excel 報告中）。wonda use --no-project停止標記；切換組織/個人情境會自動清除專案（專案是依範圍而定的）。- 在任何指令後加上
--project <name>— 僅該次呼叫的單次覆蓋。 wonda project list|create|delete— 在當前作用範圍內管理專案註冊表。組織專案僅能由組織管理員/擁有者建立；個人專案則可自行服務。將支出標記到不存在的名稱會失敗並回報unknown_project（不會靜默建立新分類，因此拼寫錯誤不會分散監控資料）。
wonda topup 永遠只為您的個人錢包充值，無論當前情境為何。為組織錢包充值（及設定自動充值）僅限管理員操作，需在 Web 的 /organizations/<slug> 頁面進行。如果成員用完組織額度，錯誤訊息會請他們要求管理員或切回個人錢包 — 他們無法從 CLI 為組織錢包充值。
組織內的角色與席位方案是分開的：
- 擁有者：原始建立者。不能被降級或踢除。可以在組織頁面上將所有權轉移給另一位成員（很少見）。
- 管理員：可以邀請（單一或批次貼上）、踢除、變更角色、變更席位、充值、設定自動充值、變更每月限額。
- 使用者：只能在組織錢包內消費（如果管理員設定了每位成員每月限額，則受其限制）。
付費組織席位（WONDA / WONDA_PREMIUM）賦予與個人付費方案相同的付費功能存取權（技能等），但僅限在組織情境中。wonda use --personal 會回退到使用者的個人帳戶方案。
存取層級
Wonda 是純付費服務：每個產品功能都需要付費方案，包括 API 呼叫、本地平台讀取、瀏覽器自動化、媒體合成、檔案編輯、診斷、生成、發布、爬取、分析、技能、中繼操作和雲端分身。在任何產品指令執行工作之前，CLI 會對 Wonda 進行即時權利檢查。當無法驗證存取權限時，檢查會以失敗閉合。新帳戶在訂閱之前沒有任何產品存取權限，且正數的額度餘額不能取代方案。
| 層級 | 存取權限 |
|---|---|
| 匿名（未登入） | 無產品存取權限。認證、設定、定價、組織探索/選擇、Shell 自動完成和本地關機指令仍然可用，以便使用者訂閱、恢復或停止背景服務。請執行 wonda auth login，然後訂閱。 |
| 免費（已登入，無付費方案） | 無產品存取權限。請前往 https://wonda.sh/account 訂閱以使用產品。 |
| WONDA（每月 $19.99，「Pro」） | 除雲端分身外的所有功能：生成（image/generate, video/generate, ...）、媒體上傳/下載、發布、爬取、分析、影片分析、技能（wonda skill install/list/get）、轉場、剪輯、電子郵件、reddit/linkedin 帳號建立、樣式、品牌。 |
| WONDA_PREMIUM（每月 $49.99，「Premium」） | WONDA 的所有功能，加上雲端分身（wonda twin：佈建、排程執行、串流登入），附帶反偵測/影子封鎖保護、無上限，以及美國帳號建立。 |
| 被標記（每個帳號的 PostHog 關閉開關） | 包含在付費方案中，但仍可透過每個帳號的開關進行閘控：wonda reddit signup（redditAccountCreationEnabled）、wonda email（emailServerApiEnabled）、公開 LinkedIn 個人資料豐富化（linkedinProfileEnrichmentEnabled）。 |
如果指令回傳 403（paid_plan_required），請前往 https://wonda.sh/account 訂閱。
這也適用於本地 stdio MCP 路徑，因為 MCP 執行的是同一個 CLI。平台 Cookie 和資料保留在裝置上，但指令必須先從 GET /api/v1/auth/access 收到成功的付費存取決定。僅安裝中繼的安裝可以使用其範圍限定的 wrelay_... 憑證進行該權利探測。該範圍限定的憑證仍然無法呼叫一般的帳戶 API。
語音複製
從 10 秒以上的音訊片段複製語音，並在 TTS 中使用。每個帳戶限制：20 個複製語音。費用：每個複製 $1.50。
# 從本地檔案複製（會先自動上傳到媒體庫）
wonda voice create "Andu" --file ./sample.mp3 --description "我的語音"
# 從現有的 wonda 媒體複製
wonda voice create "Brand" --media-id <uuid>
# 可選的來源音訊前處理
wonda voice create "Clean" --file ./raw.wav --noise-reduction --normalize-volume
# 列出已複製的語音（每行報告 isExpired 和 expiresInDays）
wonda voice list
# 單一語音
wonda voice get <voice-id>
# 重新命名 / 重新描述（僅本地，不呼叫供應商）
wonda voice update <voice-id> --name "新名稱" --description "..."
# 刪除
wonda voice delete <voice-id>
在 TTS 中使用已複製的語音：將 voice get 傳回的 providerVoiceId 作為 voiceId 傳遞給 /audio/speech：
wonda audio speech "Hello world" \
--model minimax-speech-2-8-hd \
--params '{"voiceId":"<providerVoiceId>"}'
7 天有效期：如果已複製的語音在 7 天內未在 TTS 中使用，將會自動過期。使用已複製語音執行 TTS 會自動刷新其有效期。閒置的語音過期後必須重新複製（再次花費 $1.50）。
憑證保管庫
持久儲存在外部平台上建立的登入資訊（Instagram、TikTok、Twitter 等），以便下次執行時重複使用。密碼使用伺服器端的金鑰進行 AES-256-GCM 加密，僅在 get 時解密。
# 建立
wonda credentials create --website instagram.com --username myhandle \
--email [email protected] --password-stdin <<< "hunter2" \
--metadata '{"signup_source":"wonda-email"}'
# 列出（省略密碼）
wonda credentials list --website instagram.com
# 取得完整記錄，包含解密的密碼
wonda credentials get <id>
# 更新任何欄位（使用 --password-stdin 輪換密碼；使用 --username "" 清除）
wonda credentials update <id> --username newhandle
# 刪除
wonda credentials delete <id>
# 一次呼叫取得並記錄使用原因 — 使用 POST 而非 GET，因為它會寫入一個 'used' 事件並附上原因。只要能夠說明原因，請優先使用此方式而非 `get`。
wonda credentials use <id> --reason "instagram 註冊流程"
# 檢視近期事件（建立/使用/輪換/更新）以進行稽核
wonda credentials events <id>
欄位：website（必要 — 輸入如 insta 這類文字時會標準化為 instagram.com）、username、email、password（必要）、metadata（任意 JSON）。username / email 至少需要一個。每個 (website, username) 組合允許多筆記錄 — 如有需要請自行去重。
事件日誌：每次 credentials get/use、create、密碼輪換及其他更新都會記錄為該憑證的事件（行為者：cli | web | system）。請使用 credentials events <id> 或 Web 介面的歷史記錄圖示進行稽核。事件日誌僅可附加，且在刪除憑證時會級聯刪除。
全域輸出旗標
所有指令都支援以下輸出控制旗標：
--json— 強制輸出 JSON（當 stdout 被 pipe 時會自動啟用）--quiet— 僅輸出主要識別碼（任務 ID、媒體 ID 等）— 適合腳本使用-o <path>— 將輸出下載到檔案（隱含--wait）--fields status,outputs— 選擇特定的 JSON 欄位--jq '.outputs[0].media.url'— 使用 jq 表達式過濾 JSON 輸出
CLI 公告與棄用警告
每次執行指令時，CLI 會輪詢 GET /api/v1/updates（匿名，在 ~/.wonda/state.json 中快取 1 小時）以取得作用中的公告：棄用通知、事件預警、升級提示。訊息只會輸出到 stderr，因此 stdout/JSON 保持乾淨以便 pipe。
每個請求的棄用提示會以標準的 Warning: 299 - "<message>" HTTP 標頭形式到達，並由 CLI 的 HTTP 客戶端在 stderr 上顯示為 [deprecated METHOD /path] <message>。
使用 WONDA_QUIET=1（環境變數）或 --quiet（旗標）可同時靜音這兩個管道。使用 WONDA_NO_UPDATE_CHECK=1 可僅停用網路檢查。
WAB / Wonda 自動化瀏覽器（wonda wab）
1Password 已包含在本地 WAB 設定檔中。 WAB 會下載穩定的官方 1Password 瀏覽器擴充功能，驗證其發行者簽章，並在首次設定時將其釘選到工具列。使用 wonda wab show <persona> 開啟 WAB，然後點擊 1Password 進行登入。每個角色都保有各自的 1Password 工作階段。桌面應用程式可能會要求您將 WAB 核准為額外的瀏覽器；直接在擴充功能中登入也同樣可行。快取的擴充功能檔案可在離線時運作。WAB 最多每天檢查一次快取擴充功能的更新（在角色啟動時），包含失敗的檢查；變更 Chromium 版本會觸發另一次相容性檢查。如果擴充功能從未成功安裝，每次啟動都會重試安裝。已在執行的瀏覽器會在下一次啟動時套用擴充功能更新。啟動和 wab install 會清除超過七天的未使用快取版本；正在使用的 WAB 處理程序中的版本會保留。在啟動 WAB 之前設定 WAB_ONEPASSWORD=0 可跳過內建的擴充功能。匿名擷取、草稿工作階段和雲端分身不會載入它。包含逗號的 Wonda 資料路徑也會跳過 1Password 並顯示警告。
wab 的子指令：show, list, close, cleanup（清除孤立 WAB）。
媒體庫
wonda media upload 會將檔案上傳到您的 Wonda 媒體庫並傳回一個 UUID，可在生成指令中作為 --media-id 使用，或作為參考圖像、影片等。媒體庫可用於語音複製（上傳範例音訊）、圖像生成（參考影像）等。使用 wonda media list 列出媒體庫中的項目，使用 wonda media get <uuid> 取得單一項目的詳細資料。
提示詞與參數
所有生成模型（影像、影片、音訊、音樂）都接受 --prompt 字串和 --params JSON 物件（或 --params '{"key":"value"}'）來傳遞模型特定的參數。請查閱模型的文件以了解可用的參數。--size 或 --aspect 等通用參數會自動對應到 --params 中。--wait 會讓 CLI 等待直到輸出準備就緒，而非立即傳回任務 ID。--model 選擇生成模型（例如 stabilityai/stable-diffusion-3.5-large 用於影像，minimax/video-01 用於影片）。--count 指定要生成的輸出數量。
社交平台發布
Wonda 可以發布到 LinkedIn、Reddit 和 X/Twitter。每個平台都需要透過 WAB 進行認證：
# 發布到 LinkedIn
wonda linkedin post "這是我的 LinkedIn 貼文" --image <media-id>
# 發布到 Reddit
wonda reddit post --subreddit "r/artificial" --title "我的標題" --body "貼文內容"
# 發布到 X/Twitter
wonda x post "這是一則推文" --media <media-id>
--schedule 可讓您延遲發布（例如 --schedule "2026-07-07T14:00:00Z"）。各平台也支援分析功能（wonda linkedin analytics, wonda reddit analytics, wonda x analytics）。
自動化與研究
Wonda 可以爬取 LinkedIn、Reddit 和 X/Twitter 以進行研究：
# LinkedIn 個人資料豐富化
wonda linkedin enrich --url "https://www.linkedin.com/in/..."
# Reddit 子版塊分析
wonda reddit analyze --subreddit "r/machinelearning" --limit 50
# X/Twitter 趨勢
wonda x trends
疑難排解
如果遇到問題：
- 認證錯誤：執行
wonda auth login重新認證。 - 403 錯誤：確保您有有效的付費方案。執行
wonda auth check驗證您的方案層級。 - 中繼離線：對於桌面應用程式，請確認 Wonda 桌面應用程式正在執行，且中繼已配對（
wonda relay status）。 - 媒體上傳失敗：檢查檔案是否存在且為支援的格式。
- 社交平台發布失敗：請在
https://wonda.sh/setup確認平台已連接。
如需更多協助，請參閱 https://wonda.sh/docs 或執行 wonda help。