最近在使用 OpenCode 和 Codex CLI 進行開發時，發現自己經常需要手動確認 Codex 的五小時額度刷新時間。

有時候額度已經恢復，但因為當下沒有開發需求，就沒有立即送出請求。

因此我嘗試開發一個小工具，研究能否在額度恢復後，自動發送一次最小請求，減少手動操作。

專案名稱：Preheat Codex Quota

GitHub：
https://github.com/twinatrick/preheat-codex-quota

━━━━━━━━━━━━━━━━━━━━

一、功能設計

工具主要提供以下功能：

1. 自動查詢 Codex 五小時額度。
2. 只有剩餘 100% 時才嘗試預熱。
3. 每小時 HH:01:00 定期檢查。
4. 在已知刷新時間後 15 秒、45 秒再次檢查。
5. 預設 280 分鐘防重複間隔。
6. 支援 OpenCode Plugin 與 Codex CLI MCP Server。

整體設計希望盡可能減少不必要的請求。

━━━━━━━━━━━━━━━━━━━━

二、技術架構

主要使用兩種語言：

Python：負責額度判斷、CLI 執行、狀態管理與 MCP Server。

TypeScript：負責 OpenCode Server Plugin、背景排程及額度資料取得。

運作流程：

OpenCode / Codex CLI
↓
讀取目前額度
↓
檢查是否為五小時視窗
↓
判斷剩餘額度是否為 100%
↓
確認防重複限制
↓
發送一次簡單請求
↓
記錄結果

預熱請求內容：

Reply with exactly OK. Do not use tools, read files, or perform searches.

━━━━━━━━━━━━━━━━━━━━

三、為什麼加入防重複機制？

因為額度資訊可能存在更新延遲。

如果每次看到 100% 就重新發送請求，反而可能造成額外消耗。

因此使用 Python 檔案鎖、狀態紀錄與冷卻時間，限制重複觸發。

另外也提供 Dry Run 模式，可以只檢查條件而不執行請求。

━━━━━━━━━━━━━━━━━━━━

四、目前開發狀態

目前版本為 v1.3.0，包含 22 項 Python 單元測試，主要驗證：

• 額度解析
• 不同 CLI 的執行路徑
• 防重複檢查
• 排程時間計算
• MCP JSON-RPC 通訊

不過，多帳號隔離、額度資料一致性與不同 OpenCode 認證環境仍有需要改善的地方。

目前不建議將單元測試通過視為所有環境都已驗證完成。

━━━━━━━━━━━━━━━━━━━━

五、這個工具的限制

工具不會增加 Codex 官方額度，也無法繞過使用限制。

另外，發送請求後不保證額度一定立即由 100% 顯示為 99%，或保證刷新時間提前。

預熱效果應以實際帳號顯示的額度與刷新時間為準。

━━━━━━━━━━━━━━━━━━━━

六、開源與交流

這個專案目前放在 GitHub，提供程式碼、Skill 設定、OpenCode Plugin 與安裝文件。

https://github.com/twinatrick/preheat-codex-quota

如果有人也在研究 OpenCode Plugin、Python MCP Server 或 CLI 自動化，歡迎交流設計方式。

也歡迎提出 Bug、相容性問題及改善建議。