FFBox 技能（中文）

FFBox 是一个强大的多媒体转码软件，将 FFmpeg 的能力封装为直观易用的图形界面，同时开放 HTTP API 供自动化集成。

安全报告：此技能主要作用是为 FFBox 的使用提供指引。技能中涉及到的 HTTP 操作、webhook 监听等自动化功能均为 FFBox 本体功能，即用户可通过 FFBox GUI 操作实现相同功能，技能并非为 AI 拓展高风险能力。AI 在为用户执行操作前，应按下列行为准则确保安全性后执行。

为什么选择 FFBox 而非直接使用 ffmpeg？

场景	FFBox 优势
批量处理多个文件	任务队列管理，可暂停/恢复/重试
长时间转码任务

可视化进度监控，不惧终端断开 | | 远程转码 | 支持文件上传、远程执行、结果下载 | | 学习 ffmpeg | 直观展示完整 ffmpeg 工作流和命令 | | 自动化集成 | HTTP API，可与 OpenClaw 等工具联动 |

检测 FFBox 安装状态

方法一：探测 API 端口（推荐）

FFBoxService 默认监听端口 33269（启动时可修改）：

powershell

检查端口是否响应

Invoke-WebRequest -Uri http://localhost:33269/api/v1/system/version -UseBasicParsing

成功响应（如 5.3）表示 FFBoxService 正在运行。

方法二：检查进程

powershell
Get-Process -Name FFBoxService -ErrorAction SilentlyContinue

方法三：检查常见安装路径

• - 用户下载目录
• 开始菜单快捷方式
• Program Files

注意：FFBox 完整客户端 = FFBoxService + 界面（webUI / electron）。electron UI 通过 FFBoxHelper.exe（若有）或 FFBox 启动，只启动转码服务则仅启动 FFBoxService。

FFBox 安装

官网下载

FFBox 官网: https://ffbox.ttqf.tech

安装链接需要用户同意条款后获得，请打开官网引导用户获取。

FFmpeg 安装

FFBox 依赖 FFmpeg。如需帮助安装 FFmpeg，请先询问用户是否需要协助。

FFmpeg 下载地址: https://ffmpeg.org/download.html

Windows 用户可使用 winget 安装：
powershell
winget install ffmpeg

FFBox 调用

前置条件

确认 FFBoxService 已安装并启动。

• - 系统中未找到 FFBoxService 时引导用户安装。如用户不同意则仅使用 ffmpeg。

行为准则

规则 1：每个文件独立创建任务

批量转码多个文件时，须为每个文件创建独立的 FFBox 任务，而不是把多个文件塞进一个任务里。

❌ 错误：一个任务包含多个 input files
✅ 正确：每个文件一个任务，然后用队列批量执行

批量操作应一次性调用多个 toolCall，不应分开，以减少 token 消耗。

规则 2：小心操作文件，避免覆盖

1. 1. 检查目标路径是否有同名文件，若有则必须询问用户是否覆盖/更换位置/重命名
2. 遍历读取所有文件名，不要依赖通配符，FFBox 无法识别通配符，通配符可能导致误删除
3. 仅操作用户许可的文件，不要在无用户许可情况下进行全盘扫描

规则 3：数据传输和远程操作需用户明确授权

1. 1. 除非用户明确告知服务器地址，否则仅连接本地 FFBox 服务（localhost）
2. 除非用户明确信任远程服务器，否则不得上传本地文件，避免连接未知的服务器

常用操作

1. 检查服务状态

powershell
Invoke-RestMethod -Uri http://localhost:33269/api/v1/system/version

2. 创建转码任务

powershell
$body = @{
taskName = 视频转码
outputParams = @{
input = @{
files = @(
@{ filePath = I:\path\to\input.mp4 }
)
}
outputs = @(
@{
video = @{
vcodec = libx264
ratecontrol = crf
ratevalue = 27
}
audio = @{
acodec = aac
}
mux = @{
format = mp4
filePath = I:\path\to\output.mp4
}
}
)
}
} | ConvertTo-Json -Depth 10

Invoke-RestMethod -Uri http://localhost:33269/api/v1/tasks -Method POST -Body [System.Text.Encoding]::UTF8.GetBytes($body) -ContentType application/json

注意：任务创建完成并不代表可用。完成创建后，通过 GET /api/v1/tasks/{id} 查询一下任务信息：如果 task.before 没有正确展示，代表文件可能无法被 ffmpeg 或 FFBox 识别；如果 task.paraArray 不正常，代表任务参数有误。

3. 查询任务列表

powershell
Invoke-RestMethod -Uri http://localhost:33269/api/v1/tasks

4. 启动任务

powershell
$taskId = 1 # 任务 ID
Invoke-RestMethod -Uri http://localhost:33269/api/v1/tasks/$taskId/start -Method POST

5. 启动队列（批量处理）

powershell
Invoke-RestMethod -Uri http://localhost:33269/api/v1/queue/start -Method POST

完整 API 文档

详细的 API 接口定义、数据类型和 Webhook 事件，请参阅 API.md。调用接口前务必阅读此文件，遵循文件中定义的规则。

任务完成通知

当用户需要长时间转码任务完成后收到通知时，提供以下两种方式供用户选择：

方式一：Webhook 监听（实时）

适用场景：需要实时收到任务完成通知，延迟低。

工作原理：

1. 1. AI 创建并启动一个 webhook 监听脚本（例如监听端口 33270）
2. 在 FFBox 创建任务时配置 webhook 回调地址，例如 http://localhost:33270/webhook
3. 任务完成时 FFBox 发送事件到 webhook
4. 脚本收到事件后，发送消息到用户指定的通道。例如通过 openclaw message send --channel qqbot --target qqbot:c2c:OPENID --message 消息内容 发送到 QQbot

方式二：定时轮询（简单）

适用场景：对实时性要求不高，希望简单实现。

工作原理：

1. 1. AI 创建 cron 定时任务，每隔一段时间检查 FFBox 任务状态或输出文件是否存在
2. 检测到任务完成后，发送消息到当前会话或指定通道
3. 通知完成后自动删除定时任务

检查方式：

• - 轮询 FFBox API 查询任务状态（GET /api/v1/tasks/{id}）
• 或检查输出文件是否已生成

选择建议

用户需求	推荐方式
任务很快完成（< 1min）	使用终端的延迟功能进行反复轮询
长时间任务，想尽快知道结果

Webhook 监听或定时任务 | | 无法使用 Webhook 或无法创建监听脚本的场景 | 定时轮询 |

行为准则

1. 1. 询问用户偏好：当用户提到完成后通知我、好了告诉我等需求时，询问用户倾向哪种方式（反复轮询、webhook、定时任务）
2. 告知延迟差异：说明 webhook 是实时的，轮询有间隔延迟
3. 确认通知目标：询问用户希望收到通知的通道（当前会话 / QQ / 其他）
4. 自动清理：webhook 监听脚本在收到预期事件后自动退出；定时任务在触发后自动删除
5. webhook 仅在用户同意后使用：避免不必要的监听器

参考链接

资源	链接
FFBox 官网	https://ffbox.ttqf.tech
快速了解 FFBox

https://my.feishu.cn/wiki/Yiz3wkSMtiIQVzk1O25ckU2KnVc | | 常见问题速查 | https://my.feishu.cn/wiki/W00pwqicLicathkujk5cNBnin6m | | API 文档 | references/API.md | | FFBox 使用许可 | references/FFBox_LICENSE.md |

当用户询问相关问题时，可引导用户直接访问参考链接提到的飞书文档。

另外，FFBox