Wonda CLI
Wonda CLI 是一个面向终端型 AI 代理的内容创作工具包。使用它可以生成图像、视频、音乐和音频;编辑和合成媒体;发布到社交平台;并在 LinkedIn、Reddit 和 X/Twitter 上进行研究与自动化操作。
安装
如果在 PATH 中找不到 wonda,请先安装它:
# 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流程,并附带一个中继范围的wrelay_...凭证,存储在 macOS 钥匙串中。请勿要求用户粘贴 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>将报告限制为一个项目。在组织上下文中,它报告组织范围的使用情况,包括按成员细分——需要管理员/所有者角色。管理员还可以从网页上的组织页面下载完整的 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 始终为您的个人钱包充值,无论上下文如何。充值组织钱包(以及配置自动充值)仅限管理员操作,可在网页上的 /organizations/<slug> 完成。如果成员组织信用额度用尽,错误消息会提示他们请求管理员或切换回个人——他们不能通过 CLI 充值组织钱包。
组织内的角色与席位计划是分开的:
- 所有者:原始创建者。不能被降级或踢出。可以从组织页面将所有权转让给其他成员(极少见)。
- 管理员:可以邀请(单个或批量粘贴)、踢出、更改角色、更改席位、充值、配置自动充值、更改月度限额。
- 用户:只能在组织钱包内消费(如果管理员设置了每人月度限额,则受其限制)。
付费组织席位(WONDA / WONDA_PREMIUM)提供与个人付费计划相同的付费功能访问权限(技能等),但仅在组织上下文中生效。wonda use --personal 会回退到用户的个人账户计划。
访问层级
Wonda 仅限付费:每个产品面(生成、媒体、发布、抓取、分析、技能、云孪生)都需要付费计划。新账户在订阅前没有信用额度和产品访问权限。
| 层级 | 访问权限 |
|---|---|
| 匿名(临时账户,未登录) | 无产品访问权限。CLI 首次运行时创建临时账户,但只能访问以下本地命令以及认证/计费端点。运行 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)。 |
| 本地(无 API 调用、无信用额度、无计划) | 完全在您的机器上运行,因此无需计划即可使用:wonda brand extract <url>(无 --save)、wonda compose motion/wonda compose text、wonda wab record <url>、wonda edit ... 对本地文件进行的 ffmpeg 原始转换、以及 wonda doctor。基于 Chromium 的命令需要一次性 wonda wab install。 |
如果命令返回 403(paid_plan_required),请在 https://wonda.sh/account 订阅。
语音克隆
从 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 "你好世界" \
--model minimax-speech-2-8-hd \
--params '{"voiceId":"<providerVoiceId>"}'
7 天过期:在 TTS 中 7 天未使用的克隆声音会自动过期。使用克隆声音运行 TTS 会自动刷新其过期时间。闲置的声音过期后必须重新克隆(再次花费 $1.50)。
凭证保险库
持久保存在外部平台(Instagram、TikTok、Twitter 等)上创建的登录信息,以便在下次运行时重用。密码使用服务器端密钥进行 AES-256-GCM 加密,仅在 get 时解密。
# 创建
wonda credentials create --website instagram.com --username 我的用户名 \
--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 新用户名
# 删除
wonda credentials delete <id>
# 获取并记录使用原因,一次调用——POST,而非 GET,因为它会写入带有原因的“已使用”事件。只要可能,优先使用此方法而非 `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 UI 的历史图标进行审计。事件日志是仅追加的,并在凭证删除时级联删除。
全局输出标志
所有命令都支持以下输出控制标志:
--json——强制 JSON 输出(stdout 被管道传输时自动启用)--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 保持干净以便管道传输。
每个请求的弃用提示以标准 Warning: 299 - "<message>" HTTP 头部形式到达,并由 CLI 的 HTTP 客户端以 [deprecated METHOD /path] <message> 的形式输出到 stderr。
使用 WONDA_QUIET=1(环境变量)或 --quiet(标志)可以静默这两个通道。使用 WONDA_NO_UPDATE_CHECK=1 禁用仅网络检查。
WAB / Wonda 自动化浏览器(wonda wab)
Wonda 自动化浏览器(WAB)是一款高级隐身反检测浏览器,经过强化,平台无法将其指纹识别为自动化工具。wonda wab 是反检测 Chromium 堆栈(一个未被检测到的 Playwright 分支)的唯一命令。它有两个方面:
- **认证会话。**每个角色一个持久的有头 Chromium,包含 LinkedIn、X、Reddit 等已登录会话。CLI 按需启动它,让它空闲退出,并在命令通过
--via wab运行时,通过它路由平台读取/写入。Cookie 存储在角色 Chromium 配置文件中,而不是~/.wonda/config.json中。 - 匿名捕获。
wonda wab record <url>(以及wonda brand extract)驱动一个临时 Chromium,使用全新的指纹,没有角色,没有 Cookie。请参见下面的record块。
思维模型:您有账户(每个平台一个身份)。每个平台命令通过扁平 JSON 存储(--via cookies,快速,无需 Chromium)或账户的角色(--via wab,实时反检测 Chromium)将路由到该账户的 Cookie。角色是 Chromium 外壳,可以在一个指纹下容纳多个账户。在几乎所有情况下,角色会在首次使用 --via wab 时自动创建,并以账户命名,因此您永远不需要键入角色名称。
本地 wonda.mcpb 桌面扩展从 Claude Desktop 或 Claude Code 使用相同的本地 WAB 路径:平台 Cookie 保留在设备上,读取使用本地 Cookie,写入使用本地 WAB。Claude Web 和 Cowork 需要远程 MCP 连接器。
**原生登录