讯飞云 CLI 使用指南

认识 CLI#

快速开始

npm install -g @xfyun/cli
xfyun skill install --auto
xfyun --version

# 在讯飞开放平台控制台创建 CLI 令牌: https://console.xfyun.cn/xfyun-cli/tokens
xfyun console login "<CLI令牌>"
xfyun console app list --json

使用前提：Node.js 18 或更高版本；讯飞开放平台账号；通过 CLI 创建应用要求完成实名认证，控制台创建流程以页面提示为准

xfyun skill install --auto 会安装随包的 Agent Skill，供 Claude Code、Codex、AStudio 识别命令和使用说明；不使用 Agent 时可以跳过。安装或更新 CLI 后重新执行一次，并重启 Agent 会话

账号下没有应用时，按 app list 输出中的链接完成实名认证，并到控制台「我的应用」创建首个应用；已实名用户也可以使用 xfyun console app create --config 创建。应用创建不会自动开通能力或获得调用量

登录并创建应用后，可以先用能力清单和能力百科确认目标能力：

xfyun run capabilities --json
xfyun explain tts --json
xfyun demo tts

语音能力

超拟人合成先用 xfyun run uts --list-voices 查看当前应用已开通的发音人；加 --all 查看全部可选并标记已开通项。发音人授权在控制台「应用 → 语音合成 → 超拟人语音合成 → 发音人授权管理」完成

文本、识别与图像

知识、生成与审核

表中“链接待补”表示该变体的产品页链接尚未取得，待 PM 补充；不影响命令本身可用性

控制台与本地工具

使用路径：安装 → 登录 CLI 令牌 → 检查实名与 APPID → 检查能力与用量 → 执行任务

能力目录不代表当前应用已开通；开通、领取、购买和续费由用户在开放平台完成

安装与更新#

全局安装

npm install -g @xfyun/cli
xfyun skill install --auto
xfyun --version

项目内安装

npm install @xfyun/cli
npx xfyun skill install --auto
npx xfyun --version

npx xfyun 依赖项目内已安装的 @xfyun/cli；未安装时请使用全局安装

更新

npm install -g @xfyun/cli
xfyun skill install --auto

xfyun skill install --auto 会自动写入检测到的 Claude Code、Codex、AStudio 用户级技能目录。其他 Agent 用 --target <技能根目录> 指定；也可以用 xfyun skill path 查看随包 Skill 目录。未检测到常见 Agent 时，按提示用 --target 指定；--auto 与 --target 二选一。更新 CLI 后重新执行安装并重启会话

使用智能体安装时，可直接发送：

帮我安装讯飞云 CLI：运行 npm install -g @xfyun/cli，然后运行 xfyun skill install --auto 和 xfyun --version 确认安装成功。

连接账号#

在讯飞开放平台控制台「CLI 访问令牌」创建 CLI 令牌（访问令牌）：

• 名称用于区分设备和用途；有效期为 1～90 天，建议使用满足任务的最短期限
• 令牌只展示一次，关闭页面后无法再次查看，请立即复制
• 令牌绑定创建者本人账号，当前不区分接口权限

登录并验证：

xfyun console login "<CLI令牌>"
xfyun console app list --json

令牌作为命令参数传入。CLI 会在输出和错误信息中脱敏，但令牌可能留在 shell 历史或进程列表；登录后建议清理历史，不要在共享终端登录

本机配置位置：

• Windows：%APPDATA%\\xfyun-console\\config.json
• 其他系统：~/.config/xfyun-console/config.json
• 权限：POSIX 0600；Windows 使用当前用户 ACL

xfyun console logout 只清理本机配置；令牌撤销见第 7 节

准备应用#

实名认证

通过 CLI 创建应用前需要完成实名认证；新账号建议先完成实名，再到控制台创建首个应用。入口：

https://console.xfyun.cn/user/authentication

官方快速指引：第四步：完成实名认证

• 按实际主体选择个人或企业认证；企业用户不能以个人身份认证
• 提交后可用 xfyun console account certification --json 查询状态：
  • verified：已通过，可以创建应用
  • unverified：未认证，先完成实名
  • pending：审核中，等待审核完成
  • rejected：未通过，到控制台查看原因并重新提交
• 未实名时 CLI 创建应用会返回 30006；只有 verified 可以创建应用
• 实名认证解决的是账号主体资格，不代表已开通具体能力或获得调用量

应用列表与创建

每次能力调用使用一个 APPID。未指定 --app 时，CLI 使用控制台的默认应用

xfyun console account certification --json
xfyun console app list --json
xfyun console app list --keyword "产品测试" --json
xfyun console app get <APP_ID> --json
xfyun console app default --json
xfyun console app categories --json
xfyun console app create --config app.json --json

app default 只查询默认应用，不设置默认应用；默认应用在控制台设置（应用管理）。--app 只接受 APPID，不接受应用名称；名称请先用 app list --keyword 查询

创建应用的配置示例：

{
  "appName": "产品测试",
  "appOs": "web",
  "appCategory": "应用-办公商务-其他",
  "appDescr": "用于 CLI 联调"
}

规则：

• 名称、分类、描述不能为空
• 名称最多 30 个字符，只能包含中文、字母、数字和 - . _，且不能与当前账号已有应用重名
• 描述最多 300 个字符
• appCategory 必须使用 app categories --json 返回的真实分类
• 非交互环境必须传 --config；缺少字段时 CLI 会指出具体字段

账号下没有应用时，默认引导到控制台创建；已实名用户明确要求时也可以使用 CLI 创建。创建应用不代表开通能力或获得调用量

能力与调用量#

三个入口不要混用：

• xfyun console capability list --json：平台能力目录，包含 businessId、名称、文档地址；不代表当前应用已开通
• xfyun run capabilities --json：CLI 当前支持的能力、命令、凭据映射和状态；同样不代表当前应用已开通
• xfyun explain <能力> [--app <APP_ID>] --json：能力百科，给出前置条件、凭据形态、输入限制、计费单位、示例、产品页、控制台和文档；带 --app 时同时展示该应用用量

每项能力的产品页由 xfyun explain <能力> --json 与 xfyun run capabilities --json 的 product_url 返回；能力表已尽量绑定当前可取得的产品页，未列出的以 CLI 输出为准

capabilities 的 status 与 verification_scope 表示实现和验证状态；这些状态不代表当前应用已开通或有余量

xfyun demo <能力> 用于准备官方示例资源；没有官方样例的票据、证件等能力会输出命令模板，此时用 --file 指定自备文件。默认只准备资源、打印命令，不会调用收费能力；只有用户确认后才加 --run

查询用量与设置预警：

xfyun console quota --service <BUSINESS_ID> --app <APP_ID> --json
xfyun console capability usage <APP_ID> <BUSINESS_ID> --json
xfyun console capability warning get <APP_ID> <BUSINESS_ID> --json
xfyun console capability warning set <APP_ID> <BUSINESS_ID> --config warning.json --json

businessId 从 console capability list --json 获取。单位以返回的 usageUnit / usageUnitName 为准；单位为空时不要猜测；字段缺失或为 null 时报告“未取得数据”，不要当成 0。warning set 按完整配置提交，先 get 再改，保留其他字段

开通与购买

CLI 不会自动开通、领取免费包、购买或续费。需要服务量时，按需在控制台完成：

1. 先查看能力的产品页、控制台入口和计费单位：xfyun explain <能力> --app <APP_ID> --json
2. 到控制台服务页确认是否已开通，以及是否有免费试用、套餐或购买入口： https://console.xfyun.cn/services
3. 按页面流程完成开通或购买；企业采购和发票按页面或商务流程办理
4. 完成后用 xfyun console quota --service <BUSINESS_ID> --app <APP_ID> --json 复查余量

免费额度、套餐、价格和开票以控制台页面为准；CLI 不承诺具体价格或免费额度，也不自动续费。缺少权限或余量时，命令返回错误和控制台 / 服务页 / 工单指引：

• 能力开通：https://console.xfyun.cn/services
• 实名认证：https://console.xfyun.cn/user/authentication
• 提交工单：https://console.xfyun.cn/workorder/commit

执行任务#

通用参数：--app 指定应用；--json 或 --format json 输出统一 envelope；-o 保存产物；--timeout 设置本地超时。进度和提示写入 stderr，stdout 只放结果或 JSON。完整参数以各命令 --help 为准

@文件 用于把本地文本作为输入（如 xfyun run proofread @document.txt）；OCR、转写、上传等文件类命令直接传路径

-o 在合成、转写、PPT、PDF 等命令中会直接覆盖同名文件；embed 等命令只创建新文件、不覆盖。脚本或 Agent 请使用唯一路径，或先检查目标文件

退出码：0 成功；2 参数错误；3 未登录 / 认证失败；4 权限或未开通；5 限流；6 服务错误；7 超时；8 需要用户处理；9 内部错误。调用凭条是预估用量，真实用量以控制台查询为准

--json 成功与失败的结构：

{
  "ok": true,
  "status": "completed",
  "data": { "voice": "xiaoyan", "size_bytes": 12345 },
  "error": null,
  "meta": {
    "observed_at": "2026-10-21T08:00:00.000Z",
    "provider": "tts",
    "billing": { "is_estimate": true, "unit": "character", "quantity": 12 }
  },
  "trace_id": "tr_..."
}

{
  "ok": false,
  "status": "user_action_required",
  "data": null,
  "error": {
    "code": "SERVICE_PURCHASE_REQUIRED",
    "message": "服务未开通或授权不足",
    "category": "user_action_required",
    "retryable": false
  },
  "action": {
    "type": "open_url",
    "url": "https://console.xfyun.cn/services/tts",
    "message": "请用户到服务页确认开通状态或购买服务量，完成后再继续；不要自动购买或循环重试。"
  },
  "meta": { "observed_at": "2026-10-21T08:00:00.000Z" },
  "trace_id": "tr_..."
}

action 在顶层，不在 error 里；脚本先判断 ok，再读 error.code、error.retryable 和 action

常用命令示例：

# 语音
xfyun run tts "你好，讯飞开放平台" --service tts -o hello.mp3
xfyun run transcribe meeting.mp3 --service ost --wait -o meeting.txt
xfyun run evaluate answer.wav --service ise --ref-text "今天天气很好" --category read_sentence --language cn --json
xfyun run analyze "https://your-host/meeting.mp3" --template preset_2 --wait --json

# 文本与 OCR
xfyun run translate "你好" --from cn --to en --json
xfyun run proofread @document.txt --json
xfyun run ocr page.jpg --json
xfyun run ocr --pdf report.pdf --export-format markdown --wait -o report.md

# 知识与生成
xfyun run kb guide --json
xfyun run kb ask "文档中有哪些使用限制？" --kb-id <REPO_ID> --json
xfyun run ppt "2026 年 AI 行业趋势" --wait -o trend.pptx
xfyun run search "讯飞开放平台" --limit 10 --json

# 任务
xfyun run jobs wait <JOB_ID> -o result.txt

异步能力提交后返回本地 job_id，可用 xfyun run jobs list|get|wait|result 查询。Job 保存原应用、控制台环境和业务身份，不保存密钥；查询沿用原身份，跨应用、跨环境或缺少原始身份时停止远端查询。等待超时不会自动重提，用同一 job_id 继续。二进制产物只返回路径和体积，不打印内容

安全与退出#

xfyun console logout

logout 只删除本机配置，不撤销服务端令牌；需要终止授权时在控制台「CLI 访问令牌」撤销（访问令牌）

常见问题#