如果你的程式是建立在 browser-use 0.x 上,升級到 1.0 不只是版本更新,而是架構和預設值都換了一套。原本的 24 個瀏覽器動作,現在由一個持久化 Python REPL 取代;而 Browser() 也不再代表本機瀏覽器,而是直接建立雲端瀏覽器。本指南根據 1.0.7 的版本說明、MIGRATING.md,以及 11 月 20 日發布的工程文章,整理 1.0.7 的固定方式、首次執行流程與 0.x 遷移重點。
5 分鐘跑起來 1.0
先把版本鎖定。1.0.0 於 2026 年 11 月 10 日發布;到了 11 月 20 日,1.0.7 已是穩定標籤,而 1.0.8rc1 則仍處於預發布狀態(版本列表)。README 特別提醒,永遠不要使用 >=,因為不同次版本之間可能會破壞 API。
uv add 'browser-use==1.0.7'
# or
pip install 'browser-use==1.0.7'需求條件很明確:Python 3.11 以上、4.0 以下(README、PyPI)。所有相依套件都使用 == 鎖定版本,有助於重現環境,但如果你的應用程式同時需要不同版本的 pydantic、mcp 或 google-genai,就可能產生相依性衝突。
接著完成一次驗證。到 cloud.browser-use.com 建立金鑰,再選擇匯出環境變數或執行登入輔助程式:
export BROWSER_USE_API_KEY=bu_...
# or
browser-use login登入資訊會儲存在 ~/.config/browser-harness/auth.json,CLI、MCP server 和 browser-harness 都會共用這份設定(MIGRATING.md)。如果是在容器中執行,請使用 BROWSER_USE_AUTO_LOGIN=true;在 SSH 或無頭環境裡,1.0.8 release candidate 會顯示連結和核准碼,你可以用另一台裝置完成核准(1.0.8rc1 說明)。
第一次執行只需要三行:
from browser_use import Agent
result = Agent(
"Find the number of stars of the browser-use repo"
).run_sync()
print(result.final_result())不過,這段程式預設會產生費用:它使用 Browser Use Cloud 瀏覽器和預設 gateway 模型(README Path 1 / Path 3、MIGRATING.md 預設值)。如果只是想零雲端支出地測試,現在就加上 Browser('chromium') 和自己的 llm。
原本的 24 個動作去哪了?
browser-use 0.x 會把一份 DOM 傾印交給模型,讓模型每一步從動作選單中挑一個動作。1.0 直接拿掉這個選單,改成提供一個主要的 python 工具:它是持久化 REPL,預先載入 browser-harness 輔助程式和 raw cdp(),底層則建立在 Pydantic AI 上(工程文章):
async def python(ctx: RunContext[Session], code: str) -> list[Any]:
"""Run Python in the persistent REPL
(browser-harness helpers and raw cdp() pre-imported)."""這次刪改共移除 136,905 行、在 554 個檔案中新增 29,601 行,Python 檔案數也從 178 個降到 43 個(工程文章)。
最能說明這種設計的例子,是處理卡住的頁面:agent 呼叫 Page.stopLoading、攔下卡死的 script、重新載入頁面,接著找出頁面內部的 JSONP endpoint,再分批抓取 730 個日期,只重試失敗的批次,最後回傳 4,720 筆資料。整個過程沒有任何一個專用工具負責這些工作(工程文章)。
團隊留下的原則很簡單:只有在模型讀過一次後仍無法自行重寫時,才值得做成 helper。CAPTCHA 是例外。在一次規模不大的 staging 測試中,單靠文字指示處理 hCaptcha 的成績是 0/3;專用的 solve_captcha 工具則是 6/6,原因在於這個工具能切換頁面本身無法觸及的 solver 開關(工程文章)。
至於成本和速度,別只看標題數字,先讀清楚註腳。11 月 20 日的文章表示,在同一批三個模型上,1.0 的分數高出 14–33 分,成本則低了 2.7–5.2 倍;測試是在 11 月 8 日執行的 200 項任務,其中 180 項有評分。但文章也明確指出,每個模型只跑了一次,而且預設值已經改變,因此不能把全部功勞都歸給工具重設計(工程文章)。
較乾淨的比較需要縮小範圍。1.0.4 的分數是 76.1,1.0.3 則是 76.0;在保留 prompt caching 的前提下,批次螢幕截圖裁剪讓每項任務的模型成本從 $0.434 降到 $0.208(1.0.4 說明)。BU Bench v2 中,1.0 ultrafast 得分 62.5、成本 $0.070、耗時 650 秒;Browser Use Pi 則是 56.3、$0.082 和 743 秒。作者表示,排除 provider 錯誤後,這個差距已失去統計上的顯著性。預期它會更便宜、更快,但別直接當成更聰明。
會悄悄改變帳單與瀏覽器的預設值
下表整理自 MIGRATING.md 和 1.0.6 版本說明;內容以 1.0.7 為準,也納入較早指南容易漏掉的 1.0 中期預設模型切換。
| 設定 | 0.x | 1.0.7 |
|---|---|---|
llm=None | 必須指定模型 | 透過 Browser Use gateway 使用 bu-4.0 |
bu-4.0 價格 | n/a | 輸入每 1M $1.80,輸出每 1M $9.00 |
bu-fast 價格 | n/a | 輸入每 1M $0.12,輸出每 1M $0.60 |
Browser() | 本機 Chromium | Browser Use Cloud 瀏覽器 |
| 本機瀏覽器 | 預設值 | 必須明確指定 Browser('chromium') |
| API key | 每個 provider 一組 | 一組 BROWSER_USE_API_KEY |
max_steps | 500 | 100(保留一個 step 用於交付結果) |
| Agent timeout | 未指定 | 1,700 秒,不含啟動與關閉時間 |
| Judge | 選擇性啟用 | 預設為 judge=True |
| Reasoning / mode | n/a | bu-fast / bu-ultrafast 使用 reasoning='medium'、mode='ultrafast' |
有三個陷阱特別值得注意。第一,預設模型在 1.0 中途換過:到 1.0.5 為止,預設值都是 bu-fast;但 1.0.6 改成了 bu-4.0,token 價格高出 15 倍。專案自己的範例顯示,同一個簡短測試使用 bu-4.0 會花 $0.022,使用 bu-fast 則是 $0.0014。想維持舊的成本水準,就明確傳入 llm='bu-fast'。第二,現在直接呼叫 Browser() 會建立雲端瀏覽器,每瀏覽器小時 $0.06,另外還有模型與搜尋費用(README);而且雲端瀏覽器無法連到 localhost 或私有 IP(MIGRATING.md)。第三,一個 step 等於一次模型請求加上一個 Python cell,因此較低的 100-step 上限同時也成了支出上限;現在 max_steps < 1 或 timeout <= 0 會在瀏覽器啟動前就失敗(MIGRATING.md)。
Judge 是另一筆容易忽略的費用。任何至少完成一個 step 的執行,都會讓你自己的模型額外發出一次低成本請求,處理最多 120,000 個字元的 trace;如果啟用 vision,還會一併送出最後四張不重複的圖片,包括最後一頁,而且資料不會經過遮罩(MIGRATING.md)。結果會放在 result.judgement,包含 success、failure_reason、gotchas,以及 bot/CAPTCHA 旗標;這筆成本也會計入 result.cost_usd。你可以用 judge=False 關閉它,或傳入包含預期答案的 judge_context;如果螢幕截圖不應離開你的資料邊界,請設定 use_vision=False。
需要時,把瀏覽器留在本機
選瀏覽器時,先看它需要連到哪裡,不要只是沿用習慣。下面的模型識別名稱,是 README 本機瀏覽器範例中的示意 provider(README):
from browser_use import Agent, Browser, ChatOpenAI
agent = Agent(
"Summarize the dashboard at http://localhost:3000",
llm=ChatOpenAI("gpt-6-luna"),
browser=Browser("chromium"),
)
print(agent.run_sync().final_result())需要存取 localhost、私有網路或自訂 viewport 時,請使用 Browser('chromium');如果雲端的裝置度量呼叫不會改變實際頁面 viewport,也應選它。想操作已經開啟、而且保留現有登入狀態的 Chrome,則使用 Browser('chrome');Browser('chrome', profile='Work') 會啟動一份帶有登入資訊的暫時副本,但不會把 Sync 寫回去。在 Windows 上,因為 cookie 會被鎖定,請先關閉原本的 Chrome(MIGRATING.md)。如果你需要受管理的 stealth、proxy、CAPTCHA 處理或完全不設定本機環境,雲端仍然是合理的預設選擇(README);只是要把瀏覽器小時費用和 token 費用分開編列。
自訂模型仍然可以使用,但要走對路徑(MIGRATING.md):
- Gateway 別名:
bu-4.0、bu-4.0-mini、bu-4.0-pro、bu-fast、bu-ultrafast、bu-smart - Providers:
ChatOpenAI、ChatAnthropic、ChatGoogle,或像groq:llama-3.3-70b-versatile這樣的 Pydantic AI 字串 - Azure:使用
llm='azure:<deployment>',並設定AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEY和OPENAI_API_VERSION
現在把 LangChain chat object 傳給 Agent(llm=...) 會拋出 TypeError;像 bu-2-0 這類已退役的 gateway 名稱,也會在瀏覽器啟動前被拒絕。每個平行執行的 agent 都需要自己的 Browser();兩個 agent 共用同一個瀏覽器會拋出 RuntimeError。不過,設定 keep_alive=True 的瀏覽器可以由多次循序執行共用(MIGRATING.md)。
別靠猜來遷移:讓錯誤訊息告訴你答案
1.0 刻意採用快速失敗。被移除的 import 會拋出標明替代方案的 ImportError;不支援的 Agent(...) 參數會拋出 TypeError;任何 1.0 無法處理的設定,都會在瀏覽器啟動或產生費用前報錯(MIGRATING.md)。另一小批設定——包括 use_vision=True、vision_detail_level、max_actions_per_step、flash_mode、max_failures、highlight_elements 以及類似的調校旗標——雖然仍可接受,卻會被忽略,且每個設定只顯示一次警告。use_vision=False 仍然有效,因為它會阻止螢幕截圖傳給模型。
啟動之後,行為則相反:run() 通常會回傳錯誤結果,而不是直接拋出例外,狀態會是 status='error',詳細資訊放在 result.error。只有取消操作仍會往外拋出。請同步調整你的判斷方式:
# 0.x
history = await agent.run(max_steps=500)
ok = history.is_successful()
# 1.0
result = await agent.run(max_steps=100)
ok = result.is_done() and result.success is not False現在的 is_done() 只表示執行已經結束;成功與否取決於模型透過 finish(result, success) 給出的判定,而當模型沒有提供判定時,is_successful() 會回傳 None。舊版逐步歷史記錄的輔助方法——包括 action_names()、model_actions()、extracted_content()、save_as_playwright_script(),以及 MIGRATING.md「removed history APIs」列出的其他方法——都已移除。請改讀 result.messages、result.status、result.partial、agent.workspace 裡的檔案,以及 result.judgement。
先做三項修改:把 max_steps 從 Agent(...) 移到 agent.run(max_steps=...);將移除的 callback(on_step_start、pause、stop、multi_act、save_history)改用 logging.getLogger('browser_use') 設為 INFO,或使用 BROWSER_USE_LOGGING_LEVEL=warning;重新檢查 secrets 的作用範圍。現在 domain-scoped secrets 只會在符合的頁面上輸入,以 bu_2fa_code 結尾的名稱會被視為 TOTP seed;舊版的 <secret>name</secret> placeholder 會報錯,必須改成 type_secret('name')。值在 cells 和結果中會以 <secret:name> 顯示,但這只是遮罩,不是 sandbox,因為模型撰寫的 Python 仍然可以讀取 secrets(MIGRATING.md)。如果還需要時間,可以先用 pip install 'browser-use<1' 鎖住版本,再在分支上遷移。
"browser use is more a python framework for building your own browsing agent" — u/Starks1293,發表於 r/ClaudeCode
這個說法也符合 Reddit 討論中使用者對它的描述:它更像是建立瀏覽 agent 的框架,常被拿來討論受 bot 防護的網站和程式碼層級的控制。不過可靠度仍取決於模型與網站;一篇正式環境報告提到,處理基本表單填寫時,花了五分鐘、失敗了九個 step。
上線前先看:judge、secrets,以及不太穩定的現實
如果你要深入使用,真正重要的是:
- 透過
output_model_schema定義型別化結果,再從result.structured_output讀取 - 使用 workspace 上傳檔案,以及透過
workspace/downloads管理下載內容,結果則從result.downloads取得 - 網域控制項(
allowed_domains、prohibited_domains、block_ip_addresses),它們能約束行為一致的模型,但不是網路 sandbox - 選擇性啟用
web_search=True;每次搜尋都會計費,並計入result.cost_usd - 透過
browser-use --cli-mcp、browser-use skill install和browser-use --doctor使用 CLI/MCP
把 1.0 當成一個快速變動中的框架來管理:鎖定精確版本,在長任務上加入 judge_context,用 checkpoint('titles.json', titles, partial=True) 保存未完成工作;不受信任的任務則放進容器執行,因為網域限制和 secret 遮罩都不等於隔離(README)。
現在遷移、先鎖版本,還是留在 0.x?
| 情況 | 建議 |
|---|---|
| 新建 agent 專案,可接受雲端 | 從 ==1.0.7 開始,保留 bu-4.0 預設值,維持 judge 開啟 |
| 對成本敏感的批次工作 | 傳入 llm='bu-fast' 和 judge=False,擴大規模前先量測 |
| Localhost/內網/自訂 viewport | 使用 Browser('chromium') 加上自己的模型,絕不要使用裸呼叫 Browser() |
| 現有 0.x 正式環境 | 在主分支鎖定 browser-use<1,再利用快速失敗的錯誤訊息於分支上遷移 |
| 大量依賴 CAPTCHA 的流程 | 為專用 solver 編列預算;團隊測試中,單靠文字指示的成績是 0/3 |
你會得到一個能攔截卡死 script、或呼叫從未包裝成工具的私有 API 的 agent,但同時也失去固定動作選單帶來的防護。如果你的網站適合這種取捨,就遷移;如果還不確定,現有正式系統先維持 browser-use<1,邊鎖定版本邊評估,仍然是更安全的做法。
常見問題
browser-use 1.0 有哪些新功能?
一個搭配 browser-harness 輔助程式與 raw CDP 的持久化 Python REPL,取代了 0.x 的 24 動作選單,整個函式庫大約移除了 80% 的內容(Python 檔案從 178 個降到 43 個)。預設值也改成 Browser Use Cloud、gateway 模型,以及單一的 BROWSER_USE_API_KEY。
我的 0.x 程式碼會壞掉嗎?
常見入口(Agent、Browser、run()、final_result())仍然存在,但被移除的 import 和選項會在計費前拋出 ImportError 或 TypeError;max_steps 已移到 run(),而 Browser() 現在代表雲端瀏覽器。想維持現狀就鎖定 browser-use<1,否則建議先建立分支再遷移。
還能使用自己的模型和本機瀏覽器嗎?
可以。你可以傳入 ChatOpenAI、ChatAnthropic、ChatGoogle 等 provider,或使用 Pydantic AI 字串;本機瀏覽器則用 Browser('chromium') 建立全新的瀏覽器,或用 Browser('chrome') 操作已開啟的 Chrome。雲端瀏覽器無法連到 localhost。
browser-use 1.0 需要哪個 Python 版本?
Python 3.11 以上、4.0 以下。精確鎖定的相依套件版本可能會和其他套件衝突,因此建議先在全新的虛擬環境中安裝。
如何關閉執行 judge?
傳入 judge=False,即可略過額外的評判請求;或者傳入包含驗收條件的 judge_context,讓它的判定更有參考價值。如果 judge 不應傳送螢幕截圖,請設定 use_vision=False。