Windows · 一鍵安裝腳本 v3.0English

Windows 安裝指南

一支 PowerShell 腳本，自動幫你在 Windows 上完成 AgEnD 的所有安裝 —— WSL 2 + Ubuntu、你選擇的 AI 後端（Kiro CLI、Claude Code、Antigravity、Codex）、 AgEnD 本體、串接 Discord／Telegram Bot，以及開機自動啟動。裝好之後，你直接在 Discord 或 Telegram 跟 AI Agent 對話即可，不需要開啟任何程式。

一行指令安裝

開啟 PowerShell（按 Win+X →「終端機」），貼上這一行後按 Enter：

powershell -ExecutionPolicy ByPass -c "irm https://songsid.github.io/AgEnD/install.ps1 | iex"

全新安裝要試用 beta，先在同一個 PowerShell 視窗執行以下指令，再貼上面的安裝指令：

$env:AGEND_VERSION = 'beta'

AGEND_VERSION 只接受 beta、latest 或完整版本號（例如 2.3.2）。未設定時安裝 latest；系統管理員重新啟動與重新開機接續都會保留選擇。這不會切換已安裝的 AgEnD 版本；既有安裝請用 agend update --beta。不想讓之後的新安裝沿用 beta，可執行 Remove-Item Env:AGEND_VERSION。

新安裝的 Linux 若要略過磁碟選單，可在一行指令前設定 $env:AGEND_WSL_DRIVE = 'D:'。只接受本機磁碟代號，而且必須有至少 5 GB 可用空間；取得系統管理員權限與重新開機接續都會保留選擇。重試時優先沿用已儲存的預定位置；既有 Linux 只會沿用，不會因為這個設定而搬移。之後不想沿用時可執行 Remove-Item Env:AGEND_WSL_DRIVE。

• 安裝程式要啟用 WSL，所以 Windows 會詢問一次系統管理員權限。選「是」之後，安裝程式會在新視窗裡執行：裝有 Windows Terminal 時在它裡面開（中文顯示正常），沒有的話是 PowerShell 視窗；你貼上指令的那個視窗會等它，最後告訴你結果。如果你開的已經是系統管理員 PowerShell，就直接在原視窗執行；若有安裝 Windows Terminal、而你不是在它裡面，會改在 Windows Terminal 重新開啟。設定 $env:AGEND_INSTALL_TERMINAL = 'conhost' 可保留舊的主控台視窗。
• -ExecutionPolicy ByPass 只對這一個指令有效，不會改動你的執行原則，也不需要解除封鎖檔案。
• 如果要求重新開機，按 Enter 就好：重新登入 Windows 後，安裝會自己繼續（Windows 會先問一次，請選「是」）。如果沒有自動繼續，再貼上同一行指令，就會從中斷處繼續。
• 每個比較久的步驟都會顯示已經過多久、通常需要多久，下面還有那個工具自己的進度。
• 請不要按 Ctrl+C：在那個視窗裡，它是「停止程式」，不是「複製」（自動安裝的步驟中按到，會先問你）。要複製，用滑鼠選取文字再按右鍵；要貼上，按右鍵。

想自己下載腳本再執行？請看手動安裝。 macOS 或 Linux 的一行安裝指令是 curl -fsSL https://songsid.github.io/AgEnD/install.sh | bash。

事前準備

系統需求

• Windows 11（或 Windows 10 版本 2004 以上），64 位元（x64 或 ARM64）
• 穩定的網路連線（需下載約 1–2 GB）
• 至少 5 GB 可用磁碟空間（建議 SSD）
• BIOS 虛擬化（VT-x / AMD-V）已啟用

帳號與 Bot 資料

• 你選的 AI 後端所需帳號 —— 例如 Kiro CLI 用免費的 AWS Builder ID，其餘則需 Anthropic / Google / OpenAI / xAI 帳號
• Discord 或 Telegram 帳號
• Bot Token（Discord：Developer Portal；Telegram：BotFather）——也可以完全不用：在設定頁選 Web only (no bot)，只用網頁儀表板

小提示：事先把 Bot Token 記在記事本，安裝時可直接貼上比較順暢。 Telegram：你在群組傳 /start 時，quickstart 會找出群組和你的 User ID。Discord：quickstart 會從你的伺服器訊息或 bot 私訊偵測帳號，請你確認；失敗時須手填有效 ID，另需 General 頻道 ID，請看 Discord Bot 設定教學。

安裝程式會做什麼

跟著畫面上的中文提示操作即可，全程約 10–20 分鐘（視網路速度而定）。安裝程式分成 5 個階段：

[1/5] 安裝 WSL 2 + Ubuntu —— 安裝 Ubuntu-24.04。如果有兩個以上可用空間至少 5 GB 的本機磁碟，會列出可用空間並讓你選擇安裝位置，標示建議的預設值（系統碟有至少 20 GB 時用系統碟，否則選空間最大的磁碟）；直接按 Enter 就採用預設。只有一個符合條件的磁碟時不會詢問。安裝前會記住位置，重試與重新開機接續都沿用；如果你已移除上次安裝的 Linux，會清掉舊位置並讓你重新選擇。如果電腦裡已經有 Ubuntu，會讓你選：另外安裝一個 AgEnD 專用的 Ubuntu，名稱是 AgEnD（建議，你原本的完全不動）；或用原本的那個（會修改它的設定，並說明改什麼）；直接按 Enter 就結束、不動任何東西。之後再執行時會沿用這個 AgEnD 專用的 Linux，不會再裝第三個。已經是 2 以上的 WSL 不會再更新；較舊的會先透過 Microsoft Store 更新，GitHub 只是備案（很多人共用同一個對外網路時，GitHub 可能暫時拒絕下載；安裝程式會說明狀況，現有的 WSL 能用時就繼續）。可能需要重開機一次；重新登入後會自動從中斷處繼續。
[2/5] 安裝 AI 後端（可多選） —— 用逗號分隔選擇一個以上（直接 Enter 只裝 Kiro CLI；接續安裝時會列出上次的選擇，按 Enter 沿用）。已經安裝、而且能回應 --version 的後端會保留並顯示版本，不會再跑它的安裝程式：
1. Kiro CLI（免費，需 AWS Builder ID / GitHub / Google）
2. Claude Code（需 Anthropic 帳號，Claude Pro $20/月+）
3. Antigravity CLI（免費，需 Google 帳號）
4. OpenAI Codex（需 ChatGPT 帳號或 API Key）
[3/5] 安裝 AgEnD —— 全自動（透過官方安裝腳本裝 Node.js 22 LTS + tmux）。
[4/5] 準備瀏覽器登入 —— Kiro CLI、Claude Code 與 Codex 會在下一個階段的設定頁、在瀏覽器裡登入：這個視窗不用選方法，也不用貼代碼。Kiro 會在那裡問登入方式，Claude Code 會給一段代碼讓你貼回網頁，Codex 會顯示連結與裝置代碼。在網頁上選 Sign in later，該後端就留到儀表板的 Needs you 再登入。Antigravity 維持主控台登入：安裝程式會印出之後要執行的指令。不支援瀏覽器登入的舊版 AgEnD 套件會改用主控台登入。
[5/5] 串接通訊軟體 + 啟動服務 —— 在瀏覽器裡完成，不用在主控台打字：安裝程式會打開 AgEnD 的設定頁，並幫你複製設定碼（在網頁上按 Ctrl+V 貼上）。在網頁上選擇 Discord 或 Telegram，貼上 Bot Token（按 Verify 會顯示這是哪個 bot），或選 Web only (no bot)，不用 bot、只用網頁儀表板（後端登入也在那裡：設定 → Agent → 登入）；Telegram 要在群組傳 /start 讓它找到群組；Discord 要確認偵測到的帳號，並填入 General 頻道 ID。完成後 AgEnD 會啟動，並安裝成系統服務。設定頁有 15 分鐘的期限並會倒數，最後三分鐘會提醒。設定頁關閉時（時間到、太久沒操作或設定碼錯太多次），安裝程式會說明原因：按 Enter 重新打開（已經登入的後端不會再問），或按 c 改在主控台進行同樣的設定（agend quickstart），設定頁打不開時也會提供這個選項。設定頁要求在主機上確認時，安裝程式會另外開一個執行 agend settings confirm 的視窗，列出會改變的內容並詢問 y/N；必須由電腦前的人回答。最後它會幫你打開網頁儀表板（一次性登入碼已經複製好，按 Ctrl+V 貼上即可），並在桌面放兩個捷徑：AgEnD 儀表板 之後隨時按兩下都能用同樣方式打開，AgEnD 重新啟動 會先問過你再重啟 AgEnD。這台電腦本來就裝了 AgEnD（例如一直用 agend update 更新）？再貼一次同一行指令即可：它會偵測到已經裝好，先問你要不要檢查／修復設定與服務，或接續後端登入（預設為否；不論哪種，原有設定都會保留），再提供新增或更新這兩個捷徑。它不會重做設定。主控台指令放在「進階」裡，需要時再看。

手動安裝

不用一行指令，改用同一支安裝腳本：下載 install-agend.ps1，自己執行。

放置腳本並以系統管理員開啟 PowerShell

把 install-agend.ps1 放到方便找到的位置（桌面、D:\Tools 等），路徑盡量不要有中文或特殊符號。接著開啟系統管理員 PowerShell：在搜尋列輸入「PowerShell」→ 右鍵 →「以系統管理員身分執行」（或按 Win+X →「終端機（系統管理員）」）。

允許執行腳本（首次需要）

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
Unblock-File .\install-agend.ps1

出現確認提示時輸入 Y，接著 cd 到腳本所在位置（例如 cd ~/Desktop）。

執行

.\install-agend.ps1

跟著畫面上的中文提示操作即可，階段和上面說明的 5 個相同。

安裝中斷怎麼辦？再貼上同一行指令即可（手動安裝的話，重新執行 .\install-agend.ps1）—— 安裝程式會自動偵測已完成的步驟並從中斷處繼續。若想完全重頭來過，先在同一個 PowerShell 視窗執行 $env:AGEND_INSTALL_FORCE = '1'，再貼上那一行指令；手動安裝的話，執行 .\install-agend.ps1 -Force。

開機自動啟動機制

腳本已設定三道機制，讓 Bot 在每次重開機後自動上線，完全不需手動操作。第二道需要第 5 步安裝的服務：quickstart 詢問要不要安裝服務時請回答要。如果跳過或安裝失敗，請在 WSL 裡執行 agend install。

1. Windows 登入後自動啟動 WSL：透過 Startup 資料夾中的 start-wsl.vbs（位置 %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\）。
2. WSL 內 AgEnD 由 systemd 服務自動啟動：只要 WSL 在運行，AgEnD 就會自動啟動。
3. WSL 不會閒置自動關閉：.wslconfig 讓它保持運行，關閉終端機視窗不影響服務。

日常使用

平常直接在 Discord／Telegram 跟 Bot 對話即可，不需要開啟任何程式。若 Bot 沒有回應，開啟 PowerShell 或 CMD：

wsl                                          # 進入 WSL（不論裝在哪個磁碟都一樣）

agend ls                                     # 查看所有 Agent 狀態
agend start                                  # 啟動所有 Agent 服務
agend stop                                   # 停止所有 Agent 服務
agend attach <名稱>                          # 進入某個 Agent 的操作畫面
agend update                                 # 更新 AgEnD 到最新版
agend web --code                             # 網頁 dashboard 的登入代碼（localhost:19280）
agend shortcuts                              # 建立或更新桌面捷徑
kiro-cli                                     # 手動開啟 Kiro CLI
exit                                         # 離開 WSL

離開 Agent 操作畫面：在 agend attach 裡按 Ctrl+B，放開，再按 D。不要按 Ctrl+C（會終止 Agent！）。

常見問題

出現「此腳本需要以系統管理員身分執行」？

請用右鍵 →「以系統管理員身分執行」開啟 PowerShell。

出現「無法連線到網路」？

安裝程式會先從 Windows、再從 WSL 檢查它需要的網站，並說明是哪裡失敗：DNS、逾時、連線被拒、不受信任的 HTTPS 憑證或 proxy，以及該怎麼做。會檢查 HTTPS 的公司網路，要把公司的根憑證放進 Ubuntu（設定 NODE_EXTRA_CA_CERTS）；公司 proxy 則要為 WSL 設定 Windows 的 proxy。必要的網站連不上時，安裝程式會先問你要不要繼續，預設是停止。

安裝紀錄在哪裡？

安裝程式顯示的所有內容也會寫進 %LOCALAPPDATA%\AgEnD\install-logs 的紀錄檔（保留最近 10 份）。設定碼、登入碼、token 與網址中的帳密會先遮蔽再寫入。安裝程式停止時，你貼上指令的那個視窗會說明停在哪個階段、紀錄檔在哪裡：求助時請附上那個檔案。

它停下來，說安裝會裝到另一個帳號

WSL、AgEnD、桌面捷徑與重新開機後的接續，都屬於執行安裝程式的那個帳號。如果一般帳號在系統管理員提示時輸入了另一位管理員的密碼，安裝程式會在修改任何東西之前停下，並列出兩個帳號。請 IT 在安裝期間給你的帳號系統管理員權限，或改用那個帳號登入後再安裝。

WSL 安裝後要求重開機？

正常現象。重開機後再執行一次腳本即可自動接續。

後端登入一直沒完成？

在設定頁取消那個登入再試一次，或選 Sign in later：該後端會留在儀表板的 Needs you，等 AgEnD 啟動後再登入。

電腦重開機後 Bot 不回覆了？

通常會自動恢復（需等待 30–60 秒開機啟動）。如果超過 2 分鐘仍無回應：

wsl -u root -- bash -lc "agend start"

公司電腦防毒軟體擋住 .vbs 啟動腳本？

請聯繫 IT 將 %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\start-wsl.vbs 加入白名單，或改為手動啟動（開機後執行一次 wsl 即可）。

BIOS 虛擬化沒開怎麼辦？

重開機進入 BIOS 設定（通常按 F2 / Del / F12），找到 Intel VT-x 或 AMD-V（SVM Mode）選項啟用。

如何更新 AgEnD？

在 General 傳 /update，或進入 WSL 後執行 agend update。如果你安裝時還沒有桌面捷徑，在 WSL 裡執行 agend shortcuts，就會建立「AgEnD 儀表板」和「AgEnD 重新啟動」；也可以再貼一次一行安裝指令，已經裝好 AgEnD 的電腦上，它會先問要不要檢查／修復，再問要不要更新捷徑。如果是 agend 指令本身不能用了（更新被打斷後出現 agend: command not found），再貼一次一行安裝指令：它會就地修復 AgEnD，保留你的設定和資料。

完全移除方法

在 PowerShell 中依序執行：

wsl --unregister Ubuntu-24.04
Remove-Item "$env:USERPROFILE\.agend-install-progress" -ErrorAction SilentlyContinue
Remove-Item "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\start-wsl.vbs" -ErrorAction SilentlyContinue

安裝程式在你的 %USERPROFILE%\.wslconfig 合併了兩個設定（[wsl2] vmIdleTimeout=-1 與 [general] instanceIdleTimeout=-1），保留你原有的其他設定，並在旁邊留了備份（.wslconfig.agend-backup-…）。請只刪掉這兩行，或還原備份；檔案裡有你自己的設定時，不要整個刪掉。

如需移除 WSL 功能本身：設定 → 應用程式 → 選用功能，關閉「Windows 子系統 Linux 版」。

使用 Linux 或 macOS？請改用首頁的一行安裝指令。