第一次執行
假設你已經完成安裝，並且模擬器裡裝好了遊戲、按遊戲內設定調整完畢。
1. 打開 WebUI
啟動器會直接打開視窗。原始碼或 Docker 部署則訪問：
http://127.0.0.1:25548首次訪問如果要求輸入密碼，說明部署配置裡已經設定了 Password，或者監聽地址不是迴環、程序自動生成了密碼。自動生成的密碼在專案根目錄的 password.txt。
不要裸奔在公網
WebUI 可以啟停任務、讀取截圖、修改配置。監聽 0.0.0.0 且沒有密碼，等於把帳號交給整個網路。開放前務必在部署設定裡設定強密碼。
2. 建立實例
「實例」= 一份獨立的用戶配置 + 一個排程器處理程序。預設實例名是 ap，可以建立 ap-2、ap-3 用於多開。
在 WebUI 的實例列表點擊新建，選擇空白模板或從已有實例複製。複製會連同任務開關和排程時間一起帶走。
配置寫入 config/<实例名>.json。實例名只允許字母、數字、下劃線與短橫線，重命名請通過 WebUI 匯出再匯入，不要直接改檔案名稱。
WebUI 語言與遊戲伺服器是兩件不同的事。前者影響介面文案（zh-CN / en-US / ja-JP / zh-TW），後者在「系統設定 → 模擬器設定 → 遊戲伺服器」裡選擇包名。
3. 連接模擬器
進入「系統 → 模擬器設定」：
| 字段 | 填什麼 |
|---|---|
| 模擬器 Serial | 模擬器 ADB 地址，例如 127.0.0.1:16384；不確定就填 auto |
| 遊戲伺服器 | 通常留 auto；多客戶端時手動選包名 |
| 遊戲內伺服器 | 用於維護檢測。不知道就選「不使用檢測」 |
| 截圖方案 | 先留「自動選擇最快的」 |
| 控制方案 | 推薦 MaaTouch |
儲存後回到總覽，點擊截圖測試。能顯示遊戲畫面就說明 ADB、截圖方案、解析度三項都通了。
auto 不是萬能的
同時開著兩個模擬器時，auto 無法判斷你要控制哪一個。此時必須手填 Serial。查詢方法：在模擬器自帶 adb 目錄執行 adb devices。
畫面是黑的 / 截圖超時
按順序疑難排解：
- 模擬器是否真的啟動了遊戲（不是啟動器介面）。
-
adb devices是否能看到設備且狀態為device（不是offline/unauthorized）。 - 截圖方案換一個再試（例如從
DroidCast_raw換到ADB_nc）。 - 解析度是否為 1280×720。平板模式或自定義 DPI 會導致識別與截圖異常。
4. 跑通第一個任務
不要一上來就開大世界。先用一個短週期、低風險的任務驗證整條鏈路：
在任務列表找到「科研」，打開「啟用該功能」。這兩個任務不消耗石油、失敗代價低，適合驗證。
任務的 Scheduler.NextRun 預設是 2020-01-01（即「立即到期」）。啟用後如果顯示未來時間，清空該字段即可立即執行。
回到總覽點擊啟動。日誌會依次出現：加載配置 → 連接設備 → 截圖 → 進入科研 → 收取/開始研究 → 安排下次執行。
遊戲內科研佇列確實發生變化；WebUI 總覽的「當前任務」顯示該任務；日誌結尾出現「任務結束」；下次執行時間被推到合理區間（科研通常是數小時）。
如果日誌一直停在「連接設備」
說明排程器處理程序沒拿到設備。檢查模擬器是否被其他程序佔用 ADB（例如另一個腳本、Android Studio），以及 Serial 是否寫錯。必要時在「模擬器設定」裡開啟「在檢測不到設備的時候嘗試重新啟動 adb」。
5. 部署設定
config/deploy.yaml 控制後端本身的行為，改動通常需要重新啟動：
| 字段 | 預設 | 說明 |
|---|---|---|
WebuiHost | 0.0.0.0 | 監聽地址；僅本機用 127.0.0.1 |
WebuiPort | 25548 | WebUI 連接埠 |
WebuiPassword | 空 | 訪問密碼；空且監聽公網時會自動生成 |
Language | zh-CN | WebUI 語言 |
Theme | default | 亮色 / 深色 |
OcrServerPort | 22268 | 獨立 OCR 伺服連接埠 |