degausai/wonda

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 配置：

1. 登录后打开 https://wonda.sh/download，安装经过公证的 Mac 包。
2. 使用 wonda relay pair 或首次运行的浏览器交接来配对中继。这使用现有的 cli-auth 流程，使用存储在 macOS 钥匙串中的中继作用域 wrelay_... 凭证。不要让用户粘贴 API 密钥或设备代码。
3. 打开 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 "你好世界" \
  --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 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）

1Password 已包含在本地 WAB 配置文件中。 WAB 下载官方的稳定版 1Password 浏览器扩展，验证其发布者签名，并在首次设置时将其固定到工具栏。使用 wonda wab show <persona> 打开 WAB，然后点击 1Password 登录。每个人物都保留自己的 1Password 会话。桌面应用可能需要你批准 WAB 作为附加浏览器；直接在扩展中登录也有效。缓存的扩展文件可以在离线状态下工作。WAB 每天最多检查一次缓存的扩展更新（在人物启动时），包括失败的检查；更改 Chromium 版本会触发另一次兼容性检查。如果扩展从未成功安装，每次启动都会重试安装。已在运行的浏览器会在下次启动时获取扩展更新。启动和 wab install 会清理超过七天的未使用缓存版本；活动 WAB 进程使用的版本会被保留。在启动 WAB 之前设置 WAB_ONEPASSWORD=0 以跳过捆绑的扩展。匿名捕获、暂存会话和云端双生不会加载它。包含逗号的 Wonda 数据路径也会跳过 1Password，并发出 dr...