本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。英文原文

WebMCP 瀏覽器橋接

狀態：實驗性範圍：公開、現行狀態上次審閱：2026-10-10 負責人：AX Code 維護者

WebMCP 橋接讓代理程式在隔離的 Chrome 視窗中開啟頁面、讀取內容，並（可選擇）對頁面執行動作。此功能屬於實驗性質，預設關閉，而且需要 Chrome 150 或更新的版本。

WebMCP 是一項提案中的網頁標準。頁面可以註冊結構化工具，也就是名稱、描述與輸入結構描述，讓代理程式直接呼叫這些動作。AX Code 會取用頁面註冊的工具，也可以自行讀取頁面並對頁面執行動作。

Codex 與 ChatGPT Work 把內建瀏覽器對同一標準的作法記載為網站工具。該頁說明他們的桌面應用程式如何開啟 WebMCP、訪客如何查看網站提供的工具，以及網站作者如何註冊工具。以下步驟是 AX Code 的作法。

用 Chrome 啟用

安裝 Google Chrome 150 或更新的版本。相同主要版本的 Chromium 也可以。AX Code 會以全新設定檔開啟自己的 Chrome 視窗，不會更動已經開啟的 Chrome 視窗。
用 ax-code 啟動終端機介面。
點選側邊欄頁尾的 WebMCP 標籤、首頁提示頁尾的同一個標籤，或執行 /webmcp。這次點選或指令就是同意。在此之前不會啟動任何瀏覽器。AX Code 會先在不啟動瀏覽器的情況下，檢查常用位置是否已安裝 Chrome 150 或更新版本；若沒有就提出警告。這項檢查只是建議，絕不會擋住這次嘗試。你的選擇會存進使用者設定，因此下次啟動時橋接會自行恢復，不必再點一次。
AX Code 會開啟該隔離視窗，並啟用 WebMCP 功能（--enable-features=WebMCP）。在你親手登入之前，視窗裡沒有任何登入狀態。
請代理程式開啟頁面。依產品預設，導覽不受限制。已設定或受管理的來源清單會把範圍縮小。
再點一次標籤即可關閉橋接。這會結束暫時的工作階段授予；已儲存的核准會保留，直到你在 MCP 設定中撤銷。

互動層級開啟時，標籤會顯示 [act]。產品預設包含這個層級。若要關閉，把 interact 在該項目的 webmcp 設定檔中設為 false。你較早儲存的項目會保留當時的層級。

ax-code mcp webmcp 會印出一段設定片段。它不會安裝套件、連接伺服器，也不會寫入檔案。加上 --interact 可印出已開啟互動層級的項目，或用 --executable-path /absolute/path/to/chrome 指定特定的 Chrome 150 以上二進位檔。設定該路徑後，AX Code 會在啟動前檢查二進位檔的主要版本。

在你自己開啟的 Chrome 視窗裡使用工具

上面的隔離視窗已經啟用 WebMCP。若要在建置網站時所用的 Chrome 設定檔裡試用頁面工具，請依照 Chrome 的 WebMCP 指南：

開啟 chrome://flags/#enable-webmcp-testing。
把旗標設為 已啟用。
重新啟動 Chrome。

該旗標套用在你開啟的那個 Chrome 設定檔。AX Code 橋接仍然從標籤啟動。

提示列提示

橋接關閉時，若提示提到 URL 或本機伺服器（例如 localhost:3000），會顯示一行指向標籤與 /webmcp 的說明。每個工作階段最多出現一次，累計最多三次，而且絕不會改變送給代理程式的內容。

代理程式可以做什麼

層級	工具	核准
頁面	列出、開啟、導覽、關閉頁面；執行頁面透過 WebMCP 註冊的工具	每次呼叫都要核准，除非已儲存支援的範圍
讀取	頁面快照、螢幕截圖、主控台、請求中繼資料	每個來源在每個工作階段授予一次，或已儲存的讀取核准
互動	點選、游標暫留、等待、填入、填寫表單、按鍵、回應對話框	見下方

頁面內容不受信任：頁面可能試圖引導代理程式。輸出會標明來源，並且限制大小。

儲存核准

符合條件的提示會以紅色背景提供 加入 WebMCP 允許清單。選取它、檢視範圍，然後選擇 新增並允許。已儲存的核准套用在這台機器上的這個專案，瀏覽器重新連線與 AX Code 重新啟動之後仍然有效。

頁面清單會核准 AX Code 瀏覽器的 list_pages，包含所有已開啟來源的標題與 URL。它不核准頁面內容。
導覽核准開啟或前往一個精確來源。
讀取核准在一個精確來源上取得快照、螢幕截圖、主控台與網路中繼資料。其他來源與連接埠需要各自的核准。
關閉核准關閉目前位於一個精確來源上的任何頁面，包含有未儲存工作的頁面。這是分開的選擇：導覽與讀取核准不會一併授予。關閉前會再次檢查目標來源。

第一次讀取核准之後，AX Code 會在同一呼叫中再次檢查頁面，然後繼續該次讀取。頁面或橋接若有變更，呼叫會停止，並要求重新讀取。它不會重做失敗的瀏覽器操作。

導覽限制與管理員原則仍然適用。儲存核准不會編輯 allowedOrigins。輸入文字、後果重大的點選、對話框與頁面註冊的工具，仍沿用既有核准。允許一次 仍然是暫時的；倒數絕不會存成持久核准。

選取 WebMCP 標籤旁邊的 WebMCP 允許清單 連結（工作階段側邊欄頁尾與首頁提示頁尾），執行 /webmcp-allowlist，或開啟 /mcp，選取橋接，然後按 Ctrl+G。在項目上按兩下（或按兩次 Enter）即可撤銷；第一次會標記該列，幾秒內的第二次才確認，因此單次點選絕不會撤銷。清除列會以相同方式撤銷此專案中該橋接的全部已儲存核准。清單較長時可以捲動。按 Escape，或點選面板外側，即可關閉。

搜尋框也可以新增核准。輸入精確的 https:// 來源（或 http://localhost），然後選取導覽、讀取或關閉列來儲存；在儲存之前會提供頁面清單列。橋接必須已經連線：明確核准會繫結到執行中的橋接身分，並在每次呼叫時檢查，與從提示儲存的核准相同，因此受管理的來源清單、讀取層級開關與管理員原則仍然適用。關閉 WebMCP 標籤會中斷瀏覽器連線，並保留已儲存的選擇。

本機存放位置預設是 ~/.local/share/ax-code/webmcp-approvals.json（XDG 資料目錄覆寫仍然適用）。核准繫結於橋接身分；變更啟動方式或瀏覽器設定檔之後，需要重新核准。

頁面開啟或變更之後，仍可能出現導覽錯誤。若能辨識，錯誤會回報逾時、網路或找不到頁面的類別，而不會回顯原始橋接錯誤文字。決定是否再次導覽之前，請先查看 list_pages。導覽錯誤不會移除已儲存的核准。

互動層級

游標暫留與一般點選，在每個來源的一次授予下執行，可做 20 個動作，之後會再次出現相同提示。

輸入文字、按鍵、對話框、連結、按兩下，以及名稱聽起來後果重大的點選（送出、付款、刪除、授權等），每次都會詢問，並顯示目標與完整的值。
名稱看起來像憑證的欄位會被標示並遮罩。形狀像 API 金鑰或私密金鑰的值會被拒絕：請自行輸入憑證。
動作需要同一頁面的新快照；頁面已移動或元素未知時會被拒絕。同一回合內拒絕三次之後，就不再繼續動作。

依名稱做的檢查是啟發式判斷，不是保證。提示才是控制點，請閱讀它。

使用既有頁面

請 AX Code 檢查頁面的能力、開發它的原生工具，或診斷特定行為。browser_workflow 工具會把這些工作歸在一起，一般觀察不需要你先啟動測試伺服器。請先啟用橋接並指出要看的頁面；這些動作都不會開啟頁面、登入、變更瀏覽器設定檔，或排程以後的工作。

例如：「檢查我本機應用程式上的工具，並顯示它們對應哪些應用程式函式」，或「在我重現空白結果之前先擷取這個頁面，然後比較錯誤，並指出可能的原始碼檔案。」

檢查原生工具與其原始碼

呼叫 status，並帶入 server、pageId 與精確的 origin，以查看實際准入的工具，以及原生與快照是否可用。空白清單不能證明無法存取的頁框沒有工具。既有連接器可能更適合不需要頁面上下文的工作。

{
  "action": "inventory",
  "server": "webmcp",
  "pageId": 1,
  "origin": "http://localhost:3000",
  "sourceFiles": ["src/tools.ts", "public/search.html"]
}

保留傳回的 inventoryId。之後的清查呼叫把它當作 baselineId 傳入，就能看到新增或移除的工具，以及變更的結構描述欄位。檔案會明確檢查權限、限制在儲存庫內，並且有大小上限。靜態的命令式註冊，以及加上引號的 HTML 表單屬性，會產生原始碼候選；計算得出的名稱、重複定義與不支援的範本，仍會是未解析或含糊的。名稱與結構描述相符可以佐證候選，但不能證明瀏覽器載入的就是該原始碼修訂。

產生應用程式整合

使用 author 傳回可供審閱的整合程式碼：

{
  "action": "author",
  "name": "find_products",
  "description": "Find products matching a query in the current catalog.",
  "module": "./src/catalog.js",
  "exportName": "findProducts",
  "schema": {
    "type": "object",
    "properties": { "query": { "type": "string" } },
    "required": ["query"]
  },
  "format": "imperative",
  "effect": "read"
}

具名函式必須是直接匯出。產生的註冊會接受 AbortSignal，供元件或路由清理使用。只有在應用程式函式接受並遵守第二個引數時才設定 acceptsSignal: true，該引數就是 {signal}。format: "declarative" 會傳回表單，以及供人工送出的模組繫結；請把它的 webmcp-result 事件接到應用程式介面。支援基本型別欄位；不支援的結構描述限制會被拒絕，而不是悄悄捨棄。套用任一範本之前，請審閱應用程式的驗證、授權與實際效果。即使表單要求人工送出，編輯欄位仍可能觸發自動儲存。

分開檢查執行與模型選擇

既有的 contract 步驟會核對固定輸入與預期結果。在路由或角色變更之後加上 {"action":"tool_presence","name":"admin_reset","present":false}，以檢查不可用的操作是否已取消註冊。present: true 也可以釘選 descriptorHash。這些是生命週期檢查點，不是事件追蹤。匯出的迴歸測試包含相同檢查。

另外用一次選擇評估，來看模型是否選對工具與引數：

{
  "action": "selection_eval",
  "inventoryId": "<returned inventory UUID>",
  "cases": [
    { "task": "Find AX products", "expected": { "name": "find_products", "arguments": { "query": "AX" } } },
    { "task": "Delete every product", "expected": { "name": null, "arguments": {} } }
  ],
  "repeats": 2
}

選取的 API 模型只收到工作與擷取到的目錄，沒有執行工具，也沒有預期答案。呼叫會先核准，並限制為 12 個案例、重複三次，以及兩分鐘的評估期限。報告會記錄模型身分、套件雜湊、分開計算的精確選擇與引數次數、聯合正確性，以及未知結果。失敗仍留在分母裡。CLI 模型不能用於這項評估，因為它們可以執行自己的工具。選擇分數不能證明工具正確，也不能取得 Arena 資格。

診斷動作前後

以相同的頁面目標呼叫 observe，可加上選擇性的 sourceFiles，以及使用既有角色、名稱與 count、value、checked、disabled 結構描述的明確 assertions。透過已核准的工具或手動，把要求的動作做一次。然後呼叫 {"action":"diagnose","observationId":"<returned UUID>"}。結果會比較斷言結果、快照雜湊、有上限的主控台與請求中繼資料差異、語意清查變更，以及原始碼候選。相關性是供調查的證據，不是已經證明的根因。沒有斷言時，狀態是 observed，不是 pass。

基準只保留在目前的執行環境工作階段裡，30 分鐘後過期，每個工作階段最多 16 筆。連線或頁面位置一變，就不能再重用。釘選的橋接無法辨認相同 URL 的重新載入，因此這些比較仍然只是建議。只保留頁面位置與快照的雜湊；有上限的診斷文字與工具描述元是不受信任的證據。

若是可以重現的 localhost 問題，promote 會取用觀察 ID，以及一份明確、一般形式的 manifest，其中包含本機測試伺服器指令與步驟。它會凍結一個新的受控情境。觀察結果絕不會複製進驗收：編輯之前先跑一次失敗的對照，再透過既有工作流程，讓修復後的執行取得資格。

重複每天的觀察工作

隨需配方會檢查既有頁面，不進行導覽，也不排程：

{
  "action": "recipe",
  "server": "webmcp",
  "pageId": 1,
  "definition": {
    "version": 1,
    "name": "Preview health",
    "origin": "http://localhost:3000",
    "assertions": [{ "locator": { "role": "status", "name": "Ready" }, "property": "count", "equals": 1 }]
  }
}

預設只做快照。選擇性的 queries 包含精確工具 name、descriptorHash、物件 input、resultPath 與 equals。它們會在既有的逐次核准下呼叫真正的應用程式工具；唯讀提示不能證明效果。結果會明確區分快照觀察，以及效果尚未驗證的應用程式呼叫，並在查詢之後重新檢查快照。請儲存審過的定義，不要儲存擷取到的內容或憑證。定義不帶權限，也絕不會變成 Arena 回執。通過只表示宣告的觀察相符；缺少的資料不能算通過檢查。

手動註冊工具

請代理程式新增一個會重用頁面既有邏輯的工具，或從頁面的 JavaScript 註冊一個。Chrome 指南說明命令式 API 與宣告式表單 API。最小的唯讀工具如下：

if (typeof document.modelContext?.registerTool === "function") {
  await document.modelContext.registerTool({
    name: "read_heading",
    description: "Read the main heading of the current page.",
    inputSchema: {
      type: "object",
      properties: {},
      additionalProperties: false,
    },
    annotations: { readOnlyHint: true },
    execute: async () => ({
      heading: document.querySelector("h1")?.textContent ?? "",
    }),
  })
}

相容的代理程式之後就能在該頁面發現 read_heading。OpenAI 的網站工具頁面從 Codex 與 ChatGPT Work 的角度說明同一個概念，包括他們的內建瀏覽器如何列出網站提供的工具。

限制

沒有指令碼、上傳、下載、cookie、請求本文、座標或拖曳。管理員可以用受管理的 webmcp 要求（allow、allowRead、allowInteract、allowedOrigins）停用橋接或任一個層級；專案與使用者設定不能把限制放寬。

用 ax-code mcp add 新增的伺服器是另一條信任路徑。請見 MCP 整合。

用五個步驟除錯 localhost 頁面

頁面顯示不正確、控制項沒有反應，或請求失敗時：

前往頁面並取得快照。無障礙樹就是結構基準。導覽與讀取使用既有核准。
在既有的互動核准下，把失敗的動作做一次。
讀取差異：動作前後的主控台錯誤與網路中繼資料（方法、URL、狀態、類型；請求與回應本文不在範圍內）。若是非同步狀態，請等待；絕不要重複觸發該動作。
判定為 PASS、FAIL 或 BLOCKED，並寫出缺少的能力。工具回覆已收到，並不是應用程式成功的證明。
若 localhost 的失敗可以寫成結構化斷言，就把它凍結成 browser_workflow 情境（見下方），記錄失敗的對照，並在修復之後把同一個雜湊跑兩次。

把證據附到錯誤報告

透過凍結情境調查的 localhost 失敗，可以用證據包讓報告便於審閱：情境名稱與雜湊、失敗的斷言結果（不含擷取到的頁面內容）、來自 browser_workflow inspect 的回執 ID、快照雜湊、有上限的主控台錯誤與網路中繼資料差異、標成 explicit、local_map 或 unresolved 的原始碼連結，以及來源。只放入執行環境有上限、且已遮罩的輸出。絕不要放入請求或回應本文、標頭、cookie、儲存體、頁面內容，或形狀像憑證的值。回執 ID 與複製的回執資料只是參考；具權威的回執狀態仍由執行環境持有。

重現並驗證開發變更

browser_workflow 工具會在你編輯網頁應用程式之前凍結驗收步驟，透過已連線的 WebMCP 橋接執行，並記錄結構化斷言。請先啟用橋接。第一個支援的環境是 127.0.0.1 上可拋棄的 HTTP 伺服器；每次執行會配置不同的連接埠與暫存資料目錄，以及全新的隔離瀏覽器環境。持久的瀏覽器設定檔會被拒絕。空的環境會由上游橋接保留到中斷連線為止；同一條連線跑滿 32 次之後，請先重新連接橋接再繼續。工作流程絕不會重用它們的 cookie 或儲存體。

請代理程式用 action: "freeze" 凍結情境。例如，由專案擁有、並接受連接埠引數的 test/browser-server.mjs 可以這樣用：

{
  "action": "freeze",
  "manifest": {
    "version": 1,
    "name": "Search returns a matching result",
    "server": "node test/browser-server.mjs {port}",
    "path": "/",
    "setup": [],
    "reset": [],
    "cleanup": [],
    "steps": [
      { "action": "fill", "locator": { "role": "textbox", "name": "Search" }, "value": "example" },
      {
        "action": "assert",
        "assertion": {
          "locator": { "role": "status", "name": "One result" },
          "property": "count",
          "equals": 1
        }
      }
    ]
  }
}

保留傳回的雜湊。用 {"action":"run","hash":"<hash>","server":"webmcp"} 執行（填入你已連線橋接的名稱）。重現失敗、做出變更，然後把同一個雜湊跑兩次。每次執行都會啟動宣告的伺服器、開啟自己的頁面、檢查步驟、關閉頁面，並停止自己的伺服器。生命週期指令在儲存庫根目錄執行，並走一般的殼層權限。{port} 會展開成配置到的連接埠；{data} 會展開成已加引號的暫存目錄。設定、重設與清理指令必須在 15 秒內結束；就緒期限是 15 秒，瀏覽器執行期限是 120 秒。瀏覽器動作沿用既有權限與互動預算。

支援的步驟是點選、游標暫留、填入、結構化斷言，以及頁面工具契約檢查。定位器使用精確的角色與無障礙名稱。相符項目是零個或多個時，會以 unknown 停止；沒有猜測的 UID，也沒有 CSS 或指令碼後援。斷言比較數量、值、勾選或停用狀態。沒有出現的狀態屬性就是未知。若是非同步繪製，把 timeoutMs（0 到 10000，預設 0）加到 assert 步驟。執行器會輪詢新的結構化快照，直到斷言相符或期限到期；它絕不會重複前面的點選或填入。逾時會跟情境一起凍結，並保留在匯出的測試裡。情境上限是 32 個步驟與 32 KiB。

inspect 傳回凍結的資訊清單與執行環境回執。回執把情境繫結到儲存庫修訂與內容、操作結果、快照雜湊，以及有上限的主控台與網路中繼資料。原始碼有變、操作被拒、證據缺失、逾時，或清理未完成，都不能通過。這些結果只驗證宣告的斷言；它們不能證明應用程式的每一項行為。凍結狀態與具權威的回執放在目前的執行環境工作階段。重新啟動之後，請再凍結並重新取得資格；複製出來的 JSON 回執不會被當成執行環境的權威。

匯出迴歸測試

{"action":"export","hash":"<hash>"} 會傳回使用 playwright-core 的獨立 Node 模組。把傳回的程式碼存成專案測試，並用指向 Chrome 的 AX_TEST_WEBMCP_CHROME 執行。它會啟動相同的測試夾具，使用全新的瀏覽器環境、穩定的角色與名稱定位器，以及凍結的斷言。在說它已驗證之前，請實際跑過匯出的測試。匯出的測試是獨立的迴歸成品；其輸出不是 Arena 回執。頁面工具契約步驟使用 Chrome 原生的 WebMCP 協定，帶有精確的描述元雜湊與預期輸出，不會執行任意頁面指令碼。Chrome 必須支援該實驗性協定，契約匯出才能使用。

開發頁面工具契約並調查失敗

頁面開著時，{"action":"contracts","server":"webmcp","pageId":1} 會傳回已註冊的描述元與精確的描述元雜湊。凍結一個 contract 步驟，其中包含 name、descriptorHash、input、resultPath 與 equals。雜湊一變，檢查就失敗。對負向輸入設定 expectError: true：只有已確認的頁面工具執行錯誤才算滿足；已取消的呼叫、權限拒絕，以及沒有完成，都是未知。變更之後再加斷言，同時檢查結果頁面狀態與傳回值。

template 動作接受 name、相對的應用程式 module、明確的 exportName，以及 schema。它會確認本機匯出存在，並傳回註冊骨架。啟用之前，請對照應用程式的輸入驗證、授權與商業邏輯審閱；這個工具不能只憑匯出的函式名稱建立那些保證。

選擇性的 sources 清單會列出儲存庫內的檔案，帶有從 1 起算的 line、從 0 起算的 column，以及選擇性的本機 map 檔案。失敗的執行會傳回有上限的診斷，以及標成 explicit、local_map 或 unresolved 的原始碼連結。對應只是建議，絕不是根因的證明，也不是斷言通過的證明。遠端對應、儲存庫以外的路徑，以及超過 1 MiB 的檔案，都不會讀取。瀏覽器的網路證據仍然只是中繼資料。

在 implement Arena 中要求瀏覽器證據

提供 browserScenario: "<hash>"，並帶上 mode: "implement"。開始 Arena 之前，先凍結情境，並在目前乾淨的基底上記錄一次真正失敗的斷言。每個候選都會在自己的隔離工作樹裡收到該凍結契約，而且必須透過已連線的隔離橋接成功跑兩次。瀏覽器的啟用與權限仍受監督。缺少橋接存取、內容過期、結果未知或回執缺失，都會阻止提升，即使儲存庫檢查通過也一樣。一般的程式碼驗證與變更檢查仍會執行，而且沒有候選會自動合併。

有效率地選擇證據

原生 WebMCP 工具描述應用程式操作；Chrome DevTools MCP 提供瀏覽器檢查與自動化。明確的應用程式操作，優先使用頁面已註冊的工具，然後驗證它的結果與結果頁面狀態。文字與穩定的元素定位器，使用無障礙快照。版面、畫布或只有影像的內容，請擷取螢幕截圖：裁切到新的快照 uid，或使用降低品質的 JPEG，以留在內嵌限制之內。解讀像素需要具備視覺能力的模型。WebMCP 與文件記載的 DevTools MCP 工具清單都沒有專用的 OCR 工具；從影像推斷的文字只是建議，不能滿足結構化驗收斷言。

用 types 與 pageSize 縮小主控台讀取範圍；用 resourceTypes 與 pageSize 縮小網路中繼資料範圍。工作流程回執會保留動作前的基準與有上限的差異，方便找出重現過程帶入的錯誤。網路本文與任意評估仍在橋接授予的範圍之外。上游 DevTools MCP 裡的效能追蹤、模擬、Lighthouse、螢幕錄製、記憶體與擴充功能工具是分開的能力，這個設定檔不會把它們公開出來。

請見 Chrome 的 WebMCP 除錯指南與上游的 DevTools MCP 工具參考。上游 main 可能與 AX Code 釘選的橋接不同；只有本機工具結構描述說明支援的引數。