系列目录
– （一）部署篇 ← 你在这里
– （二）核心概念篇 —— 模式 × Skill × Design System × Agent
– （三）实战案例篇 —— 从 0 到 1 设计一个攀岩者网站
写在前面
Open Design（OD）是 Claude Design 的开源替代品。它不自带 AI 模型，而是调用你电脑上已有的 Agent CLI（Hermes、Claude Code、Codex 等），输入一句话需求，输出可交互的 HTML 设计稿。
你将收获：
- 一个本地运行的 AI 设计工具
- 支持生成网页、PPT、App 原型、仪表盘等
- 72 套内置品牌风格一键切换
- 完全离线可用，数据不离开你的电脑
第一章：环境要求
必需依赖
| 依赖 | 版本要求 | 说明 |
|---|
|—|—|—|
| Node.js | 24.x（精确到 24，不支持 22/26） |
运行时引擎 |
|---|---|---|
| pnpm | 10.33.x |
包管理器 |
| 操作系统 | macOS / Linux / WSL2 | Windows 原生也可但不推荐 |
| Agent CLI | 至少一个 | Hermes / Claude Code / Codex / Gemini 等 |
为什么必须是 Node 24？
Open Design 使用了 better-sqlite3 等原生 C++ 模块，这些模块编译时绑定了特定 Node 版本的 ABI（应用二进制接口）。Node 22 的 ABI 版本是 127，Node 24 是 137，Node 26 是 147 —— 版本不匹配会报 NODE_MODULE_VERSION 错误。
第二章：安装 Node 24
方案 A：使用 nvm（推荐）
`bash
# 安装 nvm（如果没有）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
# 安装并切换到 Node 24
nvm install 24
nvm use 24
node -v # 应输出 v24.x.x
`
方案 B：直接下载二进制
`bash
# 创建目录
mkdir -p ~/.local/node24
# 下载（国内用 npmmirror 镜像）
curl -L -o ~/.local/node24/node-v24.tar.xz
“https://npmmirror.com/mirrors/node/v24.1.0/node-v24.1.0-linux-x64.tar.xz”
# 解压
cd ~/.local/node24 && tar xf node-v24.tar.xz
# 验证
~/.local/node24/node-v24.1.0-linux-x64/bin/node -v
# 输出: v24.1.0
`
方案 C：系统包管理器
`bash
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash –
sudo apt-get install -y nodejs
# Arch Linux
sudo pacman -S nodejs-lts-jod # 如果 AUR 有 24.x 的话
`
第三章：安装 Open Design
3.1 克隆仓库
`bash
cd ~
git clone https://github.com/nexu-io/open-design.git
cd open-design
`
3.2 配置 npm 镜像（国内用户必做）
`bash
# 写入 ~/.npmrc
cat >> ~/.npmrc << 'EOF'
registry=https://registry.npmmirror.com
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
EOF
`
3.3 启用 Corepack 并安装依赖
`bash
# 启用 corepack（自动选择 pnpm 版本）
corepack enable
# 验证 pnpm 版本
corepack pnpm –version
# 应输出: 10.33.2
# 安装依赖（首次约 2-5 分钟）
corepack pnpm install
`
3.4 批准构建脚本
`bash
# 允许原生模块的 postinstall 脚本
corepack pnpm approve-builds
`
这一步是让 better-sqlite3、sharp 等原生模块执行编译。
3.5 重建原生模块（如果切换过 Node 版本）
`bash
corepack pnpm –filter @open-design/daemon rebuild better-sqlite3 –pending
`
第四章：启动 Open Design
4.1 基本启动命令
`bash
# 确保使用 Node 24
export PATH=”$HOME/.local/node24/node-v24.1.0-linux-x64/bin:$PATH”
# 启动 daemon + web（前台模式，适合开发调试）
pnpm tools-dev run web
# 或后台模式
pnpm tools-dev start daemon web
`
4.2 指定固定端口（推荐）
`bash
# 固定端口，避免每次重启端口变化
pnpm tools-dev start daemon web –daemon-port 3456 –web-port 4567
`
启动后：
- Web 界面：
http://127.0.0.1:4567 - Daemon API：
http://127.0.0.1:3456
4.3 写一个启动脚本（一劳永逸）
`bash
cat > ~/.local/bin/start-open-design.sh << 'SCRIPT'
#!/bin/bash
export PATH=”$HOME/.local/node24/node-v24.1.0-linux-x64/bin:$HOME/.local/bin:$PATH”
cd ~/open-design
pnpm tools-dev stop 2>/dev/null
pnpm tools-dev start daemon web –daemon-port 3456 –web-port 4567
sleep 3
pnpm tools-dev start web –daemon-port 3456 –web-port 4567
pnpm tools-dev status
SCRIPT
chmod +x ~/.local/bin/start-open-design.sh
`
以后只需一条命令：
`bash
~/.local/bin/start-open-design.sh
`
4.4 常用管理命令
`bash
cd ~/open-design
# 查看状态
pnpm tools-dev status
# 查看日志
pnpm tools-dev logs
# 重启
pnpm tools-dev restart –daemon-port 3456 –web-port 4567
# 停止
pnpm tools-dev stop
`
第五章：配置 Agent
5.1 Agent 是什么？
Open Design 不自带 AI 模型，它调用你电脑上已有的 Agent CLI。Agent 是实际执行设计生成的引擎。
5.2 支持的 Agent 列表
| Agent | 安装命令 | 检测方式 |
|---|
|—|—|—|
| Hermes | pip install hermes-agent |
which hermes |
|---|---|---|
| Claude Code | npm i -g @anthropic-ai/claude-code |
which claude |
| Codex | npm i -g @openai/codex |
which codex |
| Gemini CLI | npm i -g @anthropic-ai/gemini-cli |
which gemini |
| OpenCode | 见 opencode.ai | which opencode-cli |
| Cursor Agent | 见 cursor.com | which cursor-agent |
| Qwen Code | 见 github.com/QwenLM | which qwen |
| GitHub Copilot | 见 github.com | which copilot |
5.3 验证 Agent 是否被检测到
`bash
# 查看所有已检测的 Agent
curl -s http://127.0.0.1:3456/api/agents | python3 -m json.tool
`
在输出中找到 "available": true" 的 Agent 就是可以使用的。
5.4 确保 PATH 包含 Agent 路径
如果 Agent 安装在 ~/.local/bin，启动时需要加到 PATH：
`bash
export PATH=”$HOME/.local/bin:$PATH”
`
这就是为什么我们的启动脚本里有 $HOME/.local/bin。
第六章：验证安装
6.1 检查清单
`bash
# 1. Node 版本
node -v # 应为 v24.x.x
# 2. pnpm 版本
pnpm –version # 应为 10.33.2
# 3. Open Design 健康检查
curl -s http://127.0.0.1:3456/api/health
# 输出: {“ok”:true}
# 4. Web 界面
curl -s -o /dev/null -w “%{http_code}” http://127.0.0.1:4567/
# 输出: 200
# 5. Agent 列表
curl -s http://127.0.0.1:3456/api/agents | grep ‘”available”: true’
# 应看到至少一个 Agent
`
6.2 首次打开 Web 界面
- 浏览器打开
http://127.0.0.1:4567 - 顶部选择 Agent（如 Hermes）
- 选择 Skill（默认
web-prototype） - 选择 Design System（默认
Neutral Modern） - 输入一句话需求，点击 Send
- 等待 1-3 分钟，右侧出现渲染预览
第七章：排障指南
| 问题 | 原因 | 解决方案 |
|---|
|—|—|—|
NODE_MODULE_VERSION 错误 |
Node 版本不对 | 确认用 Node 24，运行 pnpm --filter @open-design/daemon rebuild better-sqlite3 --pending |
|---|---|---|
no agents found on PATH |
Agent CLI 不在 PATH | which hermes 确认存在，启动脚本加 $HOME/.local/bin |
| 端口被占用 | 其他进程占了端口 | lsof -i :3456 查看并 kill，或换端口 |
| Web 页面空白 | Web 服务没启动 | pnpm tools-dev status 检查，单独启动 pnpm tools-dev start web |
| 生成超时 | Agent 响应慢 | 正常 1-3 分钟，超过 5 分钟检查 Agent 日志 |
| Electron 报错 | 没有图形界面 | 只启动 daemon + web，不启动 desktop |
下一篇
环境搞定了，接下来我们搞清楚 Open Design 的核心概念：四种模式、Skill、Design System、Agent 分别是什么，怎么组合使用。
发表回复