OpenClaw 安裝教學：Windows 建立 AI 代理 Hello World

OpenClaw 安裝在 Windows 上需要先確認 Node.js 執行環境，再完成 Gemini API Key 設定、Gateway 啟動與 Dashboard 操作。本文以實測截圖整理從環境確認到建立 hello-world.txt 的完整流程，涵蓋安裝過程中實際遇到的錯誤與處理方式，讓讀者能完整跑通第一個 AI 代理本機任務。

一、OpenClaw 安裝前的環境檢查

OpenClaw 安裝需要 Node.js 作為執行環境，因此第一步是開啟 Windows PowerShell，輸入 node -v 確認系統是否已安裝。若系統顯示「無法辨識 ‘node’ 詞彙是否為 Cmdlet、函數、指令檔或可執行程式的名稱」，錯誤分類為 ObjectNotFound: (node:String) []，FullyQualifiedErrorId 顯示 CommandNotFoundException，代表目前這台電腦尚未安裝 Node.js，或 Node.js 已安裝但尚未被 PATH 辨識。

接著在 PowerShell 中執行安裝腳本 iwr -useb https://openclaw.ai/install.ps1 | iex，第一次執行時這次實測曾出現「無法連接至遠端伺服器」，通常與當下網路連線或代理狀態有關；重新執行同一道指令後，進入 OpenClaw Installer 畫面，安裝器顯示 [OK] Windows detected、[!] Node.js not found，接著自動嘗試以 winget 安裝，顯示 [*] Installing Node.js... Using winget...。

這類錯誤不是 OpenClaw 本身的問題，而是系統在目前的 PATH 設定中找不到 node 指令。確認前置條件再執行安裝腳本，是避免後續流程中斷的關鍵第一步。更多安裝細節可參考 OpenClaw 官網的說明文件。

二、安裝 Node.js 與啟動 OpenClaw 設定

安裝器中止並提示「Please close this terminal, open a new one, and run this installer again.」後，贊贊小屋直接在同一視窗執行 winget install OpenJS.NodeJS.LTS，Microsoft Store（msstore）來源需要同意合約條款，輸入 y 確認後，找到 Node.js (LTS) [OpenJS.NodeJS.LTS] 版本 24.16.0，完成驗證與安裝，畫面最終顯示「已成功安裝」。

重新開啟終端機再次執行安裝腳本後，進入 OpenClaw onboarding 畫面，安裝器先顯示一組安全原則提醒，包含多使用者或共用情境需要拆分信任邊界（split trust boundaries）、建議使用沙盒與最小權限工具（Sandbox + least-privilege tools）、不要把密鑰放進代理可讀取的檔案系統（Keep secrets out of the agent’s reachable filesystem）、有工具存取能力的代理應優先使用最強可用模型。畫面底部出現「I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?」，確認 Yes 後進入 Setup mode 選單，選擇 QuickStart (recommended)。

Node.js 安裝完成後需要關閉目前的 PowerShell 視窗，重新開啟一個新的終端機，PATH 才會更新，後續的 OpenClaw 安裝流程才能正確辨識 Node.js。這段安全提醒並非裝飾，而是 OpenClaw 在設計上對代理工具風險的明確揭露，因為它在授權範圍內可以執行工具、操作本機檔案，因此在 onboarding 階段先確認使用者理解安全邊界，才進入實際設定。

三、選擇 AI 模型供應商

QuickStart 確認後，畫面顯示本機閘道設定摘要：Gateway port 18789、Gateway bind Loopback（127.0.0.1）、Gateway auth Token（default）、Tailscale exposure Off、Direct to chat channels，下方同時出現 Model/auth provider 選單，列出 OpenAI、Anthropic、xAI（Grok）、Google、OpenRouter、More…、Skip for now 等選項供選擇。

選擇 Google 後，Google auth method 選 Google Gemini API key，畫面進入 Enter Gemini API key 等待輸入，上方同時顯示已確認的設定摘要：Model/auth provider 為 Google、Google auth method 為 Google Gemini API key。

QuickStart 的本機 Loopback 設定表示這次為本機單人測試，不對外開放，也不需要額外的網路配置。OpenClaw 支援多個模型供應商，選擇 Google 並使用 Gemini API key 是免費入門最快的路徑，後續也可以透過 openclaw configure 切換到其他供應商。

四、取得 Google Gemini API Key

開啟瀏覽器前往 Google AI Studio，畫面左下角出現鑰匙圖示，點選後彈出 Get API key 提示，進入 API Keys 管理頁面，準備為這次 OpenClaw 連線建立專屬金鑰。

點開 API key details 後，彈出視窗顯示 API Key 欄位（內容以遮蔽方式呈現）、Name 欄位顯示 Gemini API Key、Project name 與 Project number，下方提供 Delete key、Copy cURL quickstart、Copy key 三個操作按鈕，使用 Copy key 複製後，準備回到 OpenClaw 終端機貼入。

API Key 是連接 Google 模型服務的憑證，雖然不是登入密碼，但一旦外洩可能被他人拿來呼叫 API、消耗配額或產生費用，因此截圖與文章都不能公開完整內容。Gemini Free tier 可以完成第一個 Hello World 任務，但贊贊小屋在後續使用中很快遇到 429（Too Many Requests）的回應，因此 Free tier 適合入門示範，若要長時間測試 Skills 或執行多步驟代理流程，仍需評估本機模型、其他供應商或付費 API。

五、輸入金鑰與背景服務啟動

回到 OpenClaw 終端機，在 Enter Gemini API key 欄位貼上剛才複製的金鑰，輸入過程中終端機以圓點遮蔽顯示，不會明文呈現，確認送出後完成模型連線設定。

接著 onboarding 詢問「Configure skills now? (recommended)」，這次選 No；隨後出現 Hooks 說明畫面，說明 Hooks 可以在代理指令觸發時自動執行動作，例如在 /new 或 /reset 時自動儲存工作階段記憶，並列出 boot-md、bootstrap-extra-files、command-logger、compaction-notifier、session-memory 等選項，畫面提示「Please select at least one option. Press space to select, enter to submit」，「Enable hooks?」選擇 Skip for now 直接跳過。

OpenClaw 啟動 Gateway，終端機顯示版本號 OpenClaw 2026.6.8（844f405），依序出現 [gateway] loading configuration...、[gateway] resolving authentication...、[gateway] starting...、[gateway] starting HTTP server...、[health-monitor] started，以及 [gateway] agent model: google/gemini-3.1-pro-preview (thinking=medium, fast=off)，最後出現 [gateway] ready 與 [heartbeat] started，代表本機代理服務已正常啟動。

Skills 與 Hooks 是 OpenClaw 進階自動化的核心機制，值得獨立深入介紹，但第一次安裝的目標是跑通基本代理任務，先確認 Gateway 啟動、模型連線與工具調用都正常運作，再進入配置才不容易混亂。本次測試過程中曾切換 Gemini 模型，最後實際完成 Hello World 任務的是 Gemini 2.5 Flash。

六、開啟 Dashboard 並進入網頁介面

在新的 PowerShell 視窗輸入 openclaw dashboard，若 Gateway 已在背景運行，會先看到「Gateway failed to start: gateway already running」並提示 Port 18789 is already in use，這不是錯誤，代表服務正常執行；終端機接著顯示 Dashboard URL: http://127.0.0.1:18789/，並說明 Token auto-auth 已包含在瀏覽器開啟的 URL 中。

瀏覽器自動開啟，網址列顯示 127.0.0.1:18789/chat?session=main，畫面中央出現 Assistant 與 Ready to chat 狀態，下方有 Message Assistant (Enter to send) 輸入框，以及 What can you do?、Summarize my recent sessions、Help me configure a channel、Check system health 等快速指令按鈕。

Gateway 是 OpenClaw 的核心中繼層，Dashboard 只是其中一種前端介面，TUI、Dashboard 或後續可能設定的其他 Channel，本質上都是連到 Gateway，再由 Gateway 管理模型、工具與代理工作階段。

七、見證 AI 代理操作本機檔案

贊贊小屋在 Message Assistant 輸入框輸入：

「請使用本機工具，在以下完整路徑建立一個純文字檔案：

C:\Users\zanzan\Documents\OpenClaw-HelloWorld\hello-world.txt

檔案內容：

Hello World!」

送出後畫面出現 Activity: 2 tools Write，代理確認調用了工具，接著回覆「好的，我已經在 C:\Users\zanzan\Documents\OpenClaw-HelloWorld\hello-world.txt 建立了內容為 Hello World! 的純文字檔案。」

開啟檔案總管，路徑列顯示 Documents → OpenClaw-HelloWorld，資料夾中出現 hello-world.txt；用記事本開啟，內容為 Hello World!，記事本底部顯示第 1 行、第 1 欄、12 個字元、純文字、UTF-8 編碼，與贊贊小屋在 Dashboard 指定的內容完全一致。

這一步是 Chatbot 與 Agent 的關鍵差異：普通聊天工具只能回答你的問題，AI 代理在取得工具授權後，可以理解任務、選擇對應工具、實際改變本機的檔案狀態。AI 回覆完成不等於任務真的完成，用檔案總管實際確認結果，是使用 AI 自動化時應該保留的最後一道人工驗證。

裝好 OpenClaw 才看懂 AI 代理和聊天工具的差別

這次安裝下來，表面上是裝了一套新工具，但贊贊小屋覺得更像是摸清了 AI 代理的第一層邏輯。Node.js 是執行環境、API Key 是模型連線的憑證、Gateway 是工作的中樞、Dashboard 只是其中一種對話介面，而 Tool Write 才是代理真正做事的地方。這四個環節缺一個，Hello World 就不會出現在檔案總管裡。

ChatGPT 或 claude.ai 讓人習慣了「問它、它答」的模式。OpenClaw 第一次讓贊贊小屋感覺到另一種可能：用自然語言說清楚要做什麼，代理理解後去執行，最後在電腦裡留下一個真實的結果。Hello World 這個任務很小，但這個閉環的意義不小。後續的 Skills、Hooks 與 MCP 都是在這個基礎上往外擴展，先把這一層走通，後面的路才會清楚。

學會計、學Excel、學習AI工具，歡迎加入贊贊小屋社群。

Claude Code 教學：從安裝到 Excel、PPT 與網頁實戰

Claude Code 教學、ChatGPT怎麼用？、ChatGPT Excel教學、ChatGPT寫ExcelVBA、Gemini是什麼？、Notion教學、AI對會計的影響。

贊贊小屋AI課程：OpenClaw AI 代理、Codex 網站、Claude Code 實戰、ChatGPT課程、AI工具全攻略、Notion課程。