agent-browser 的桌面版:讓 Claude Code 操作 Windows 桌面程式(實測)
agent-desktop 是 Vercel Labs 出的命令列工具,和 agent-browser 出自同一個團隊,做法相同,文件也放在同一個網站。它讀作業系統的無障礙樹(Windows 上是 UI Automation),把一個視窗印成 JSON,每個可以操作的元素附一個 ref。agent 對 ref 下 click 或 set-value,再讀一次確認結果。工具裡面沒有模型,觀察、決定、驗證的迴圈由呼叫它的 Claude Code 自己跑。
這篇寫給已經在用 Claude Code 或 agent-browser 的人。README 把功能講得很清楚,我們補的是 Windows 上實際跑出來的結果:哪些程式讀得到、哪些讀不到、官方說明和實測不一致的地方。測試環境是 Windows 10 Pro(19045)、agent-desktop 1.2.0,日期 2026-11-10。當天這個專案在 GitHub 有約 2.1 萬顆星,Apache-2.0 授權。
2026-11-18 發布前我們對當時最新的 1.3.1 複查過一次。1.3.0 和 1.3.1 的更新集中在 macOS(新增 sandbox 指令與 macOS 虛擬機)和 Linux 的相依套件,本文用到的指令和 Windows 上的行為沒有變。我們在同一台機器用 1.3.1 重跑了 status、skills get platform、list-windows 和系統匣 snapshot,都正常執行,status 的欄位與支援的系統介面清單和 1.2.0 完全相同。
安裝:兩分鐘
需要 Node.js 18 以上與 Git for Windows。下面的指令釘在 1.3.1(2026-11-18 的最新版)。文中的數字和截圖是在 1.2.0 量的。
npm install -g agent-desktop@1.3.1
agent-desktop status
status 會回一段 JSON,看三個地方:accessibility 是 granted、platform 是 windows、supported_surfaces 列出它讀得到的系統介面。Windows 不會跳任何授權視窗。
本文只在 Windows 10 實測,Windows 11 的新版記事本沒測。執行檔沒有程式碼簽章,Defender 可能隔離它,Windows 11 的 Smart App Control 開著時會直接擋下(官方 troubleshooting 有寫)。第一次在 Git Bash 執行會看到一行 Node launcher 的提示,不是安裝失敗。

圖說:圖下方英文小字的意思是,輸出重新縮排過,家目錄顯示成 %USERPROFILE%,值是 null 的欄位省略。
裝之前我們把 npm 套件的 postinstall 腳本讀過一遍。它只在套件內附的執行檔雜湊不符時才下載,下載後比對 checksum。腳本只寫了 github.com/vercel-labs/agent-desktop 的 Releases 網址(下載時 GitHub 會轉到自家的 githubusercontent.com),沒有第三方來源。它另外會把 npm 的 .cmd、.ps1 改成直接呼叫原生執行檔。我們也比對過,npm 套件內附的執行檔和 GitHub Release 裡的 sha256 相同,gh attestation verify 通過。
接著讓 agent 讀說明書。這個工具有兩條路:
# 路一:執行檔自己帶說明
agent-desktop skills get desktop
agent-desktop skills get platform # 自動給你現在這個作業系統的版本
# 路二:用 skills.sh 裝成 skill
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop
# Windows 再加一個
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop-windows
我們選路一,沒有裝 skill。說明跟著執行檔走,升級之後 agent 讀到的永遠是當前版本的寫法,不會發生「skill 還停在舊版、指令已經改了」這種事。如果你自己也在做給 agent 用的 CLI,這個設計值得抄:把說明書編進執行檔,用一個子指令印出來。
1.2.0 起還附了 MCP 伺服器模式。掛上 MCP 的每個 session 都拿到整個桌面的讀寫權,我們先不開,需要時才用命令列呼叫。1.3.0 新增的 sandbox(在隔離的桌面裡跑)目前只支援 macOS,官方 Windows skill 寫明 Windows 還不能用。
三分鐘最小迴圈:記事本
以下指令都在 Git Bash 裡跑,PowerShell 的差別後面講。先手動開一個新的記事本(Windows 10 的傳統記事本),隨便打一行字。
# 1 找到視窗 id
agent-desktop list-windows
# 在輸出裡找 app_name 是 notepad.exe 的那一筆,記下 id,例如 w-7087970
# 2 讀
agent-desktop snapshot --window-id w-7087970 -i --compact
-i 只留可互動的元素,--compact 把沒名字的單一子節點摺掉。我們這個記事本回來 4KB、17 個 ref,約 0.5 秒。這 0.5 秒是直接呼叫 npm 全域資料夾底下的原生執行檔。在 Git Bash 打 agent-desktop 會先經過 Node 啟動器,約 1.1 到 1.3 秒。標題列三顆按鈕長這樣(節錄):
{ "name": "最小化", "role": "button", "ref_id": "@s1lmcgdsiu6pc0:e10", "available_actions": ["Click"] },
{ "name": "最大化", "role": "button", "ref_id": "@s1lmcgdsiu6pc0:e11", "available_actions": ["Click"] },
{ "name": "關閉", "role": "button", "ref_id": "@s1lmcgdsiu6pc0:e12", "available_actions": ["Click"] }
欄位名是 ref_id,不是 ref,自己寫解析時會踩到。按鈕名稱跟著系統語言走,英文系統會是 Maximize 和 Restore。
下面指令裡的 ref 是我們這次的編號。ref 每次 snapshot 都不同,換成你自己輸出裡的。
# 3 點
agent-desktop click @s1lmcgdsiu6pc0:e11
# 4 再讀一次
agent-desktop snapshot --window-id w-7087970 -i --compact
第二次 snapshot 裡,同一個位置的按鈕名稱變成「還原」,ref 也換成新的 snapshot 編號。視窗確實放大了,迴圈成立。

圖說:圖下方英文小字的意思是,標題列是用 agent-desktop screenshot --window-id 對測試用記事本拍下後裁切的,JSON 只留相關欄位。
圖裡 click 的回傳有兩個欄位要看。delivery 是 delivered_unverified,意思是指令送出去了,工具沒辦法替你確認結果。retry 是 unsafe,意思是不要直接重按,開關類的按鈕會被按回去。所以每個動作後面都要接一次讀取,這一步省不得。
填字用 set-value。它直接寫入欄位的值,不經過鍵盤,中文不會被注音輸入法吃掉,寫完還會回讀比對。文字區是 role 為 textfield 的那一筆(我們這份是 e1,名稱「文字編輯器」),ref 一樣換成你自己輸出裡的:
agent-desktop set-value @s2lw9pi2pj0ukf:e1 "hello 中文"
「讀」比「點」更順手:從系統匣讀 VPN 狀態
這次測下來,最順手的是唯讀指令。例子是確認 VPN 有沒有連著。以前的做法是把 VPN 客戶端的視窗叫出來截圖再看圖,現在一行:
agent-desktop snapshot --surface system-tray-overflow -i --compact
它讀的是工作列右下角「顯示隱藏的圖示」那一格。不用開任何視窗,前景視窗和游標都不動。我們這台回來 6.4KB、38 個按鈕,0.2 秒。VPN 客戶端那顆按鈕的名稱直接寫著連線狀態:

agent 只要找名稱裡有沒有 Connected to 就知道答案。圖中紅底的兩處是我們手動換掉的,其餘 37 個系統匣項目也拿掉了,原因見後面的隱私提醒。
一個小坑:只待在系統匣、沒有視窗的程式不會出現在 list-apps,要用 --surface 這條路讀。
Chrome:先拿骨架,再鑽進去
瀏覽器視窗的樹很大。我們另開一個全新設定檔的 Chrome,只開 ultralab.tw/blog 一頁,量三種讀法的 JSON 大小:


圖說:上半(Page A)是這次在乾淨視窗量的。下半(Page B)是當天上午第一次測試的數字,量的是另一個頁面,旗標依當時的紀錄,所以第一列只標 --skeleton。長條的長度只在同一頁內互相比較。
| 讀法 | 這一頁(415 個 ref) | 另一個文字較多的頁面(338 個 ref,旗標依上午紀錄) |
|---|---|---|
--skeleton -i --compact |
18.8KB | 30KB,1.0 秒(紀錄只寫 --skeleton) |
-i --compact |
194.2KB | 126KB,2.8 秒 |
| 不加參數(完整樹) | 808.3KB | 469KB,2.9 秒 |
這些 JSON 是要給模型讀的。粗估一個 token 三到四個位元組,808KB 的完整樹超過 20 萬 token。Claude Code 的 Bash 工具預設只把約 3 萬字元的輸出直接放進對話,超過的存成檔案、只給前 2,000 字元預覽,agent 得自己分段去讀。完整樹(808KB)和 -i --compact(194KB)都超過這個上限,只有骨架(18.8KB)整份進得去。骨架比完整樹小 43 倍,比 -i --compact 小約 10 倍。
時間的差距比較不穩定。第一次測(右欄)骨架 1.0 秒、完整樹 2.9 秒。重測時機器同時在跑別的工作,三種讀法各跑 5 次,中位數是 3.6、4.0、4.2 秒,單次落在 3 到 5.5 秒,分不出快慢。大小的差距兩次都在,省 token 才是用 --skeleton 的理由。
骨架裡被截斷的容器會帶 children_count,告訴你下面還有東西。接著用 --root 只讀那一塊:
agent-desktop snapshot --window-id <id> --skeleton -i --compact
agent-desktop snapshot --root <某個容器的 ref> -i --compact
兩件事要記得。第一,鑽得不夠深等於沒鑽:我們對整個網頁文件鑽下去,因為這頁有 335 個連結,回來還是 175.8KB。第二,鑽過的那一塊,原本的舊 ref 全部作廢,再用會回 STALE_REF,要改用新回傳的 ref。
網頁裡的事其實交給 agent-browser 更合適。對 Chrome 用 agent-desktop,比較說得通的是瀏覽器本身的外框,例如工具列。這部分我們只讀過,還沒實際點過。
誠實的邊界
LINE 桌面版的登入畫面讀不到。 LINE 是 Qt 寫的。我們測的是登入畫面:39 個節點裡 36 個是沒有名字的群組,按鈕和勾選框沒有角色也沒有名稱,只認得出兩個輸入框。這兩個輸入框沒有名字、長得一模一樣,對它們下 set-value、get、type,全部回 AMBIGUOUS_TARGET。Windows 上的 ref 要求元素在整個視窗裡獨一無二,雙胞胎一律拒絕。剩下的路只有帶座標的 --headed mouse-click --xy,等於回到看圖點座標。登入後的聊天畫面我們沒有測。
「不搶焦點」在 Windows 上不成立(我們在 Windows 10 實測,上游也有人在 Windows 11 回報)。 官方說 ref 動作預設 headless,不移動游標也不拿走焦點。我們開兩個記事本驗證:讓 B 在前景,對背景的 A 下指令,每一步記錄前景視窗和游標座標。
| 指令 | 游標 | 前景視窗 |
|---|---|---|
| snapshot、get(唯讀) | 不動 | 不變 |
| set-value | 不動 | 被換成 A |
| click | 不動 | 被換成 A |
游標真的不動,但視窗會被拉到最前面。你正在打字的時候,agent 的一個 click 就會讓接下來的按鍵落到別的視窗。上游 issue #567 回報的是同一件事,到 2026-11-18 還開著。上游已有修補 PR #613(2026-11-08 開,截至 2026-11-18 未合併,1.3.0 和 1.3.1 都沒有收進這個修正),原因是 UI Automation 預設會在動作前先對元素設焦點(AutoSetFocus)。在修好之前,會動作的步驟要當成「會打擾人」來排。
Windows PowerShell 5.1 有兩個坑,一個會報 INVALID_ARGS,一個完全不報錯。
第一個,官方 README 與 Windows skill 都有提醒:ref 不加引號會整個消失。PowerShell 把 @開頭 的字當成 splatting 運算子,參數根本到不了程式,回的是 INVALID_ARGS,說你少給了 ref:
agent-desktop get @s158g9ceipyrbp:e1 --property value # INVALID_ARGS
agent-desktop get '@s158g9ceipyrbp:e1' --property value # 正常
第二個比較危險。用管線把字串送進 --stdin,寫進去的內容會被 PowerShell 改掉,工具卻回報成功。Windows PowerShell 5.1 的實測(PowerShell 7 我們沒測):
| 送進去 | 欄位實際拿到 | 工具回報 |
|---|---|---|
'abc' |
abc 加一個換行 |
ok: true、delivered_verified |
'中文'(預設編碼) |
?? 加一個換行 |
ok: true、delivered_verified |
中文(改從 Git Bash 用管線送) |
中文,一字不差 |
ok: true、delivered_verified |
工具沒有說謊,它忠實寫入了收到的位元組,問題出在 PowerShell 管線送出去的已經是另一串字。如果你用這條路把密碼送進登入欄,送出的會是一組錯的密碼。先把 $OutputEncoding 設成 UTF-8 也救不了:中文對了,前面卻多一個 BOM(EF BB BF),一樣被原樣寫進欄位。我們的規矩是一律用 Git Bash 呼叫,機密內容用 --stdin < 檔案 導入。
密碼檔請你自己在終端機建立,用 printf '%s' 寫入、不要用 echo,結尾不能有換行,編碼 UTF-8,再執行 agent-desktop set-value <ref> --stdin < 密碼檔。官方示範的是 printf '%s' 'hello' | agent-desktop set-value <ref> --stdin,同一個原則。這樣做的理由是文字不會出現在命令列參數,JSON 回傳也不含 value 欄位。要讓 Claude Code 遵守「一律 Git Bash」,在 CLAUDE.md 寫「agent-desktop 一律用 Bash 工具」,或設 CLAUDE_CODE_USE_POWERSHELL_TOOL=0。沒裝 Git for Windows 的人只有 PowerShell 工具可用。
幾個指令在 Windows 一定要 --headed。 type、right-click 不加 --headed 會回 POLICY_DENIED(官方有寫,type 我們實測過)。double-click、triple-click、focus 官方只說要 --headed。它們靠的是實體輸入。填字優先用 set-value。
launch notepad 不一定開新視窗。 第一次測試時,它回傳的是桌面上早就開著、還有未存檔內容的那個記事本,差一點就寫了進去。同名視窗有兩個時,--app notepad 也不會報錯,它會自己挑一個。所以前面的範例一律用 --window-id。
什麼時候用哪一個
- 網頁上的事:agent-browser。
- 桌面程式,而且元素有名字(傳統 Win32、Electron、系統匣、Chrome 的外框):agent-desktop。
- 元素沒有名字的程式(這次測到的 LINE 登入畫面):回到截圖加座標,別在 ref 上耗時間。
- 鎖定畫面和 UAC 提權視窗:官方文件寫明不支援。它也沒有螢幕錄影,只能截單張圖。
判斷方法很簡單,對目標視窗跑一次 snapshot -i --compact,看按鈕有沒有名字。名字要在整個視窗裡獨一無二,才拿得到能用的 ref。
隱私提醒
snapshot 會把畫面上的字原樣印出來。我們測 VPN 客戶端時,JSON 裡直接有帳號和內網位址。測 Chrome 時是整頁文字。這些內容接著會被 agent 讀進對話,交給模型。
三個習慣:
- 輸出導到不進版本控制的資料夾,不要貼進公開的 log、commit、issue 或聊天室。圖裡的輸出取自另開的乾淨記事本與全新設定檔的 Chrome。前三張是把真實輸出排成終端機樣式,改動處見各圖下方小字。系統匣那張取自真實桌面,名稱已手動遮蔽、其餘項目已移除。Chrome 對照圖的下半(表格的右欄)是較早一次測試的數字。
- 使用者目錄下的
.agent-desktop資料夾(~/.agent-desktop/)存著 snapshot 的 ref 對照表,裡面也有桌面內容。我們測完是 1.1MB,不用時可以整個刪掉。 - 讓 agent 讀某個視窗之前,先想一下那個視窗裡有沒有你不想交給模型的東西。指定
--window-id比讓它自己掃整個桌面安全。
還有一件事不是隱私,是安全。snapshot 讀回來的是不受信任的內容,網頁或訊息裡的文字可能夾著寫給 agent 的指令(prompt injection),而這個 agent 手上有 click 和 set-value。所以不要把 Bash(agent-desktop:*) 整條放進 Claude Code 的 allow 清單,會動作的指令留著逐次確認。
剛開始用 Claude Code 的話,可以從 Claude Code 實戰教學 看起。
常見問題
agent-desktop 和 agent-browser 差在哪,該用哪一個?
兩個都出自 Vercel Labs,做法相同:把畫面讀成結構化資料,給每個可操作的元素一個 ref,agent 對 ref 下指令。agent-browser 管網頁,agent-desktop 管桌面程式(Windows 走 UI Automation)。網頁裡的事用 agent-browser。記事本、系統匣、Electron 這類桌面程式用 agent-desktop。介面元素沒有名字的程式,兩個都幫不上忙,只能回到截圖加座標。
agent-desktop 操作時會搶走我正在用的視窗嗎?
在我們的 Windows 10(19045)上,唯讀指令 snapshot、find、get、is、screenshot 不會動到前景視窗和游標。click 與 set-value 不會移動游標,但會把目標視窗拉到最前面,你正在打的字會落到那個視窗。這和官方「預設 headless、不搶焦點」的說明不一致。截至 2026-11-18(最新版 1.3.1),上游 issue #567 仍未解決,修補 PR #613 還沒合併。
snapshot 的內容會被送到哪裡?
agent-desktop 本身沒有模型,它只把無障礙樹印成 JSON。但呼叫它的 agent 會把這份 JSON 讀進對話,所以畫面上的帳號、訊息原文、網頁全文都會交給你用的模型。另外它會在使用者目錄下的 .agent-desktop 資料夾留一份 snapshot 對照表,裡面同樣有桌面內容。輸出不要進公開的 log、commit 或聊天室。