bux 是 Browser Use 團隊開源的安裝腳本。一行指令,把任何一台你擁有的主機——VPS、Mac mini、Raspberry Pi——變成全天候運行的 Claude Code agent,內建真實 Chromium、Telegram 遠端操控與 Web 終端機。登入狀態與 Cookie 持久保存,你用 Telegram 下指令,它替你在瀏覽器裡完成工作。這份手冊涵蓋安裝、架構、設定密技與一段完整操作實例。
bux 出自 Browser Use 團隊,定位是「把任何一台你擁有的機器,變成 24/7 在跑、且具備真實瀏覽器的 Claude Code agent」。它本身不是新模型,也不是新框架,而是一支安裝腳本:在一台乾淨的 Ubuntu/Debian 主機上執行,它會裝好 Node.js 24、Claude Code、Web 終端機 ttyd,建立一個專用系統使用者 bux,並把所有元件登錄成 systemd 服務常駐運行。
和一般在筆電上手動開 Claude Code 不同,bux 把 agent 放到一台永遠開機的伺服器上。瀏覽器會話透過 browser-harness 持久保存——Cookie 與登入狀態在重啟後仍在,因此 agent 可以「記得」你已登入的 Gmail、後台或服務,不必每次重新驗證。所有狀態存在 /home/bux,主機重開後接續執行。
操控方式有兩條:綁定一個 Telegram bot,用手機傳文字指令給 agent;或開啟內建的 Web 終端機,免 SSH 直接進到 Claude Code session。遇到登入牆、兩階段驗證或 CAPTCHA 時,agent 會回傳一個即時瀏覽器畫面網址,讓你親自接手點完那一步,再把控制權交還給它。
先準備三樣東西:一台 Ubuntu/Debian 22.04 以上、至少 2GB RAM 的主機(VPS 或自有的 Mac mini、Raspberry Pi 都可以);一把 Browser Use Cloud API key,在 cloud.browser-use.com/new-api-key 申請,免費方案提供 3 個並行瀏覽器;以及一組 Anthropic API key,或 Claude Max 訂閱。Telegram bot token 可選,稍後再加。
SSH 進你的主機後,把 API key 填進下面這行直接執行。安裝腳本約 2–3 分鐘跑完,且具備冪等性(idempotent)——重複執行不會出錯。
安裝結束後,切換到 bux 使用者並啟動 Claude,首次執行輸入 /login 完成 OAuth 驗證。之後再執行 claude 就會直接進入。
不帶任何變數直接執行,腳本會以互動模式逐項詢問缺少的值。要一次帶齊則用環境變數前綴。安裝過程會裝好 Node.js 24、Claude Code、ttyd,並建立 bux 系統使用者。
| 環境變數 | 用途 |
|---|---|
BROWSER_USE_API_KEY=bu_xxx |
Browser Use Cloud 金鑰,驅動雲端瀏覽器(必填) |
TG_BOT_TOKEN=123:abc |
Telegram bot token,啟用手機遠端操控(可選) |
WITH_ZTK=0 |
跳過 ztk 壓縮工具的安裝(可選) |
/etc/bux/,agent 狀態存於 /home/bux。
安裝完成後,bux 在主機上以 systemd 服務的形式常駐運行,主機重開也會自動恢復。整套系統由四個元件構成:Telegram bot 接收你的指令、browser-keeper 維持與 Browser Use Cloud 的瀏覽器連線、ttyd 提供免 SSH 的 Web 終端機、以及核心的 Claude Code session。下表是各服務的角色。
| 服務名稱 | 角色 | 查看日誌 |
|---|---|---|
bux-tg |
Telegram bot,接收與回覆指令 | journalctl -u bux-tg |
bux-browser-keeper |
瀏覽器連線管理,維持雲端 Chromium | journalctl -u bux-browser-keeper |
bux-ttyd |
Web 終端機存取 | systemctl status bux-ttyd |
bux-restart |
重啟服務並於 Telegram 通知恢復 | systemctl status bux-restart |
以下技巧整理自官方 install.md 與 README,涵蓋 Telegram 綁定、即時畫面接管、Web 終端機與日誌排查等實際操作環節。每一條都是安裝後立刻會用到的。
用 @BotFather 的 /newbot 取得 token 後,對你的 bot 傳第一則訊息——這個帳號會被永久綁定,之後 bot 會忽略其他寄件者。請確定第一個傳訊的是你本人。
傳 /live 給 bot,它會回一個即時瀏覽器畫面網址(live.browser-use.com)。遇到登入、2FA、CAPTCHA 時你親自點完那一步,再讓 agent 接續——登入狀態會被保存起來。
同一 session 的訊息共享記憶,後續指令可直接引用先前內容。先「check my email」,再「reply to the second one」即可,不必每次重述背景。
來源 · install.md · Sessions share memorybux-ttyd 在瀏覽器裡提供主機終端機,免 SSH 即可進到 Claude Code session,適合除錯或直接下較長的指令。Telegram 與 Web 終端機兩條入口可並用。
來源 · install.md · 服務組成安裝腳本具備冪等性,可安全重複執行。要一次帶齊則用環境變數前綴:... | sudo BROWSER_USE_API_KEY=bu_xxx TG_BOT_TOKEN=123:abc bash。漏填的值會在互動模式逐項補問。
Bot 沒反應查 journalctl -u bux-tg -n 50;瀏覽器崩潰查 bux-browser-keeper 並確認 /etc/bux/env 裡的金鑰。CDP_WS 缺失就 systemctl restart bux-browser-keeper。
以下是一段示意對話:你人在外面,用 Telegram 請 bux 上你的後台查一筆訂單。過程中遇到登入牆,agent 用 /live 把畫面交還給你完成 2FA,接著繼續操作並回報結果。這正是 bux 與一般爬蟲的差異——它能處理需要登入與互動的真實流程。
關鍵有兩處。第一,agent 沒有在 2FA 前放棄,而是透過 /live 把控制權交還給人——這讓「需要登入的真實後台」也進入它能操作的範圍,而非只能爬公開頁面。第二,登入狀態被 browser-harness 保存下來,所以下一次再查同一個後台,通常不必重新驗證。
因為 bux 跑在一台常駐主機上,這整段流程你都只是在 Telegram 打字,人不必坐在電腦前。把它放上 VPS,就等於有一個全天候待命、且真的會開瀏覽器辦事的助理。
/etc/bux/tg.env 再重新綁定。
/etc/bux/env,Telegram token 在 /etc/bux/tg.env。任何能存取這台主機 root 的人都能讀到——主機的存取控制就是你的安全邊界。
--session-id 相關錯誤,先更新:sudo npm install -g @anthropic-ai/claude-code@latest。CDP_WS 缺失則等 10 秒或重啟 browser-keeper。
systemctl stop bux-*,再移除 /etc/bux、/opt/bux、/home/bux/.claude、/home/bux/.bux,刪除 bux 使用者,然後重裝。殘留設定會讓重裝行為不如預期。
裝好之後,bux 不是「裝完就定型」。它的行為與職責邊界寫在純文字檔裡,你可以照自己的工作習慣調整;也可以選擇自架或交給官方代管。
1. 編輯 agent/CLAUDE.md。agent 的上下文與行為規則集中在這個檔案。在裡面寫清楚它的職責範圍、可以與不可以動的資源、慣用語氣與輸出格式,就能把它從通用 agent 調成貼合你業務的助理。
2. 挑一台適合的主機。長時間運行建議放在 VPS(Hetzner、DigitalOcean、Fly.io、AWS);若你想讓資料留在自家,Mac mini 或 Raspberry Pi 也能跑。只要符合 Ubuntu/Debian 22.04+、2GB RAM 即可。
3. 善用兩條操作入口。外出時用 Telegram 下指令,需要細部除錯或下長指令時改用 Web 終端機。兩者連到同一個 agent 與同一份持久狀態。
4. 評估官方代管方案。若你不想自己維運主機,bux 提供每月 1,000 美元的代管試行方案,會自動配置基礎設施,並為以 Telegram 為主的團隊安排交付流程。適合想直接用、不想碰伺服器的團隊。
① install.md——完整安裝、設定與疑難排解指南。
② agent/CLAUDE.md——可自訂的 agent 上下文與行為規則。
③ 專案 Wiki——安裝細節與代管方案說明。