wangwo-cli

旺喔只读 CLI，通过 AIKE MCP Server 查询 WoW 时刻、记忆、知识库、专家、会话和技能。面向 Codex、WorkBuddy、Claude Code、JVS Crew 等支持调用本地命令的 Agent Host。

能力边界

• 只提供查询命令，不提供写入和删除命令。
• 不开放 BLE、Wi-Fi 快传、录音控制、设备文件、解绑和 OTA。
• 扫码授权后，用户身份由服务端根据 access token 注入，CLI 不接收其他用户 ID。
• 第三方 Host 托管凭证模式仍受支持，用于受控部署和兼容现有接入。

安装

npm install -g wangwo-cli
wangwo-cli --version

要求 Node.js 22 或更高版本。

升级或卸载：

npm install -g wangwo-cli@latest
npm uninstall -g wangwo-cli

从源码参与开发请阅读 CONTRIBUTING.md。

扫码登录

wangwo-cli auth login

命令会直接在终端显示二维码，不会默认打开网页。打开旺喔 App，使用个人中心扫一扫扫描二维码并确认只读授权；CLI 轮询到授权成功后保存凭证：

• macOS 优先保存到系统 Keychain。
• 其他系统或 Keychain 不可用时，按 Profile 保存到 ~/.config/wangwo-cli/profiles/<name>.json，目录权限为 0700，文件权限为 0600。旧版 credentials.json 会自动迁移为 default Profile。
• access token 到期前自动使用 refresh token 刷新。
• CLI 不输出 access token 和 refresh token 明文。

可用以下命令检查或撤销当前终端授权：

wangwo-cli auth status --format json
wangwo-cli auth logout

auth logout 会先请求服务端撤销授权，再清除本地凭证。仅需清理本地凭证时使用 wangwo-cli auth logout --local-only。

需要同时打开浏览器兜底，或不希望输出终端二维码时，可以分别使用：

wangwo-cli auth login --browser
wangwo-cli auth login --no-qr

在 AI Agent 中授权

Codex、WorkBuddy、Claude Code、Cursor 等 Agent 不应阻塞等待扫码。Agent 应发起授权、生成二维码图片并在对话中展示：

wangwo-cli auth login --agent-name Codex --no-wait --no-qr --qr-output wangwo-auth.png --format json

用户在旺喔 App 扫码并点击允许后，Agent 再完成授权和验证：

wangwo-cli auth login --resume --format json
wangwo-cli auth status --verify --format json
wangwo-cli config list --format json

--no-wait 会把待授权凭证按 Profile 保存到 ~/.config/wangwo-cli/pending-auth/，不会把 device code、access token 或 refresh token 输出到 Agent 上下文。裸 auth login 仍保留阻塞模式，供人工终端使用。

授权列表默认按“设备名 · Agent 名 · wangwo-cli”识别来源。Codex 和 Claude Code 可自动识别；其他宿主可传 --agent-name WorkBuddy，或设置 WANGWO_AGENT_NAME=WorkBuddy。--device-name 仍可完整覆盖展示名称。

最小 Scope 与增量授权

首次登录不传 --scope 时，保持兼容并申请全部只读 Scope。需要最小权限时可以只申请指定能力：

wangwo-cli auth login --scope "wow:read memory:read"

已登录的 Profile 再次执行带 --scope 的登录命令时，会把新增 Scope 与原 Scope 合并后重新授权；已具备所需 Scope 时不会重复发起授权：

wangwo-cli auth login --scope "knowledge:read"

允许的 Scope 为 wow:read、memory:read、knowledge:read、expert:read、chat:read、skill:read。未知 Scope 和写权限会被客户端与服务端同时拒绝。使用 --force --scope 可按指定 Scope 完整替换当前权限集合。

多账号 Profile

默认 Profile 名称为 default。通过 auth login --profile <name> 创建或更新 Profile，使用 profile use 切换默认账号：

wangwo-cli auth login --profile work --scope "wow:read memory:read"
wangwo-cli auth login --profile personal
wangwo-cli profile list --format json
wangwo-cli profile use work
wangwo-cli profile remove personal

所有命令都支持全局 --profile <name>，参数可放在子命令前后；它只影响本次调用，不修改默认 Profile：

wangwo-cli --profile work wow list --limit 10
wangwo-cli memory latest --profile personal

也可以通过 WANGWO_PROFILE 指定本次进程使用的 Profile。profile remove 默认同时撤销服务端授权，--local-only 仅删除本地凭证。

Agent 接入

1. 在运行 Agent Host 的机器上安装 wangwo-cli，确保命令位于 PATH。
2. Agent 执行非阻塞授权命令并在对话中展示二维码，用户使用旺喔 App 扫码确认只读授权。
3. 将仓库中的 skills/wangwo-cli 注册到支持 Skill 的 Agent Host，或直接允许 Agent 调用 wangwo-cli 命令。
4. 执行 wangwo-cli config list --format json，确认 ready=true。

每台电脑或 Agent 运行环境独立授权，可在旺喔 App 的“账号与安全 > 第三方授权”中查看和撤销。

Host 环境变量兼容模式

受控 Host 可以不使用本地扫码凭证，改为注入以下环境变量：

| 变量 | 必填 | 说明 | |---|---:|---| | AIKE_MCP_SERVER_URL | 是 | 受控 Host 的内部 MCP 地址，例如 test 环境的 /mcp/aike 地址；扫码授权 Profile 使用服务端返回的 /mcp/wangwo-cli | | AIKE_MCP_ACCESS_TOKEN | 是 | Host 托管的 AIKE MCP access token | | AIKE_USER_ID | 否 | 仅旧 Host token 需要；扫码授权 token 不需要客户端传用户 ID | | WANGWO_API_BASE_URL | 否 | 扫码授权 API 地址，默认 https://aike.wangxiaobao.com | | AIKE_USER_TIMEZONE | 否 | 用户时区，默认 Asia/Shanghai | | WANGWO_PROFILE | 否 | 本次调用使用的 Profile；命令行 --profile 优先 |

AIKE_MCP_SERVER_URL 和 AIKE_MCP_ACCESS_TOKEN 必须同时配置。环境变量模式优先于本地凭证。 扫码授权模式只向 Gateway 发送 Bearer token，不发送 userId；用户身份和授权实例由 Gateway 校验 token 后注入。

快速验证

wangwo-cli config list --format json
wangwo-cli wow list --limit 10
wangwo-cli memory latest --limit 10
wangwo-cli expert list

命令

wangwo-cli auth login [--api-base-url <url>] [--device-name <name>] [--agent-name <name>] [--scope <scopes>] [--no-wait] [--resume] [--qr-output <path>] [--browser] [--no-qr] [--force]
wangwo-cli auth qrcode <url> --ascii
wangwo-cli auth qrcode <url> --output wangwo-auth.png
wangwo-cli auth status
wangwo-cli auth logout [--local-only]
wangwo-cli profile list
wangwo-cli profile use <name>
wangwo-cli profile remove <name> [--local-only]

wangwo-cli wow list [--cursor <cursor>] [--limit 10] [--card-type <type>]
wangwo-cli wow get <cardId> [--offset 0] [--limit 12000]

wangwo-cli memory search <query> [--limit 10] [--source <source>]
wangwo-cli memory latest [--limit 10] [--source <source>]
wangwo-cli knowledge search <query> [--top-k 5]

wangwo-cli expert list
wangwo-cli expert methods --expert-code <code>

wangwo-cli chat sessions [--limit 20] [--next-token <token>]
wangwo-cli chat history <sessionId> [--limit 50] [--next-token <token>]

wangwo-cli skill list [--keyword <keyword>] [--bound true|false] [--page 1] [--size 20]
wangwo-cli skill get <skillCode>

每个命令都支持全局 --profile <name>；每个查询命令还支持 --format toon|json|yaml，默认 TOON。

分页约定

• wow list 返回 nextCursor，下一页原样传给 --cursor。CLI 不按 businessDate 聚合或重排。
• wow get 返回 hasMore=true 时，将 nextOffset 传给下一次 --offset。
• chat 命令沿用 JVS 返回的 nextToken。

后端依赖

扫码登录依赖以下授权接口：

• POST /api/mcp/device-authorizations
• POST /api/mcp/device-authorizations/token
• POST /api/mcp/device-authorizations/token/refresh
• POST /api/mcp/device-authorizations/token/revoke

CLI 依赖 AIKE MCP Server 注册以下只读工具：

• aike_activity_card_list
• aike_activity_card_get
• aike_knowledge_search_memory_search
• aike_knowledge_search_knowledge_search
• aike_expert_list
• aike_expert_work_method_list
• aike_chat_session_list
• aike_chat_session_history
• aike_skill_list
• aike_skill_get

后端必须从扫码授权 token 的绑定关系注入用户身份，并按授权 scope 过滤可见工具。