ovoBrowser CLI模式使用說明

ovoBrowser CLI模式用於在命令列中以後臺管道啟動案頭用戶端和本地自動化API。 它複用案頭端安全存儲中最近一次登入的帳號會話，不要求用戶把郵箱、密碼、Refresh Token或API Key寫進命令列。

一、適用場景

• 開機腳本或本機任務調度器啟動ovoBrowser API；

• 在不打開主視窗的情况下運行Playwright、Puppeteer、Selenium或自有腳本；

• 為本機工具固定API埠；

• 讓已經登入過的帳號以後臺管道提供環境、代理和瀏覽器生命週期介面。

CLI模式仍然是案頭用戶端的一種啟動管道，不是獨立的雲端服務，也不會繞過帳號許可權、團隊許可權、環境配額或本機安全邊界。

二、首次使用前提

1. 正常打開ovoBrowser案頭用戶端；

2. 登入需要用於自動化的帳號；

3. 確認用戶端能够正常進入主介面；

4. 徹底退出用戶端；

5. 再從命令列使用--cli啟動。

帳號登入憑據保存在作業系統安全存儲中。 CLI不支持也不建議使用以下參數：

--username
--password
--token
--api-key

如果登入已過期、帳號已退出或安全存儲被清除，請重新用案頭介面登入一次。

三、找到程式路徑

如果安裝時使用默認目錄，可從案頭快捷方式的“目標”欄位複製ovoBrowser.exe的完整路徑。 下麵使用占位路徑：

$OvoBrowserExe = "C:\Program Files\ovoBrowser\ovoBrowser.exe"

實際路徑必須以當前電腦的安裝位置為准。

四、啟動CLI模式

使用上次保存的API埠：

& $OvoBrowserExe --cli

指定埠：

& $OvoBrowserExe --cli --api-port 50325

也可以使用等號寫法：

& $OvoBrowserExe --cli --api-port=50325

埠必須是1–65535的整數。 服務只監聽127.0.0.1，不會監聽局域網地址或公網地址。

CLI啟動後：

• 主視窗默認不顯示；

• 用戶端仍在後臺運行，並保留託盤入口；

• 隱藏的渲染行程會恢復安全存儲中的帳號會話；

• API埠會被啟動，並將enabled=true和當前埠保存到本機配寘；

• 下次正常啟動案頭用戶端時，只要上次仍為啟用狀態，就會自動恢復該埠。

五、輸出啟動狀態

輸出可讀文字：

& $OvoBrowserExe --cli --api-port 50325 --cli-print

輸出單行JSON：

& $OvoBrowserExe --cli --api-port 50325 --cli-json

JSON欄位示例：

{
  "success": true,
  "mode": "cli",
  "running": true,
  "host": "127.0.0.1",
  "port": 50325,
  "url": "http://127.0.0.1:50325",
  "pid": 12345,
  "account": "stored-session"
}

部分Windows安裝環境不會把GUI程式的標準輸出保留在當前終端中。 無論終端是否顯示文字，都應通過健康檢查確認服務狀態。

六、確認埠和帳號會話可用

先檢查埠：

$BaseUrl = "http://127.0.0.1:50325"
Invoke-RestMethod -Method Post -Uri "$BaseUrl/health" -ContentType "application/json" -Body "{}"

成功響應：

{
  "success": true,
  "data": {
    "running": true,
    "version": "0.4.3"
  }
}

然後檢查帳號會話和工作區是否恢復完成：

Invoke-RestMethod -Method Post -Uri "$BaseUrl/browser/list" -ContentType "application/json" -Body '{"page":0,"pageSize":1}'

/health成功只表示埠已經監聽；/browser/list成功才表示隱藏用戶端已經恢復帳號會話並可處理帳號數據。 剛啟動時可等待幾秒後重試。

七、與登入後自動啟動的關係

帳號通過密碼登入、注册、Google/GitHub登入、邀請注册或保存會話恢復成功後，本地API都會自動啟動。 實際規則如下：

• 登入成功後會啟動API，並保存enabled=true和當前埠；

• 用戶端下次啟動時可根據已保存狀態提前恢復埠，帳號會話恢復後還會再次確認服務正在運行；

• 在“API & MCP”頁面點擊“停止服務”會立即關閉當前埠，但下一次成功登入或會話恢復仍會自動啟動；

• 使用--cli也會顯式啟動埠並保存為啟用狀態；

• 用戶端徹底退出後，API行程和埠會一起關閉。

八、已經有用戶端實例時

ovoBrowser使用單實例運行。 如果案頭用戶端已經打開，再執行：

& $OvoBrowserExe --cli --api-port 51234

命令會交給現有實例處理，並把本地API啟動或切換到指定埠，不會再啟動第二套帳號行程。 切換埠後，調用方必須更新baseUrl。

九、停止CLI服務

CLI模式與案頭用戶端使用同一個行程。 可使用以下管道停止：

• 從系統託盤退出ovoBrowser；

• 再次打開主視窗，在“API & MCP”頁面點擊“停止服務”；

• 正常退出ovoBrowser行程。

不要使用強制結束行程作為日常停止管道； 正常退出會關閉瀏覽器內核和本地API，並完成必要清理。

十、Postman配寘

1. 導入ovoBrowser-Local-API.postman_collection.json；

2. 打開集合Variables；

3. 把baseUrl改為CLI使用的地址，例如http://127.0.0.1:50325；

4. 先運行“健康檢查”；

5. 再運行“環境清單”，確認帳號會話已經恢復；

6. 按需調用環境和代理介面。

Postman不需要Bearer Token、API Key或x-api-key。本地API只允許當前電腦訪問。

十一、常見問題

Connection refused

CLI行程沒有運行、埠寫錯、埠被佔用，或程式啟動失敗。 檢查命令中的--api-port，並確認健康檢查地址一致。

健康檢查成功，但環境清單提示用戶端未就緒

隱藏用戶端還在恢復登入會話，先等待幾秒重試。 如果持續失敗，正常打開案頭用戶端，確認帳號沒有退出且能進入主介面。

埠已被佔用

換一個未佔用埠，例如：

& $OvoBrowserExe --cli --api-port 51234

登入已過期

CLI不接收帳號密碼。 請正常打開用戶端重新登入，退出後再運行CLI。

執行命令後主視窗沒有出現

這是CLI模式的預期行為。 可從託盤打開主視窗，或直接調用健康檢查。

十二、安全建議

• 只監聽和調用127.0.0.1；

• 不要用埠映射、反向代理或隧道把本地API暴露到局域網或公網；

• 不要把代理密碼、 Cookie、 帳號密碼或完整API響應寫入公共日誌；

• 不要在命令列參數、批次檔或任務計畫程式中保存登入密碼；

• 自動化結束後關閉不再使用的環境；

• 團隊帳號只授予腳本真正需要的許可權。

十三、參數速查

相關文檔：

• API檔案.md

• ovobrowser-api調用程式碼示例/postman/ovoBrowser-Local-API.postman_collection.json

• ovobrowser-api調用程式碼示例/README.md