把你自己的 AI agent 接入 KinoViz（Claude Code、Codex、Cursor）
通过 MCP 用你自己的 AI agent 驱动 KinoViz：安装本地包、输入 6 位配对码、写好 brief，然后看 Claude Code、Codex 或 Cursor 现场搭动画。
接入你自己的 AI agent，就是让你已经在用的 Claude Code、Codex 或 Cursor 来驱动 KinoViz 编辑器。你写一份简短的 brief，agent 在你看得见的 Studio 标签页里一层层把动画搭出来，你再手动收尾，并像普通项目一样导出。第一次配置大约需要十分钟。
这是什么
KinoViz 通过 MCP（Model Context Protocol）把编辑器工具开放给你的 agent。你电脑上的一个小程序把工具调用转发给已打开的 Studio 标签页，由你平时手动使用的同一个编辑器来执行。
- 你的 agent，你的订阅。 语言模型运行在你自己的 Claude Code、Codex 或 Cursor 账号里，KinoViz 不加收任何 AI 费用。
- KinoViz 负责导演和渲染。 brief 告诉 agent 要做什么，编辑器和导出管线负责渲染。
- 隐私友好。 这个功能不会把你的提示词或项目数据发给任何第三方，工具调用只在你的 agent、本地进程和浏览器标签页之间流转。
- Pro 功能。 包含在 Pro、Studio 和 7 天 Pro 试用中。
KinoViz 自带的 AI Assistant 目前处于暂停状态。这个功能是另一回事：AI 是你自己的，不是我们的。
前置条件
- Pro 或 Studio 套餐，或正在试用 Pro。
- 运行 agent 的电脑上装有 Node.js 18 或更高版本。
- 用 Chrome、Edge 或 Firefox 打开 Studio。
- 支持 MCP 的 agent：Claude Code、Codex 或 Cursor。
- agent 工作期间，让 Studio 标签页保持在前台。浏览器会暂停后台标签页的渲染。
第 1 步：把工具装进你的 agent
在 Studio 里点击顶栏的 Connect agent，弹窗里每种 agent 都有对应的安装命令。Claude Code：
claude mcp add kinoviz -- npx -y @kinoviz/agent-linkCodex：在 ~/.codex/config.toml 里添加：
[mcp_servers.kinoviz]
command = "npx"
args = ["-y", "@kinoviz/agent-link"]Cursor：在 ~/.cursor/mcp.json 里添加：
{
"mcpServers": {
"kinoviz": {
"command": "npx",
"args": ["-y", "@kinoviz/agent-link"]
}
}
}弹窗会按你当前所在的站点自动填好参数，如果与上面的示例不一致，以弹窗里的为准。添加之后请重启 agent，让它加载新工具。
第 2 步：连接
- 在 Studio 里点击 Connect agent，复制 6 位配对码，24 小时内有效。
- 对你的 agent 说：
Use the kinoviz tools, pairing code 123456，换成你自己的码。 - 连接成功后，顶栏会出现一个状态指示点。
配对码是你的标签页和本地包之间的共享口令，没有它，本机上的其他进程无法驱动你的编辑器。
第 3 步：写一份 brief
在 Studio 里打开 Agent brief。好结果和泛泛的结果，差别基本就在这份 brief。字段如下：
| 字段 | 填什么 |
|---|---|
| 风格族 | 动态字体、产品发布、社媒竖版、字幕条、UI 演示，或自由发挥 |
| 画幅 | 1:1、16:9、9:16、4:3 或 4:5 |
| 时长 | 2 到 60 秒 |
| 配色 | 1 到 6 个十六进制颜色 |
| 字体 | 最多 3 个，从 KinoViz 字体列表中选 |
| 文案 | 标题、副标题、正文行和字幕，逐字写清楚 |
| 素材 | 上传到项目里的抠图、logo 或照片 |
| 参照说明 | 用大白话描述成品想要的感觉 |
| 检查时刻 | 可选，指定 agent 要出帧检查的时间点 |
为什么参照和真实素材很重要。 agent 知道「好」长什么样、又有真实图片可放，产出才稳定。没有这些，它只能退回到文字和色块，结果通常比较平。
关于自由发挥。 自由发挥会让 agent 全权决定，Studio 会要求你确认已了解结果通常比较平庸。只要能选风格族，就选一个。
然后让 agent 开工。在 Claude Code 里可以直接运行 /mcp__kinoviz__build 提示，也可以直接让它读取 brief 并开始搭建。
第 4 步：让它搭建，你在旁观看
agent 工作时，Studio 会显示 Agent is editing 横幅和实时活动流，告诉你它正在做什么。
- 暂停或断开：随时可在横幅上操作。
- 手动接管：agent 连接期间，你仍可以选中、移动、编辑任何内容。
- 每一步可撤销：agent 的每个操作都是独立的撤销步骤，可以一步步回退。
请保持标签页在前台。如果切到了后台，agent 会等待最多一分钟让你回来，超时才会报错。
第 5 步：验收与导出
agent 认为完成后会运行验收检查：按 brief 的检查时刻出帧，统计未命名图层，并汇报它发现的主要版面问题。你在 Studio 里查看结果，可以让它再改一轮，也可以自己调整细节。
导出走正常的导出对话框，分辨率、帧率和格式由你的套餐决定，不会因为是 agent 搭的而有任何不同。
擅长与限制
| 适合 | 暂时不适合 |
|---|---|
| 2D 动态字体排版 | 电影感 3D 场景 |
| 产品发布与功能展示 | 物理模拟 |
| 社媒竖版短片 | |
| 字幕条与下三分之一条 | |
| UI 与 App 演示 |
agent 拿到的是一套为稳定性精选的精简工具集，而不是编辑器的全部工具。它擅长版式、节奏、遮罩和预设，对最重的 3D 和特效功能覆盖较少，这部分你可以事后手动补上。
常见问题排查
「Not connected」。 agent 找不到 Studio 标签页。请在 /studio 里打开一个项目，确认标签页已登录，并运行 kinoviz_status 检查。
「Not paired」。 agent 还没拿到配对码，或者码已过期。点击 Connect agent 获取新码，并让 agent 用新码配对。
标签页在后台。 请把 Studio 标签页切到前台。agent 会把任务排队最多一分钟，超时仍未回到前台才会报错。
plan_required。 你的账号所在套餐不含此功能。请升级到 Pro，或在定价页开启 7 天试用。
常见问答
AI 模型的费用由 KinoViz 承担吗？
不是。模型运行在你自己的 Claude Code、Codex 或 Cursor 订阅里，费用在那边结算。KinoViz 自带的 AI Assistant 是另一个功能，目前处于暂停状态。
我的项目或提示词会被发给第三方吗？
这个功能不会把你的提示词或项目数据发给任何第三方。本地包只是在你自己的电脑上，把你的 agent 和你的浏览器标签页连起来。你的 agent 仍会按其服务商的条款与自己的模型服务通信。
支持哪些 agent？
任何能运行本地 MCP 服务的 agent。文档提供 Claude Code、Codex 和 Cursor 的配置。
需要哪个套餐？
Pro 或 Studio，7 天 Pro 试用也包含。