Open Design 使用教程：安装、接入 Codex、生成首个可编辑原型

Open Design 是一个本地优先的 AI 设计工作台。它不会只返回一张无法修改的效果图，而是让 Codex、Claude Code、Cursor 等 Agent 在项目目录中生成 HTML、CSS、组件、演示文稿等真实文件，再由 Open Design 负责预览、管理设计系统和导出。

这篇文章不再重复项目 README 的功能列表，而是完成一条可以验收的流程：安装 Open Design、确认 Agent 被识别、生成一个落地页、检查生成文件，并在失败时找到日志和恢复方法。

先选择安装路线

只想体验时优先用 GitHub Releases 中的最新版桌面安装包。不要照着旧教程下载特定历史版本；Open Design 更新很快，应先查看发行说明中的系统要求和已知问题。

Windows 桌面版安装后先做三项检查

安装并启动后，不要急着生成项目。先在 PowerShell 检查准备接入的 Agent：

1
2
3

Get-Command codex -ErrorAction SilentlyContinue
Get-Command claude -ErrorAction SilentlyContinue
Get-Command cursor-agent -ErrorAction SilentlyContinue

至少有一个命令返回可执行文件路径。如果 PowerShell 能找到 codex，Open Design 却显示未安装，通常不是 Agent 本身坏了，而是桌面程序启动时继承的 PATH 不完整。

处理顺序如下：

1. 完全退出 Open Design，包括系统托盘中的进程。
2. 确认 Agent 的安装目录已经加入用户级 PATH。
3. 重新登录 Windows，或从同一个 PowerShell 窗口启动 Open Design。
4. 在 Settings 的 Execution mode 中执行 Rescan。

不要为了让它被识别而复制可执行文件到系统目录，这会让后续升级和权限判断变得混乱。

用 Docker 启动一个可复现环境

Docker 路线适合先确认 Web UI 和本地 daemon 是否能正常工作：

1
2
3
4

git clone https://github.com/nexu-io/open-design.git
cd open-design/deploy
cp .env.example .env
openssl rand -hex 32

把生成的随机字符串填入 deploy/.env：

1
2
3

OPEN_DESIGN_PORT=7456
OPEN_DESIGN_MEM_LIMIT=384m
OD_API_TOKEN=替换成刚才生成的随机字符串

然后启动：

1
2
3

docker compose up -d
docker compose ps
docker compose logs --tail 100

验收标准不是“容器显示 Running”就结束，还要打开 http://localhost:7456，确认页面能加载、项目列表能打开，并且日志中没有反复出现数据库迁移、权限或令牌错误。

停止服务但保留数据：

1

docker compose down

docker compose down -v 会删除卷内数据，只应在确定不要现有项目时使用。

从源码运行

源码路线需要 Node.js 24。先检查版本：

1
2
3

node --version
corepack enable
corepack pnpm --version

项目当前锁定 pnpm 10.33.x。版本满足后执行：

1
2
3
4
5

git clone https://github.com/nexu-io/open-design.git
cd open-design
corepack enable
pnpm install
pnpm tools-dev run web

tools-dev 会打印实际使用的地址，开发端口可能动态分配，不要默认它一定是 3000。如果依赖安装失败，先检查 Node 主版本和 Corepack 选出的 pnpm 版本，不要直接删除锁文件重新解析依赖。

接入 Codex 或 Claude Code

Open Design 会扫描本机 Agent CLI。选择本地 CLI 后，生成任务会在受管理的项目目录中执行，因此需要同时确认三件事：

• Agent 已登录，能在普通终端完成一次最小请求。
• Agent 对 Open Design 项目目录有读写权限。
• 使用的沙盒或审批策略允许创建 HTML、CSS 和图片等产物。

可以先在终端运行只读检查：

1
2

codex --version
claude --version

版本命令成功不等于认证成功。再开一个临时目录，让 Agent 读取目录并返回一句说明；不要用真实客户项目作为第一次连接测试。

生成第一个可验收原型

新建项目时，使用一个边界清楚的 brief：

1
2
3
4
5

生成一个单页 SaaS 状态监控落地页。
受众是小型开发团队。
必须包含顶部导航、当前状态、最近事件和价格区块。
使用深色主题，不使用远程图片。
输出可编辑 HTML/CSS，移动端宽度 390px 时不能横向滚动。

第一次生成后按以下顺序验收：

1. 预览是否能加载，而不是一直停在空白 iframe。
2. 项目文件中是否存在真实 HTML、CSS 或组件文件。
3. 修改标题文本后，预览是否同步更新。
4. 浏览器开发者工具中是否有资源 404 或 JavaScript 异常。
5. 将视口切到 390px，确认没有横向滚动和按钮遮挡。
6. 关闭并重新打开项目，确认文件仍在，而不是只存在于一次会话中。

这组检查比“看起来很好看”更重要。它能区分真正可继续开发的制品和一次性预览。

用 CLI 检查插件和项目

安装了 od CLI 后，可以用结构化输出核对状态：

1
2
3
4

od plugin list --json
od plugin search "landing page"
od plugin info od-default
od project list --json

应用默认插件的示例：

1

od plugin apply od-default --input brief="a one-page status dashboard"

给外部 Agent 安装 MCP 接入：

1

od mcp install codex

安装后重新启动对应 Agent，再检查 MCP 工具列表。不要因为命令返回成功就假定客户端已经重新加载配置。

常见失败怎么判断

Agent 显示未安装

先比较 Get-Command codex 的路径与 Open Design 进程实际继承的 PATH。桌面程序启动于登录会话，刚添加的环境变量可能尚未生效。

页面能打开，但生成一直等待

检查 daemon 日志以及 Agent 是否在等待登录、目录授权或命令审批。若 Agent 单独运行也失败，应先修复 Agent，而不是反复重装 Open Design。

Docker 页面提示需要 Bearer Token

确认访问令牌已写入 .env，容器确实重新创建，并检查反向代理是否删除了 Authorization 请求头。

1
2
3

docker compose config
docker compose up -d --force-recreate
docker compose logs --tail 200

展示 docker compose config 时要遮住令牌，不要把完整输出发到公开 issue。

生成结果空白

打开开发者工具检查 Console 和 Network。若 HTML 文件存在但预览空白，优先排查入口文件、相对资源路径、CSP 和脚本运行错误；若文件根本没有生成，再查 Agent 工具调用。

备份、升级和恢复

升级前先备份项目目录和 Docker 卷。源码安装应保留本地修改：

1
2
3

git status --short
git pull --ff-only
corepack pnpm install

如果升级后不能启动，记录当前提交或 release 版本、Node/pnpm 版本和完整错误，再根据发行说明决定回退。不要用删除整个工作区作为第一步。

适用边界

Open Design 更适合希望让 Agent 交付可编辑设计文件的开发者。它不是 Figma 的完全替代，也不会自动解决品牌一致性、可访问性和真实用户验证。local-first 也不等于完全离线：使用云端 Agent 或 API 时，提示词和项目内容仍可能发送给对应服务商。

参考资料：

• Open Design GitHub
• Open Design Quickstart
• Open Design Releases