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