OpenCreator（曾用名 KrillinAI）是一个面向创作者的开源 AI 工作空间

OpenCreator（曾用名 KrillinAI）是一个面向创作者的开源 AI 工作空间。它集成了视频翻译、视频下载、缩略图生成、图像生成等多种创作工具，并借助 Codex Agent 引擎，将对话式 AI 与可视化工作流无缝结合。本教程将指导你完成从环境准备到启动运行的全部过程。

一、核心架构与工作流

在开始部署前，理解 OpenCreator 的设计理念有助于你更好地使用它。其核心理念是将 Agent 对话与可视化工作区作为同一创作任务的两个界面，而非两个独立工作流。

层级	组件	职责
前端界面	`apps/web` (React)	提供仪表盘、创作工具、对话界面、设置等用户交互界面。
协作核心	共享工作流状态	同步工作区步骤、对话上下文、进度、结果和版本历史。
本地运行时	`apps/daemon` (Fastify)	管理项目、任务运行、审批、计划任务、记忆和通知，是前端与 Codex 引擎之间的桥梁。
执行引擎	Codex CLI	提供 Agent 循环、模型调用、推理、工具、Skills 和 MCP 支持，是任务执行的最终来源。
媒体工具链	yt-dlp, FFmpeg, Whisper	处理视频下载、媒体转换、转录等具体媒体操作。

工作流程：你在 Web 或 Desktop 界面发起的任务，会通过本地 Runtime (Daemon) 转发给 Codex CLI 执行。Runtime 负责管理项目持久化、审批流程和事件通知，而 Codex 专注于 Agent 逻辑。工作区的可视化操作与对话中的自然语言指令，最终都会转化为同一状态机的事件，从而保持同步。

二、部署步骤

步骤 1：环境准备

确保你的系统满足以下先决条件：

Node.js: 22 或更高版本。
pnpm: 9.15.0 版本（仓库的 packageManager 字段已固定此版本）。可以使用 corepack enable 启用 Corepack 来管理 pnpm 版本。
Codex CLI: 确保 codex 命令可在终端中运行，并且已通过 codex login 完成登录以使用真实模型任务。
Git (如从源码安装)。

验证环境：

1
2
3

node --version
pnpm --version
codex --version

步骤 2：获取 OpenCreator

方式一：使用桌面应用（最简单）

对于 macOS 和 Windows 用户，可以直接下载预编译的桌面应用，无需手动安装依赖和构建：

macOS (Apple Silicon): 下载 OpenCreator-<version>-mac-arm64.dmg
macOS (Intel): 下载 OpenCreator-<version>-mac-x64.dmg
Windows (x64): 下载 OpenCreator-<version>-win-x64.exe

注意：macOS 安装包已签名并公证。Windows 安装包暂未进行 Authenticode 签名，安装前可核对 SHA-256 以验证文件完整性。

方式二：从源码运行 Web 版

如果你希望从源码运行 Web 版本进行开发或自定义：

# 1. 克隆仓库
git clone https://github.com/krillinai/OpenCreator.git
cd OpenCreator

# 2. 启用 Corepack 并安装依赖
corepack enable
pnpm install

# 3. 启动 Web 开发服务器（会自动按需启动本地 Runtime）
pnpm web:dev

启动成功后，在浏览器中打开 http://127.0.0.1:19861/ 即可访问。

步骤 3：初始配置与使用

首次启动：无论是桌面应用还是 Web 版，首次启动时，本地 Runtime 会自动准备一个默认项目。Web 版还会通过同源代理自动注入临时令牌，无需手动复制连接令牌。
配置 AI 服务：进入 设置 → AI 服务，配置你需要的模型、转录、语音和图像生成服务。需要填入对应的 API 密钥、Base URL 等信息。例如，使用 OpenAI 的服务，就需要填入 OpenAI 的 API Key 。
开始创作：你可以通过两种方式开始一个任务：
- 对话方式：在 Composer 对话界面，用自然语言描述你的需求。
- 工具方式：在仪表盘（Dashboard）中，直接选择 视频翻译、视频下载、缩略图生成 或 图像生成 等可视化工具进行操作。

三、核心配置与管理

3.1 AI 服务配置

OpenCreator 支持多种模型提供商，根据你的选择在设置中填入相应凭证：

服务类型	支持的选项
语言模型	GPT, DeepSeek, Qwen, Kimi, GLM, Grok 等
图像生成	GPT Image
语音与转录	Whisper, OpenAI TTS, MiniMax, Edge TTS (无需API Key), 阿里云语音

3.2 第三方组件管理

OpenCreator 集成了 yt-dlp 等工具。你可以在 设置 → 第三方组件 中查看当前使用的版本、内置版本和最新版本。OpenCreator 会每隔七天检查更新，但永远不会自动安装，需要你手动确认更新，且会保留当前可用的工作版本作为回退。

3.3 关键环境变量

大多数用户无需设置环境变量，但在需要隔离数据或指定特定 Codex 路径时，可以使用以下变量（可在启动命令前设置）：

环境变量	默认值	用途
`OPENCREATOR_DATA_DIR`	`.runtime`	指定数据库、任务运行记录和附件存储位置。
`OPENCREATOR_CODEX_BIN`	`codex`	指定 Codex CLI 可执行文件的自定义路径。
`CODEX_HOME`	`~/.codex`	Codex 的配置、会话和 Skills 存储目录。

四、常见问题与技巧

Web 版无法连接到 Runtime？
- 确认 pnpm web:dev 已成功启动，且终端窗口未关闭。
- 检查是否打开了 http://127.0.0.1:19861/，而非其他地址。
任务执行失败或找不到模型？
- 检查 设置 → AI 服务 中的 API 密钥和 Base URL 是否正确。
- 确认 Codex CLI 已登录（codex login）且有权限使用你配置的模型。
如何确保版本一致性（桌面端）？
- 桌面应用打包时会记录 Web 构建的哈希值。如果自行打包，pnpm desktop:package 命令会校验 apps/web/dist 与嵌入资源是否一致，不一致则打包失败。
数据存储在哪里？
- 默认在仓库根目录的 .runtime/ 文件夹下，包含 SQLite 数据库、任务日志和附件。如需备份，可备份此目录及 $CODEX_HOME 目录。

五、部署清单与总结

部署方式	步骤	适用场景
桌面应用 (推荐)	下载对应平台的 `.dmg` 或 `.exe` 文件 → 安装并运行 → 配置 AI 服务	最快捷，适合内容创作者和最终用户。
源码运行 (Web)	安装 Node.js/pnpm → 克隆仓库 → `pnpm install` → `pnpm web:dev`	适合开发者、需要自定义功能或进行二次开发。