系列文章: Opendesign (3/11)

← Open Design 是什麼？為什麼這個 Claude Design 開源版要存在Open Design 的六個核心理念：搞懂哲學才知道為什麼這樣設計 →
Open Design 安裝與快速上手：從 clone 到第一張 artifact
#open-design#install#quickstart#pnpm#node#tutorial

Open Design 安裝與快速上手：從 clone 到第一張 artifact

5 min read

上一篇講完 Open Design 是什麼，這篇直接動手。先講結論：環境正常的話，五分鐘可以跑起來、看到第一張 artifact。下面我會把指令、必備版本、常見卡關點、第一次執行會看到什麼，全部交代清楚。

開工前的環境清單

需要備好的東西，缺一不可：

  • Node 24 — 不是 22、不是 20，就是 24
  • pnpm 10.33.x — 用 corepack 啟用最方便
  • git — 裝好就好
  • 至少一個 coding agent CLI — Claude Code、Codex、Cursor Agent、Gemini CLI、OpenCode、Qwen、Copilot CLI 任一個。沒有也行——daemon 會切到 BYOK 模式叫你貼 Anthropic API key

如果你 Node 不是 24，用 nvm 或 fnm 切一下：

nvm install 24 && nvm use 24
# 或
fnm install 24 && fnm use 24

五行指令跑起來

Quickstart 真的就這幾行：

git clone https://github.com/nexu-io/open-design.git
cd open-design
corepack enable
corepack pnpm --version   # 應該印出 10.33.2
pnpm install
pnpm tools-dev run web

最後一行跑完會在 terminal 印出 web URL（通常 http://localhost:3000 之類的），瀏覽器打開就是 Open Design 介面。

第一次啟動會發生什麼

pnpm tools-dev run web 的第一輪 boot 不只是把 Next.js 拉起來，daemon 在背景同時做四件事，你會看到 console 跑這幾步：

  1. 掃描 PATH — 找你系統有沒有裝 claude / codex / cursor-agent / gemini / opencode / qwen / copilot，找到誰就把誰當預設 agent
  2. 載入 19 個 skill — 從 skills/ 目錄讀 SKILL.md frontmatter，建索引
  3. 載入 71 個 design system — 從 design-systems/ 目錄讀 DESIGN.md，準備好下拉選單
  4. 建 .od/ 資料夾 — 不是 od init，daemon 自己 mkdir 出來

打開瀏覽器看到的歡迎對話框，主要在問你「要不要貼 Anthropic API key」——這是給 BYOK fallback 用的，CLI 偵測到的話可以跳過。

.od/ 是什麼？看一眼就懂

這是 Open Design 唯一的 runtime 資料夾，gitignored、機器本地、永遠不要 commit。長這樣：

.od/
├── app.sqlite                 ← 專案、對話、訊息、開啟中的 tab
├── artifacts/                 ← 一次性「Save to disk」的 render（含時間戳）
└── projects/<id>/             ← 每個專案的工作目錄，也是 agent 的 cwd

裡面那顆 SQLite 存的是你的會話狀態——明天打開電腦，todo card、訊息、tab 都還在原位。

要看裡面有什麼：

ls -la .od && sqlite3 .od/app.sqlite '.tables'

要打掉重練，把 daemon 停掉、整個資料夾砍掉、重新跑：

pnpm tools-dev stop
rm -rf .od
pnpm tools-dev run web

跑第一張 artifact

介面跑起來之後，最快感受到「它跟 ChatGPT 不一樣」的方法：

  1. 在 skill 下拉選 simple-deck 或 saas-landing
  2. design system 選 linear-app 或 vercel
  3. prompt 框打：「幫我做一張關於 ⟨你的副業⟩ 的 pitch deck，三頁就好」
  4. 送出

正常情況你會看到的不是「agent 立刻開始寫 HTML」，而是一張 form 跳出來——問你 surface、audience、tone、scale。這就是 RULE 1 在運作（反 AI-slop 那篇會詳細拆）。填完、選方向，agent 才開始 stream 出 todo card → 寫 HTML → 進 sandboxed iframe 預覽。

第一次看到 artifact 在 iframe 裡長出來那一刻，你會懂為什麼這個工具值得花時間。

常見卡關與解法

幾個最常踩到的坑：

pnpm: command not found — corepack enable 沒執行，跑一下就好。

Node 版本錯誤 — 用 nvm/fnm 切到 24，重來一次 pnpm install。

找不到任何 agent CLI — which claude which cursor-agent 看一下，至少裝一個；不然就在歡迎對話框貼 Anthropic key 走 BYOK。

Port 已被佔用 — pnpm tools-dev stop 把舊 daemon 殺掉再重啟。

SQLite 出錯 — 砍 .od/app.sqlite 重建（會清掉所有專案紀錄，慎用）。

下一步：搞懂為什麼它長這樣

裝好不等於會用。Open Design 的設計選擇——為什麼不自帶 agent、為什麼 skill 是檔案不是 plugin、為什麼 Design System 是 Markdown——背後有一套很清楚的哲學。

下一篇我們拆它的六個核心理念，看懂這六件事，後面 skill 和 design system 你會用得很順手；沒看懂，就會一直覺得「這工具怎麼有點怪怪的」。