From bd9eda19c1e12ee85f3be83c85957d5b5e2742e0 Mon Sep 17 00:00:00 2001 From: openclaw Date: Mon, 19 Oct 2026 01:39:23 +0000 Subject: [PATCH] docs: add openai-video provider documentation and configuration guide --- README.md | 143 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 113 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index df30c5e..187aaa2 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,124 @@ -# OpenClaw Tools (`openclaw-plugin-tools`) +# OpenClaw Tools & Media Providers (`openclaw-plugin-tools`) -Collection of custom tools and bundled skills for OpenClaw. +OpenClaw 统一私有扩展插件集合,聚合了自定义 Agent 工具、媒体生成驱动(视频/图像)以及内置技能库。 -## Step-by-Step Construction History +--- -1. **Step 1 — Initialize Scaffold (`chore: openclaw plugins init tools`)** - Generated the standard plugin skeleton via `openclaw plugins init tools`. -2. **Step 2 — Compile & Build Metadata (`build: compile TypeScript to dist and add .gitignore`)** - Compiled `src/index.ts` into `dist/index.js` and ran `openclaw plugins build --entry ./dist/index.js` so downstream installs do not require a local build step. -3. **Step 3 — Enable Multi-Skill Bundling (`feat: enable bundled skills directory in openclaw.plugin.json`)** - Added `"skills": ["./skills"]` to `openclaw.plugin.json` and `"skills"` to `package.json#files` so OpenClaw discovers all skills placed under `skills//SKILL.md`. -4. **Step 4 — Bundle First Skill (`feat(skills): bundle bitwarden agent-access skill`)** - Added `skills/agent-access/SKILL.md` for Bitwarden Agent Access (`aac`). -5. **Step 5 — Documentation (`docs: document step-by-step plugin construction and usage`)** - Documented project layout and installation workflow. +## 包含模块一览 -## Project Structure +| 模块类别 | 标识符 (ID) | 类型 | 说明 | +| :--- | :--- | :--- | :--- | +| **视频生成** | `openai-video` | `videoGenerationProviders` | OpenAI `/v1/videos` 兼容格式视频生成驱动(支持自建网关 / gemini-web2api / Sora 协议) | +| **基础工具** | `echo` | `tools` | 基础测试与回显工具 | +| **内置技能** | `agent-access` | `skills` | Bitwarden Agent Access 自动化技能 | -```text -openclaw-plugin-tools/ -├── openclaw.plugin.json # Plugin manifest (declares tools & skills dir) -├── package.json # Package metadata & entrypoints -├── src/ -│ ├── index.ts # Tool plugin TypeScript source -│ └── index.test.ts # Unit tests -├── dist/ # Pre-compiled JS artifacts -└── skills/ # Bundled skills directory - └── agent-access/ - └── SKILL.md # Bitwarden Agent Access skill +--- + +## 模块说明 + +### 1. 视频生成驱动 (`openai-video`) + +适配标准 **OpenAI Videos API**(`/v1/videos` 规范),专门针对自建中转(如 `gemini-web2api-go`、`ccLoad`、第三方 OpenAI 兼容视频服务)做了深度兼容修复: +* `POST /v1/videos` 创建生成任务(纯文本任务自动发 JSON Body,避免第三方服务不支持 Multipart 的 400 报错;带垫图/垫视频时使用 Multipart 表单) +* `GET /v1/videos/{id}` 轮询任务完成状态(兼容普通对象错误与字符串错误消息) +* `GET /v1/videos/{id}/content` 下载二进制视频流 +* 原生支持内网/私有端点(`allowPrivateNetwork: true`,支持 `host.incus.internal` 或局域网 IP) + +#### 配置说明 + +支持通过 **Web 控制台(Control UI)** 或直接编辑 `~/.openclaw/openclaw.json`。 + +##### 方式 1:Web 控制台可视化配置 +进入 **Settings → Plugins → Tools**: +* **API Base URL**:填写视频上游端点(例如 `http://host.incus.internal:8083/v1` 或内部网关地址) +* **API Key**:填写 API Key 或 SecretRef(留空时自动回退读取环境变量 `OPENAI_VIDEO_API_KEY`、`CCLOAD_API_KEY` 或 `BIFROST_API_KEY`) +* **默认视频模型**:例如 `gemini-video` 或 `sora-2` + +##### 方式 2:编辑 `openclaw.json` + +在 `~/.openclaw/openclaw.json` 中配置: + +```json5 +{ + "plugins": { + "entries": { + "tools": { + "enabled": true, + "config": { + "video": { + "baseUrl": "http://host.incus.internal:8083/v1", + "apiKey": "sk-your-video-key", + "defaultModel": "gemini-video", + "allowPrivateNetwork": true + } + } + } + } + }, + "agents": { + "defaults": { + "mediaModels": { + "video": { + "primary": "openai-video/gemini-video" + } + } + } + } +} ``` -## Installation & Update +> **向下兼容提示**:插件仍完全兼容旧版独立插件 `plugins.entries["openai-video"].config` 的配置路径,迁移期间无需强行改动旧配置即可直接读取。 + +#### 使用方法 + +配置后,OpenClaw 内置的 `video_generate` 工具即可自动调度: +* **自然语言直接对话生成**: + > “帮我生成一个 5 秒的猫咪在海滩上奔跑的 16:9 视频” +* **垫图/图生视频**: + 在对话中上传或提供图片链接,提示助手基于该图生成视频。 + +--- + +### 2. 基础工具 (`tools`) + +* **`echo`**:回显文本输入,用于验证 Agent 工具链连通性与执行状态。 + +--- + +### 3. 内置技能 (`skills`) + +* **`agent-access`**:位于 `skills/agent-access/SKILL.md`,安装插件后自动软链接至 OpenClaw 技能目录,提供 Bitwarden 凭据的无感注入与访问流程。 + +--- + +## 安装与更新 + +### 安装插件 +在 Gateway 主机上执行: ```bash -# Install from Gitea openclaw plugins install git:git.1-h.cc/OpenClaw/openclaw-plugin-tools --force - -# Validate plugin -npm run plugin:validate ``` + +### 插件更新 +当 Gitea 仓库有新提交时,在终端执行: + +```bash +openclaw plugins update tools +``` + +### 验证与测试 + +```bash +# 运行单元测试 +pnpm test + +# 编译 TypeScript 产物 +pnpm run build +``` + +--- + +## License + +[MIT](LICENSE)