作者注：本文講解 agent-desktop 的安裝、授權、snapshot/click 閉環和 MCP 接入，並說明怎樣給“循環裏的大腦”配置模型與 Base URL。
讓編程 Agent 或自制 Agent 去點 Finder、填系統設置、操作一個原生客戶端，過去基本只能靠截圖、視覺模型和像素座標，鏈路長，也容易點錯。Vercel Labs 開源的 agent-desktop 換了一條路：它讀取操作系統的無障礙樹（Accessibility Tree），把桌面界面變成帶 ref 的 JSON，Agent 按 ref 執行點擊和輸入。這就是它說的“無截圖 computer use”。
這不是又一個自帶 AI 的桌面機器人。 開始之前先說清三件事：
- agent-desktop 不含模型：二進制裏沒有嵌入 LLM，沒有 GUI，也沒有交互提示。每條命令打印一個 JSON envelope 後就退出。
- 循環在調用方：觀察、行動、校驗（observe-act-verify）的循環由調用它的 Agent 負責，比如 Claude Code、OpenCode 或你自己寫的腳本。
- 不做網頁：網頁自動化交給同門項目 agent-browser，agent-desktop 只管原生桌面應用。
既然工具本身不帶模型，“大腦”就得由調用方 Agent 提供，這一步需要 API Key 和 Token。你可以把調用方 Agent 的 Base URL 指向 API易 apiyi.com，用一個 Key 調用 claude-opus-5-5、claude-sonnet-5-5 等模型。
核心價值：讀完本文，你能把 agent-desktop 裝好、授權、跑通 snapshot → click → 再 snapshot 的最小閉環，再通過 MCP 接進自己的 Agent，並配好模型側的 Base URL 和型號。
agent-desktop 核心要點
先用一張表看清 agent-desktop 的定位。下表信息來自官方 README、FAQ 和文檔站，觀察日期爲 2026-11-13。
| 要點 | 說明 | 對開發者的價值 |
|---|---|---|
| 數據來源 | 讀取 OS 無障礙樹：macOS 用 AX API，Windows 用 UI Automation，Linux 用 AT-SPI | 不依賴截圖和像素匹配，結構化程度高 |
| 輸出格式 | 每條命令輸出一個 JSON envelope 後退出，元素帶 ref | 方便 LLM 解析，也方便腳本做斷言 |
| 默認模式 | headless，走無障礙 API，不移動指針、不搶焦點 | 可以在後臺操作，不打斷用戶 |
| 是否含模型 | 不含，循環由調用方負責 | 模型自選，成本和效果由調用方控制 |
| 接入方式 | CLI、MCP（stdio）、skills、C 庫 FFI | 能接進 Claude Code、OpenCode、自制 Agent |
截至 2026-11-13，GitHub 倉庫 vercel-labs/agent-desktop 約 22,900 star，採用 Apache-2.0 協議，npm 包名就是 agent-desktop，當天仍有新提交。命令總數約 61 個名字、57 個可運行，分爲 Observe、Act on ref、Keyboard mouse、Apps windows、Notifications、Clipboard、Wait、Sessions、Sandboxes、System 等組。
agent-desktop 如何工作：無障礙樹與 ref
agent-desktop 的核心概念是 snapshot 和 ref。執行 snapshot 時，它會遍歷目標應用的無障礙樹，把按鈕、文本框、菜單項等元素輸出爲 JSON，每個元素分配一個 ref。完整 ref 的形式類似 @s8f3k2p9:e8：前半段是這次 snapshot 的標識，後半段是元素編號。
ref 只屬於產生它的那一次 snapshot。如果只傳裸的 @e8，會得到 INVALID_ARGS。界面變化後，舊 ref 可能失效，返回 STALE_REF 或 AMBIGUOUS_TARGET，這時需要重新 snapshot。這個設計逼着調用方每次行動後都重新觀察，也就是 observe-act-verify 中“校驗”這一步。
上圖中的“Agent 選 ref”這一步是模型在做決策。agent-desktop 負責把界面結構化地交出去，讀懂 JSON、決定點哪個元素，都是調用方模型的工作。
agent-desktop 與 agent-browser 如何分工
兩個項目同屬 Vercel Labs，文檔站也放在一起，但職責邊界很清楚：
| 對比項 | agent-desktop | agent-browser |
|---|---|---|
| 目標 | 原生桌面應用（Finder、系統設置、原生客戶端） | 網頁與瀏覽器頁面 |
| 觀察方式 | OS 無障礙樹 | 瀏覽器側頁面結構 |
| Chromium / Electron 應用 | 可通過 DevTools 端口交給 agent-browser | 適合接管這類應用的網頁內容 |
| 是否含模型 | 不含 | 同樣作爲工具供 Agent 調用 |
| 典型命令 | snapshot、click、clipboard-set |
面向頁面的導航與交互 |
一個比較實用的分工是：原生窗口、菜單欄、Dock、通知交給 agent-desktop；遇到網頁或 Electron 應用裏的 Web 內容，就通過 DevTools 端口切到 agent-browser。
agent-desktop 版本節點與事實來源
agent-desktop 迭代很快，幾個關鍵版本都帶來了行爲變化，部分屬於破壞性變更。下表按事實來源標註，“未知”表示官方資料暫未明確。
| 版本 / 日期 | 主要變化 | 來源 |
|---|---|---|
| 1.0.0（2026-10-27） | Linux 支持正式進入 1.0 | 官方 Changelog |
| 1.1.0（2026-11-02） | envelope 升級到 2.6；支持 macOS Dock 與 menu-bar-extras；身份證明相關破壞性變更 | 官方 Changelog |
| 1.2.0（2026-11-05） | 新增 MCP（agent-desktop mcp）；type / set-value / clipboard-set 支持 --stdin |
官方 Changelog |
| 1.3.0（2026-11-11） | 新增 agent-desktop sandbox 和 macOS sandbox provider；menu/menubar snapshot 不再帶 data.window（破壞性） |
官方 Changelog |
| Windows / Linux 沙箱 | 是否會提供對應 provider | 未知 |
agent-desktop 快速上手
下面按“安裝 → 授權 → 最小閉環 → MCP 接入”的順序走一遍。
第 1 步：安裝 agent-desktop
平臺要求：macOS 13+；Windows 10 1809+（x64 / ARM64）；Linux 爲 Ubuntu 24.04+（x86_64 / aarch64），X11 或 Wayland 都可以。安裝方式任選一種：
- npm（需要 Node 18+，包內帶各平臺原生二進制）：
npm install -g agent-desktop - Homebrew（macOS / Linux，已進入 homebrew-core）：
brew install agent-desktop - 原生歸檔：從 GitHub Releases 下載，helper 需要放在可執行文件旁邊
裝好後先運行 agent-desktop status，確認二進制和當前平臺環境正常。
第 2 步：agent-desktop 權限授權
macOS 上需要給終端或宿主進程開啓“輔助功能”權限，否則讀不到無障礙樹。官方提供了引導命令：
agent-desktop permissions --guide：按提示在系統設置中完成輔助功能授權- 授權完成後再運行一次
agent-desktop status複覈
需要注意，授權對象是“運行 agent-desktop 的那個進程”。如果你通過 Claude Code、某個 IDE 或 MCP 客戶端間接調用它，可能需要給對應的宿主應用授權。
第 3 步：跑通 snapshot → click → snapshot 最小閉環
以 Finder 爲例，三條命令就能構成一次完整的觀察-行動-校驗：
agent-desktop snapshot --app Finder -i：獲取 Finder 的無障礙樹，-i用於聚焦可交互元素，輸出 JSON 中帶有@s8f3k2p9:e8這類 refagent-desktop click @s8f3k2p9:e8：點擊上一次 snapshot 中的目標元素，必須寫完整 refagent-desktop snapshot --app Finder -i：再次觀察，校驗界面是否按預期變化
如果第 2 步報 STALE_REF 或 AMBIGUOUS_TARGET，說明界面已經變化，回到第 1 步重新 snapshot 即可。遇到需要真實指針或鍵盤事件的應用，可以加全局參數 --headed，切到物理輸入模式。
對於元素很多的界面，一次性完整 snapshot 會很長，也浪費模型 Token。可以分兩層獲取：
agent-desktop snapshot --skeleton --app Finder：先拿骨架，看清大致區域agent-desktop snapshot --app Finder --root @<骨架中的 ref>：再從某個子樹下鑽
這個技巧能明顯縮短送進模型的上下文。對調用方來說，上下文越短，按 Token 計費的成本越低。
第 4 步：通過 MCP 和 skills 接入 Agent
從 1.2.0 開始，agent-desktop 內置 MCP 服務，走 stdio，暴露 desktop_snapshot、desktop_click 等工具。不同客戶端的配置格式略有差異，下面是示意：
- 啓動命令：
agent-desktop mcp - 通用 JSON 配置示意：
{"mcpServers": {"agent-desktop": {"command": "agent-desktop", "args": ["mcp"]}}} - Claude Code 示意：
claude mcp add agent-desktop -- agent-desktop mcp
如果你的 Agent 支持 skills，還可以直接加載官方的使用說明，讓模型知道該怎麼調用：
agent-desktop skills get desktop、agent-desktop skills get platform：輸出技能說明npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop：通過 skills.sh 安裝
需要同進程調用的場景，也可以使用 C 庫 libagent_desktop_ffi。
可選：1.3.0 的 agent-desktop sandbox
1.3.0 新增了 agent-desktop sandbox 子命令和 macOS sandbox provider，可以在本機簽名的 macOS 虛擬機裏運行自動化，把 Agent 的操作和你的真實桌面隔離開。這不是必需步驟，最小閉環不依賴它。如果你擔心 Agent 誤操作真實文件，或者想跑大量探索性任務，可以優先考慮。
🚀 快速開始：MCP 配好後，調用方 Agent 還需要一個能用的模型。官方推薦的做法是在 API易 apiyi.com 控制檯創建令牌，再把 Agent 的 Base URL 指過去，一個 Key 就能在 Claude、GPT、Gemini 等模型之間切換對比。
給 agent-desktop 循環接上模型“大腦”
agent-desktop 只負責“眼睛和手”，決定點哪個 ref、判斷任務是否完成的“大腦”在調用方。這個環節有兩個關鍵配置：Base URL 和模型型號。
Base URL：帶不帶 /v1 要分清
調用方 Agent 通常走兩類協議，Base URL 寫法不同，寫錯是 404 最常見的原因：
- OpenAI 兼容協議（大多數自制腳本、OpenCode 的 OpenAI 兼容 provider）：
https://api.apiyi.com/v1，帶/v1 - Anthropic 原生協議（Claude Code 等直接走 messages 接口的客戶端）：
https://api.apiyi.com，不帶/v1
以 Claude Code 爲例，可以用環境變量示意配置：
export ANTHROPIC_BASE_URL=https://api.apiyi.comexport ANTHROPIC_AUTH_TOKEN=你的令牌
自制 Python 或 Node 腳本使用 OpenAI SDK 時，把 base_url 設爲 https://api.apiyi.com/v1，model 填 claude-opus-5-5 即可。令牌在 api.apiyi.com/token 創建，詳細配置可以參考 docs.apiyi.com/faq/base-url-config.md。
自制 Agent 的循環怎麼寫
不想依賴現成 Agent 時，自己寫一個循環也不復雜。核心步驟如下：
- 運行
agent-desktop snapshot --app 目標應用 -i，讀取 stdout 中的 JSON envelope - 把任務目標和 snapshot JSON 一起發給模型，要求它只返回下一步動作和完整 ref
- 執行模型給出的命令，例如
agent-desktop click @sxxxx:eN - 再次 snapshot，把新結果交給模型判斷是否完成；收到
STALE_REF時直接重新觀察 - 設置最大步數和人工確認點，避免死循環或越權操作
這裏的第 2 步和第 4 步都會消耗 Token。前面提到的 --skeleton 加 --root 下鑽方式，在這裏會直接影響成本。
選型：claude-opus-5-5 與 claude-sonnet-5-5
兩款 Claude 型號都已在 API易 型號總表上架，同時支持 chat 和 messages 端點。下表價格數據日期爲 2026-11-13，單位爲每 1M Tokens，型號與價格以平臺型號列表爲準。
| 型號 | 輸入 | 輸出 | 緩存讀 | 適合的 agent-desktop 場景 | 可用平臺 |
|---|---|---|---|---|---|
claude-opus-5-5 |
$4 | $20 | $0.2 | 多步驟、界面複雜、需要較強規劃的任務 | API易 apiyi.com |
claude-sonnet-5-5 |
$2 | $10 | $0.1 | 步驟明確、重複性較強的日常操作 | API易 apiyi.com |
一個可行的思路是先用 claude-opus-5-5 跑通流程，確定提示詞和步驟後，再評估能否把穩定環節切到 claude-sonnet-5-5。snapshot JSON 中會有大量重複的系統提示和工具說明，緩存讀價格明顯低於輸入價格，所以開啓提示緩存對長循環比較友好。最新價目請以 docs.apiyi.com/models 爲準。
agent-desktop 排錯：權限問題還是模型問題
agent-desktop 和模型屬於兩條獨立鏈路，報錯時先判斷是哪一側出了問題，可以少走很多彎路：
| 現象 | 所在鏈路 | 可能原因 | 處理方式 |
|---|---|---|---|
| snapshot 爲空或讀不到應用 | 工具側 | 未授予輔助功能權限，或應用本身沒有暴露無障礙樹 | 運行 agent-desktop permissions --guide，檢查宿主進程授權 |
INVALID_ARGS |
工具側 | 只寫了裸 ref，例如 @e8 |
使用完整 ref，例如 @s8f3k2p9:e8 |
STALE_REF / AMBIGUOUS_TARGET |
工具側 | 界面已變化，ref 失效 | 重新 snapshot |
| 模型請求 401 | 模型側 | 令牌錯誤、過期或環境變量沒有生效 | 到 api.apiyi.com/token 覈對令牌並重新導出 |
| 模型請求 404 | 模型側 | Base URL 的 /v1 寫錯，或型號名拼寫錯誤 |
OpenAI 兼容帶 /v1，Anthropic 原生不帶；型號對照總表 |
簡單判斷方法：只要 agent-desktop 命令能在終端裏單獨跑出 JSON，工具側就沒有問題，剩下的報錯基本都在模型側。模型側的 401/404 可以對照 API易 apiyi.com 文檔中心的 Base URL 配置說明逐項檢查。
agent-desktop 權限與隱私風險
這一節討論的是桌面自動化本身的風險，和賬號無關，但開始使用前值得認真看一遍。
輔助功能授權的分量。 在 macOS 上開啓輔助功能，意味着被授權的進程可以讀取並操作其他應用的界面。授權給終端或某個 Agent 宿主後，這個進程裏運行的任何程序都可能獲得同等能力。建議只給必要的宿主授權，用完可以在系統設置中關閉。
snapshot、剪貼板和截圖都可能包含隱私。 官方明確提示，snapshot、剪貼板內容、截圖、通知和 debug HTML 都可能帶有桌面上的敏感信息，比如聊天內容、郵件標題、文件名和密碼管理器界面。這些數據會被調用方送進模型，所以不要公開上傳調試日誌，也不要在 issue 中直接貼完整 snapshot。
可選 helper 會聯網。 原生 CLI 本身不要求遠端模型服務，但如果啓用了可選的 JEV helper，它會把目標與屏幕描述發送給你配置的模型供應商。是否開啓、發給誰，都要自己心裏有數。
操作後果由使用者承擔。 Agent 可能點錯按鈕、刪錯文件、發出不該發的消息。可以採用這些做法降低風險：在 1.3.0 的 sandbox 中試跑，限制 --app 的範圍，給刪除、發送、支付這類高風險操作加人工確認。另外，無障礙樹讀不到的應用對 agent-desktop 不可見，這是能力邊界，不要指望它一定能操作所有軟件。
第三方 Agent 接網關是另一類風險。 把 Claude Code、OpenCode 等第三方 Agent 接到任何 API 網關時，都要注意令牌保管、額度上限和日誌中是否會寫入敏感內容。這和桌面自動化風險分開評估。建議爲 Agent 單獨建一個令牌並設置額度，出問題時可以單獨作廢。
常見問題 FAQ
Q1：什麼是 agent-desktop？
agent-desktop 是 Vercel Labs 開源的 computer use CLI。它通過 OS 無障礙樹，讓 AI Agent 看見並操作 macOS、Windows、Linux 上的桌面應用，不依賴截圖或像素匹配。它是工具而不是 Agent，本身不含模型。
Q2：agent-desktop 和截圖式 computer use 有什麼區別？
截圖式方案依賴視覺模型理解像素再給出座標，鏈路長，也容易受分辨率影響。agent-desktop 直接輸出結構化 JSON 和 ref，模型按 ref 操作，默認 headless 運行，不搶指針和焦點。代價是隻能看到暴露了無障礙信息的應用。
Q3：agent-desktop 目前是什麼版本？
截至 2026-11-13，可見的最新版本節點是 1.3.0（2026-11-11），新增 sandbox。MCP 從 1.2.0（2026-11-05）開始提供，Linux 在 1.0.0（2026-10-27）正式進入 1.0。版本更新較快，請以 GitHub Releases 爲準。
Q4：agent-desktop 適合哪些場景？
– **原生應用測試**：自動點擊設置面板、校驗界面狀態
– **編程 Agent 擴展**：讓 Claude Code 在寫完代碼後打開桌面應用驗證效果
– **重複性桌面操作**：整理 Finder 文件、讀取通知、讀寫剪貼板
網頁相關任務請交給 agent-browser。
Q5：調用 agent-desktop 的 Agent 如何快速接上模型？
1. 在 API易 apiyi.com 註冊並在令牌頁創建 API Key，新用戶有免費測試額度
2. OpenAI 兼容客戶端把 Base URL 設爲 `https://api.apiyi.com/v1`，Anthropic 原生客戶端設爲 `https://api.apiyi.com`
3. 模型選擇 `claude-opus-5-5` 或 `claude-sonnet-5-5`，再運行本文的 snapshot 閉環
Q6：MCP 配好了，Agent 卻報 401 或 404，是 agent-desktop 的問題嗎？
通常不是。agent-desktop 不連接模型服務，401 一般是令牌問題，404 多半是 `/v1` 寫錯或型號名拼寫錯誤。先在終端單獨運行 `agent-desktop snapshot` 確認工具正常，再對照 API易 apiyi.com 的 Base URL 配置文檔排查模型側。
Q7：agent-desktop 有哪些已知限制？
– 無障礙樹讀不到的應用對它不可見
– 部分版本帶有破壞性變更（如 1.1.0、1.3.0），升級前請閱讀 Changelog
– sandbox provider 目前面向 macOS，其他平臺是否跟進暫時未知
– 不做網頁自動化，需要配合 agent-browser
agent-desktop 核心要點 Key Takeaways
- 工具不含模型：agent-desktop 只輸出 JSON envelope，循環與決策在調用方
- 無截圖 computer use：基於 AX、UI Automation、AT-SPI 無障礙樹，按 ref 操作
- ref 必須完整：形如
@s8f3k2p9:e8，界面變化後需要重新 snapshot - 三平臺可用：macOS 13+、Windows 10 1809+、Ubuntu 24.04+
- MCP 一行接入：1.2.0 起
agent-desktop mcp走 stdio - 網頁交給 agent-browser：Electron 應用可以通過 DevTools 端口移交
- 大腦接入：調用方 Base URL 指向 API易 apiyi.com，選
claude-opus-5-5
總結
agent-desktop 的核心要點：
- 定位清楚：它是桌面應用的“眼睛和手”，不含模型，不做網頁
- 閉環簡單：安裝 →
permissions --guide→ snapshot → click → 再 snapshot，配合--skeleton控制上下文長度 - 接入靈活：CLI、MCP、skills、FFI 都可以，1.3.0 的 sandbox 適合做隔離試跑
- 風險要管住：輔助功能授權和 snapshot 中的隱私內容，需要按桌面自動化的標準來管理
工具側跑通之後，剩下的工作就是給循環配一個合適的大腦。推薦通過 API易 apiyi.com 創建令牌，把 Claude Code、OpenCode 或自制腳本的 Base URL 指過去，先用 claude-opus-5-5 驗證流程，再按任務複雜度評估是否切換到 claude-sonnet-5-5。
📚 參考資料
- GitHub – agent-desktop：官方開源倉庫，含 README、FAQ、Changelog
- 鏈接：
github.com/vercel-labs/agent-desktop -
說明： 版本變化、命令列表和隱私提示以此爲準
-
agent-desktop 官方文檔：概念與快速開始
- 鏈接：
agent-browser.dev/desktop、agent-browser.dev/desktop/quick-start -
說明： 安裝、授權和最小閉環示例
-
npm – agent-desktop：npm 包頁面
- 鏈接：
npmjs.com/package/agent-desktop -
說明： 查看當前發佈版本
-
Vercel – What is computer use：computer use 概念介紹
- 鏈接：
vercel.com/i/what-is-computer-use -
說明： 理解無障礙樹方案與截圖方案的差異
-
API易 文檔中心：型號總表、Base URL 配置、Claude 能力說明
- 鏈接：
docs.apiyi.com/models.md、docs.apiyi.com/faq/base-url-config.md、docs.apiyi.com/api-capabilities/claude.md - 說明： 型號與價格以平臺型號列表爲準
作者：APIYI 技術團隊
技術交流：歡迎在 API易 apiyi.com 網站首頁聯繫我們，更多資料可訪問 docs.apiyi.com 文檔中心
