Ultra Lab
Claude Code 教學Claude CodeAI AgentWindows實戰經驗

agent-browser 的桌面版:讓 Claude Code 操作 Windows 桌面程式(實測)

· · 25 分鐘閱讀
目錄
  1. 安裝:兩分鐘
  2. 三分鐘最小迴圈:記事本
  3. 「讀」比「點」更順手:從系統匣讀 VPN 狀態
  4. Chrome:先拿骨架,再鑽進去
  5. 誠實的邊界
  6. 什麼時候用哪一個
  7. 隱私提醒

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 的提示,不是安裝失敗。

agent-desktop status 的輸出:accessibility granted、platform windows、版本 1.2.0,supported_surfaces 含 system-tray-overflow(輸出已重排版與節錄)

圖說:圖下方英文小字的意思是,輸出重新縮排過,家目錄顯示成 %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 編號。視窗確實放大了,迴圈成立。

記事本最小迴圈:第一次 snapshot 的按鈕叫最大化,click 之後再 snapshot 變成還原。click 回傳 delivered_unverified 與 retry unsafe(輸出已重排版與節錄)

圖說:圖下方英文小字的意思是,標題列是用 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 客戶端那顆按鈕的名稱直接寫著連線狀態:

系統匣溢位區的 snapshot:VPN 客戶端的按鈕名稱含 Connected to 與流量數字,客戶端名稱與連線名稱已手動遮蔽,其餘 37 個項目已移除

agent 只要找名稱裡有沒有 Connected to 就知道答案。圖中紅底的兩處是我們手動換掉的,其餘 37 個系統匣項目也拿掉了,原因見後面的隱私提醒。

一個小坑:只待在系統匣、沒有視窗的程式不會出現在 list-apps,要用 --surface 這條路讀。

Chrome:先拿骨架,再鑽進去

瀏覽器視窗的樹很大。我們另開一個全新設定檔的 Chrome,只開 ultralab.tw/blog 一頁,量三種讀法的 JSON 大小:

測試用的 Chrome 視窗截圖:全新設定檔,只開 ultralab.tw/blog 一個分頁。圖的右側已裁掉,裁掉的部分是個人檔案圖示、網址列旁一個 Chrome 提示晶片與視窗按鈕

Chrome snapshot 大小對照:ultralab.tw/blog 骨架 18.8KB、互動元素 194.2KB、完整樹 808.3KB。另一個文字較多的頁面是 30KB、126KB、469KB

圖說:上半(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 讀進對話,交給模型。

三個習慣:

  1. 輸出導到不進版本控制的資料夾,不要貼進公開的 log、commit、issue 或聊天室。圖裡的輸出取自另開的乾淨記事本與全新設定檔的 Chrome。前三張是把真實輸出排成終端機樣式,改動處見各圖下方小字。系統匣那張取自真實桌面,名稱已手動遮蔽、其餘項目已移除。Chrome 對照圖的下半(表格的右欄)是較早一次測試的數字。
  2. 使用者目錄下的 .agent-desktop 資料夾(~/.agent-desktop/)存著 snapshot 的 ref 對照表,裡面也有桌面內容。我們測完是 1.1MB,不用時可以整個刪掉。
  3. 讓 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 或聊天室。

想自己動手試試?

UltraProbe 免費、免註冊,掃一次網站就知道 Google 與 AI 找不找得到你。

ULTRA LAB 週報

每週一,GitHub 前十+一件學到的事

每個工具都標清楚能不能商用、適合誰。卡關了可以到 Discord 問。

只用來寄週報,不會給別人;每封都能一鍵退訂。

加入 Discord