openstoryline-use

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenStoryline Usage Skill

你负责在“已安装完成”的前提下，执行 OpenStoryline 的实际剪辑流程。 OpenStoryline 是一个剪辑 Agent，用户可使用自己的素材，通过自然语言对话的方式剪辑视频。内置素材搜索、内容理解、生成字幕、文字转语音等功能，用户可以多次提出具体的剪辑/修改意见。

目标是：使用已有脚本，稳定地完成一次从启动服务到产出视频的闭环；并且支持在同一个

session_id

上继续对话、二次编辑、重新生成新视频。

You are responsible for executing the actual video editing process of OpenStoryline on the premise that it has been completely installed. OpenStoryline is an editing Agent that allows users to edit videos via natural language conversations using their own materials. It has built-in features such as material search, content understanding, subtitle generation, text-to-speech, etc., and users can put forward specific editing/modification suggestions multiple times.

The goal is to use existing scripts to stably complete a closed-loop process from starting services to producing videos; and to support continuing conversations, secondary editing, and regenerating new videos with the same

session_id

Scope

此技能只处理“使用与剪辑”：

检查并修改
```
config.toml
```
的必要字段。
启动 MCP server。
启动
```
uvicorn agent_fastapi:app
```
。
创建 session 并发送剪辑请求。
等待并验证输出视频产物。
在同一个
```
session_id
```
上继续对话，执行二次编辑。
验证二次编辑后是否生成了新的
```
output_*.mp4
```
。

不处理完整安装流程（依赖安装、模型下载、资源下载等），那是安装技能的范围。如果在启动时遇到问题，怀疑是安装问题，再去查看安装Skill openstoryline-install

This skill only handles "usage and editing":

Check and modify the necessary fields in
```
config.toml
```
.
Start the MCP server.
Start
```
uvicorn agent_fastapi:app
```
.
Create a session and send editing requests.
Wait for and verify the output video products.
Continue conversations on the same
```
session_id
```
to perform secondary editing.
Verify whether a new
```
output_*.mp4
```
is generated after secondary editing.

It does not handle the complete installation process (dependency installation, model download, resource download, etc.), which falls under the scope of the installation skill. If problems are encountered during startup and you suspect they are installation issues, refer to the installation skill openstoryline-install

Core Rules

默认只监听
```
127.0.0.1
```
，不要主动暴露到局域网。
优先复用现有脚本，不要重复造轮子：
- 修改配置脚本：位于代码仓库
```
scripts/update_config.py
```
- Web 服务桥接脚本位于当前 skill 目录下的
```
scripts/bridge_openstoryline.py
```
  。请先定位当前 skill 目录，再拼接
```
scripts/bridge_openstoryline.py
```
长驻服务（MCP / Web）必须按“长驻进程”方式启动，并持续观察日志；不要把启动命令当成一次性探测命令。
不要在启动命令后面追加这些包装：
- ```
| head
```
- ```
| tail
```
- ```
grep
```
- ```
timeout
```
- ```
sleep
```
- ```
pkill
```
- 以及其它会截断日志、提前退出、强行杀进程的包装
询问用户需要剪辑哪些素材及其路径。
第一轮创建 session 后返回的
```
session_id
```
必须保存；后续继续对话、二次编辑都依赖它。
如果服务端提示“上一条消息尚未完成，请稍后再发送”，不要新建 session；优先等待，必要时只终止卡住的本地 bridge 进程，然后继续复用原
```
session_id
```
重试。
不要在任务执行中途主动终止 MCP / Web 服务，除非用户明确要求停止，或者服务本身已经确认失活。
每次完成任务后，都要向用户明确返回：
- ```
session_id
```
- 最终视频
```
.mp4
```
  的完整路径
- 如有二次编辑，还要说明是否生成了新的输出文件
下面的示例命令都使用
```
source .venv/bin/activate
```
作为示例，你需要根据用户实际使用的环境，替换成正确的命令（例如
```
conda activate 
```
）。
遇到端口被占用的情况，优先换一个端口。

By default, only listen on
```
127.0.0.1
```
; do not actively expose to the local area network.
Prioritize reusing existing scripts instead of reinventing the wheel:
- Configuration modification script: located at
```
scripts/update_config.py
```
  in the code repository
- Web service bridging script is located at
```
scripts/bridge_openstoryline.py
```
  in the current skill directory. Please locate the current skill directory first, then concatenate with
```
scripts/bridge_openstoryline.py
```
Long-running services (MCP / Web) must be started as "long-running processes" and their logs must be monitored continuously; do not treat startup commands as one-time detection commands.
Do not append the following wrappers to startup commands:
- ```
| head
```
- ```
| tail
```
- ```
grep
```
- ```
timeout
```
- ```
sleep
```
- ```
pkill
```
- And other wrappers that truncate logs, exit early, or force kill processes
Ask the user which materials they need to edit and their paths.
The
```
session_id
```
returned after creating a session in the first round must be saved; subsequent conversations and secondary editing depend on it.
If the server prompts "The previous message has not been completed, please try again later", do not create a new session; prioritize waiting, and if necessary, only terminate the stuck local bridge process, then continue to retry with the original
```
session_id
```
.
Do not actively terminate MCP / Web services during task execution unless the user explicitly requests to stop them or the services are confirmed to be inactive.
After completing each task, clearly return the following to the user:
- ```
session_id
```
- The full path of the final video
```
.mp4
```
- If secondary editing is performed, also indicate whether a new output file has been generated
The example commands below use
```
source .venv/bin/activate
```
as an example; you need to replace it with the correct command according to the user's actual environment (e.g.,
```
conda activate 
```
).
If a port is occupied, prioritize switching to another port.

OpenClaw Execution Strategy (Important)

如果你是OpenClaw，一定注意以下关键点：

If you are OpenClaw, pay attention to the following key points:

长驻服务怎么跑

How to run long-running services

对于以下两类命令：

PYTHONPATH=src python -m open_storyline.mcp.server

uvicorn agent_fastapi:app --host 127.0.0.1 --port 8005

必须按“长驻进程”处理：

用
```
exec
```
启动，并开启 PTY（如果工具支持
```
pty: true
```
，就开启）。
启动后不要立刻判失败，MCP Server启动需要几分钟的时间。
用
```
process poll
```
/
```
process log
```
持续观察返回的内容，一定不要急着杀掉进程。
看到成功日志再继续下一步。

For the following two types of commands:

PYTHONPATH=src python -m open_storyline.mcp.server

uvicorn agent_fastapi:app --host 127.0.0.1 --port 8005

They must be handled as "long-running processes":

Start with
```
exec
```
and enable PTY (if the tool supports
```
pty: true
```
, enable it).
Do not immediately judge failure after startup; MCP Server startup may take several minutes.
Continuously observe the returned content using
```
process poll
```
/
```
process log
```
; do not rush to kill the process.
Proceed to the next step only after seeing the success log.

一次性命令怎么跑

How to run one-time commands

以下命令适合普通一次性

exec

：

修改
```
config.toml
```
创建 session
在现有
```
session_id
```
上继续对话
查找
```
.mp4
```
查看文件大小

The following commands are suitable for ordinary one-time

exec

Modify
```
config.toml
```
Create a session
Continue conversations on an existing
```
session_id
```
Search for
```
.mp4
```
Check file size

观察哪个日志最有用

Which log is most useful

实测中，Web 服务日志 最适合看剪辑进度。
常见正常流程节点包括：

```
filter_clips
```
```
group_clips
```
```
generate_script
```
```
generate_voiceover
```
```
render_video
```

如果 bridge 脚本还在等待，不代表系统没在工作；可能只是服务端还在处理。

In practice, Web service logs are the most suitable for viewing editing progress.
Common normal process nodes include:

```
filter_clips
```
```
group_clips
```
```
generate_script
```
```
generate_voiceover
```
```
render_video
```

If the bridge script is still waiting, it does not mean the system is not working; it may just be that the server is still processing.

Standard Workflow (OpenClaw)

0) 确认仓库根目录

0) Confirm repository root directory

后续命令中的

<repo-root>

指向 OpenStoryline 仓库根目录，例如：

bash

/Users/yourname/Desktop/code/Openstoryline/FireRed-Openstoryline

所有命令都默认在这个目录下执行，并先激活环境。

<repo-root>

in subsequent commands refers to the root directory of the OpenStoryline repository, for example:

bash

/Users/yourname/Desktop/code/Openstoryline/FireRed-Openstoryline

All commands are executed in this directory by default, and the environment is activated first.

1) 进入项目根目录并配置

1) Enter project root directory and configure

必填配置

Required configuration

在开始剪辑前，以下 6 个字段必须有值，否则模型调用会失败。你必须先向用户询问这些字段的具体值，然后用脚本进行修改：

```
[llm].model
```
```
[llm].base_url
```
```
[llm].api_key
```
```
[vlm].model
```
```
[vlm].base_url
```
```
[vlm].api_key
```

直接可用命令（在仓库根目录执行，以.venv为例）：

bash

cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set llm.model=REPLACE_WITH_REAL_MODEL
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set llm.base_url=REPLACE_WITH_REAL_URL
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set llm.api_key=sk-REPLACE_WITH_REAL_KEY

cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set vlm.model=REPLACE_WITH_REAL_MODEL
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set vlm.base_url=REPLACE_WITH_REAL_URL
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set vlm.api_key=sk-REPLACE_WITH_REAL_KEY

Before starting editing, the following 6 fields must have values, otherwise model calls will fail. You must first ask the user for the specific values of these fields, then modify them using the script:

```
[llm].model
```
```
[llm].base_url
```
```
[llm].api_key
```
```
[vlm].model
```
```
[vlm].base_url
```
```
[vlm].api_key
```

Directly usable commands (execute in the repository root directory, taking .venv as an example):

bash

cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set llm.model=REPLACE_WITH_REAL_MODEL
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set llm.base_url=REPLACE_WITH_REAL_URL
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set llm.api_key=sk-REPLACE_WITH_REAL_KEY

cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set vlm.model=REPLACE_WITH_REAL_MODEL
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set vlm.base_url=REPLACE_WITH_REAL_URL
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set vlm.api_key=sk-REPLACE_WITH_REAL_KEY

选填配置

Optional configuration

以下是常见可选项，按需设置：

The following are common optional settings, which can be configured as needed:

1. MCP 端口（端口冲突时）

1. MCP port (in case of port conflict)

bash

cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set local_mcp_server.port=8002

bash

cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set local_mcp_server.port=8002

2. 素材检索（Pexels）

2. Material retrieval (Pexels)

bash

cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set search_media.pexels_api_key=REPLACE_WITH_PEXELS_KEY

bash

cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set search_media.pexels_api_key=REPLACE_WITH_PEXELS_KEY

3. TTS（如果需要配音）

3. TTS (if voiceover is needed)

在以下 3 家中选一家填写即可：

bash

undefined

You only need to fill in one of the following three providers:

bash

undefined

minimax

cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.minimax.base_url=https://api.minimax.chat/v1/t2a_v2 cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.minimax.api_key=REPLACE_WITH_MINIMAX_KEY

bytedance

cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.bytedance.uid=REPLACE_UID cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.bytedance.appid=REPLACE_APPID cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.bytedance.access_token=REPLACE_ACCESS_TOKEN

302

cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.302.base_url=https://REPLACE_BASE_URL cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.302.api_key=REPLACE_API_KEY

---

---

2) 启动 MCP Server

2) Start MCP Server

注意 MCP Server 的启动可能需要几分钟，务必耐心等待，不要急着 kill 掉进程。 macOS/Linux:

bash

cd <repo-root> && source .venv/bin/activate && PYTHONPATH=src python -m open_storyline.mcp.server

Windows:

powershell

cd <repo-root>
. .venv\Scripts\Activate.ps1
$env:PYTHONPATH="src"
python -m open_storyline.mcp.server

看到类似以下日志，视为成功：

text

Uvicorn running on http://127.0.0.1:8001

Note that starting the MCP Server may take several minutes; please be patient and do not rush to kill the process. macOS/Linux:

bash

cd <repo-root> && source .venv/bin/activate && PYTHONPATH=src python -m open_storyline.mcp.server

Windows:

powershell

cd <repo-root>
. .venv\Scripts\Activate.ps1
$env:PYTHONPATH="src"
python -m open_storyline.mcp.server

Startup is considered successful when you see logs similar to the following:

text

Uvicorn running on http://127.0.0.1:8001

3) 启动 Web 服务（uvicorn）

3) Start Web service (uvicorn)

macOS/Linux:

bash

cd <repo-root> && source .venv/bin/activate && uvicorn agent_fastapi:app --host 127.0.0.1 --port 8005

出现以下日志即成功：

text

INFO:     Started server process [PID]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8005 (Press CTRL+C to quit)

macOS/Linux:

bash

cd <repo-root> && source .venv/bin/activate && uvicorn agent_fastapi:app --host 127.0.0.1 --port 8005

Startup is successful when the following logs appear:

text

INFO:     Started server process [PID]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8005 (Press CTRL+C to quit)

4) 创建剪辑会话

4) Create editing session

注意把地址替换为上一步启动 Web 服务时的真实地址。

bash

curl -s -X POST "http://127.0.0.1:8005/api/sessions"

这一步会创建一个剪辑会话，拿到一个

session_id

，非常重要！只要 Web 服务还活着，你就可以拿着这个

session_id

进行上传素材、多轮对话，务必保留。

Note to replace the address with the actual address of the Web service started in the previous step.

bash

curl -s -X POST "http://127.0.0.1:8005/api/sessions"

This step will create an editing session and get a

session_id

, which is very important! As long as the Web service is running, you can use this

session_id

to upload materials and conduct multi-round conversations, so be sure to keep it.

5) 上传素材

5) Upload materials

方案1：

Option 1:

bash

curl -s -X POST "http://127.0.0.1:8005/api/sessions/{session_id}/media" -F "files=@/absolute/path/input.mp4"

bash

curl -s -X POST "http://127.0.0.1:8005/api/sessions/{session_id}/media" -F "files=@/absolute/path/input.mp4"

方案2：对于大文件，建议直接走本地copy

Option 2: For large files, it is recommended to directly copy locally

bash

cp path/to/source.mp4 <repo-root>/outputs/{session_id}/media

bash

cp path/to/source.mp4 <repo-root>/outputs/{session_id}/media

6) 开始剪辑对话（自动创建 session）

6) Start editing conversation (session is created automatically)

使用 Skill 自带 bridge 脚本.

skills-root: 当前 skill 所在目录。
session-id: 填写上一步拿到的
```
session_id
```
base-url 填写 Web 服务的 url
prompt 用户的剪辑需求
lang 用户使用的语言类型，目前仅支持 zh / en，设置一次即可。

bash

cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/bridge_openstoryline.py \
  --session-id <session_id> \
  --base-url http://127.0.0.1:8005 \
  --prompt "剪一个小红书风格视频" \
  --lang "zh"

Use the bridge script built into the Skill.

skills-root: The directory where the current skill is located.
session-id: Fill in the
```
session_id
```
obtained in the previous step
base-url: Fill in the URL of the Web service
prompt: The user's editing requirements
lang: The language used by the user, currently only supports zh / en, set it once.

bash

cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/bridge_openstoryline.py \
  --session-id <session_id> \
  --base-url http://127.0.0.1:8005 \
  --prompt "剪一个小红书风格视频" \
  --lang "zh"

7) 等待并观察剪辑进度

7) Wait and observe editing progress

有时剪辑Agent会先询问剪辑需求；有时会直接开始剪辑，剪辑可能需要几分钟，尤其是带文案、配音、渲染时。

Sometimes the editing Agent will first ask for editing requirements; sometimes it will start editing directly. Editing may take several minutes, especially when it involves copywriting, voiceover, and rendering.

正确做法

Correct approach

持续
```
poll
```
当前 bridge 脚本对应的进程会话。
同时查看 Web 服务日志。剪辑 Agent 会实时更新自己的进度。
只要 Web 服务日志仍在推进，就继续等待，不要随便重启服务。

Continuously
```
poll
```
the process session corresponding to the current bridge script.
At the same time, check the Web service logs. The editing Agent will update its progress in real-time.
As long as the Web service logs are still progressing, continue waiting and do not restart the service casually.

实战经验

Practical experience

如果 bridge 命令还没返回，但 Web 服务日志里已经在跑节点，这通常说明服务端仍在正常工作，不要误判为失败。

If the bridge command has not returned yet, but nodes are already running in the Web service logs, this usually indicates that the server is still working normally, so do not misjudge it as a failure.

8) 第二轮：在同一个 session 上继续聊天

8) Second round: Continue chatting in the same session

根据助手回复，继续向它发出剪辑要求。例如，助手制定了一个剪辑计划，请求确认。那么：

bash

cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/bridge_openstoryline.py \
  --base-url http://127.0.0.1:8005 \
  --session-id <上一步session_id> \
  --prompt "开始剪辑"

或者需要调整：

bash

cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/bridge_openstoryline.py \
  --base-url http://127.0.0.1:8005 \
  --session-id <上一步session_id> \
  --prompt "使用欢快的BGM"

According to the assistant's reply, continue to send editing requests to it. For example, if the assistant has made an editing plan and requests confirmation, then:

bash

cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/bridge_openstoryline.py \
  --base-url http://127.0.0.1:8005 \
  --session-id <previous session_id> \
  --prompt "开始剪辑"

Or if adjustments are needed:

bash

cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/bridge_openstoryline.py \
  --base-url http://127.0.0.1:8005 \
  --session-id <previous session_id> \
  --prompt "使用欢快的BGM"

9) 检查首轮产物

9) Check the first-round output product

一般来说，剪辑agent的输出会直接写出剪辑产物的路径。如果没有，优先检查：

bash

cd <repo-root> && find .storyline/.server_cache/<session_id> -name "output_*.mp4" 2>/dev/null

Generally, the output of the editing agent will directly write out the path of the editing product. If not, first check:

bash

cd <repo-root> && find .storyline/.server_cache/<session_id> -name "output_*.mp4" 2>/dev/null

判定标准

Judgment standard

有

output_*.mp4

即认为剪辑成功。

Editing is considered successful if there is an

output_*.mp4

file.

10) 发送视频

10) Send the video

将生成的视频发送给用户观看，询问用户反馈。

Send the generated video to the user for viewing and ask for their feedback.

OpenClaw + 飞书 APP 场景视频发送指南

Guide for sending videos in OpenClaw + Feishu APP scenario

如果你是 OpenClaw 且用户使用手机飞书 APP，使用如下专属指南。要求：

Python 3.6+
已安装
```
requests
```
bash
```
python3 -m pip install requests
```
OpenClaw 已配置飞书渠道

运行脚本示例如下，此脚本会自动从 ~/.openclaw/openclaw.json 读取飞书凭证。 receive-id 的选择

oc_xxx -> chat_id：发到群聊或当前单聊会话，优先推荐
ou_xxx -> open_id：发给指定用户
on_xxx -> user_id：仅当明确拿到的是 user_id 时再使用

bash

cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/feishu_file_sender.py --help
cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/feishu_file_sender.py --file /absolute/path/to/video.mp4 --receive-id-type chat_id --receive-id oc_xxx

If you are OpenClaw and the user is using the Feishu mobile APP, follow the exclusive guide below. Requirements:

Python 3.6+
```
requests
```
has been installed
bash
```
python3 -m pip install requests
```
OpenClaw has configured the Feishu channel

Example of running the script: This script will automatically read Feishu credentials from ~/.openclaw/openclaw.json. Selection of receive-id:

oc_xxx -> chat_id: Send to group chat or current one-on-one session, highly recommended
ou_xxx -> open_id: Send to a specified user
on_xxx -> user_id: Only use it when you clearly get a user_id

bash

cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/feishu_file_sender.py --help
cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/feishu_file_sender.py --file /absolute/path/to/video.mp4 --receive-id-type chat_id --receive-id oc_xxx

11) 二次编辑

11) Secondary editing

在已经生成视频的情况下，如果用户对视频内容不满意，可以复用同一个
session_id
继续修改视频，并生成新的

output_*.mp4

。

If the user is not satisfied with the video content after it has been generated, you can reuse the same
session_id
to continue modifying the video and generate a new

output_*.mp4

示例：修改文案风格

Example: Modify copywriting style

bash

cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/bridge_openstoryline.py \
  --base-url http://127.0.0.1:8005 \
  --session-id <session_id> \
  --prompt "帮我把文案换成更欢乐、更有活力的风格"

同一个
```
session_id
```
下，系统会重新跑相应节点,然后重新渲染.
同一个
```
session_id
```
下会出现新的
```
render_video_*
```
目录。
新目录里会生成新的
```
output_*.mp4
```
。

bash

cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/bridge_openstoryline.py \
  --base-url http://127.0.0.1:8005 \
  --session-id <session_id> \
  --prompt "帮我把文案换成更欢乐、更有活力的风格"

Under the same
```
session_id
```
, the system will re-run the corresponding nodes and then re-render.
A new
```
render_video_*
```
directory will appear under the same
```
session_id
```
.
A new
```
output_*.mp4
```
will be generated in the new directory.

Security Note

只有当用户明确要求手机 / LAN 访问时，才改为

--host 0.0.0.0

。
同时提醒：仅在可信网络使用，避免开放到公共网络。

Only change to

--host 0.0.0.0

when the user explicitly requests access via mobile phone / LAN. Also remind: Only use it in a trusted network, avoid exposing it to the public network.