Praetor 使用者手冊

本手冊是給安裝與使用 Praetor 的 owner / founder 閱讀。它回答的是「我現在要怎麼用」與「什麼情況下該做什麼」。

產品設計、工程架構、roadmap、ADR、安全稽核細節請看 內部設計與維護文件索引。那些文件是給維護者、貢獻者與產品設計決策使用，不是日常操作手冊。

1. 你需要先知道的事

Praetor 是 local-first 的 AI company operating system。你主要透過一位 AI CEO 下達意圖，CEO 再把工作轉成 mission、專案、會議、決策、agent 分工與可檢查的本機 workspace 檔案。

Praetor 不是全自動代理人，也不是遠端託管企業服務。重要動作仍應由 owner 審核，尤其是刪除檔案、外部溝通、花費、shell command、憑證、安全設定、runtime 設定與 workspace 權限變更。

2. 安裝方式

一般使用者建議用 Docker 一鍵安裝：

curl -fsSL https://raw.githubusercontent.com/chaochungkuo/praetor/main/scripts/install.sh | sh

安裝前請確認：

• Docker Desktop 或 Docker Engine 已啟動。
• 已安裝 Git。
• 使用 macOS、Linux，或 Windows with WSL 2。

安裝完成後，終端機會顯示：

• App URL
• setup URL
• workspace path
• doctor command
• backup command
• executor setup command

預設 App URL 是：

http://127.0.0.1:9741/app/praetor

預設會建立：

• ~/.praetor/praetor：Praetor app source。
• ~/.praetor/data：私有 app state。
• ~/praetor-workspace：你可以直接查看的公司 workspace。
• http://127.0.0.1:9741：本機 Docker app。

3. 第一次設定

打開 installer 印出的 setup URL，依序完成：

1. 確認 local app URL。

2. 選擇公司 workspace folder。

3. 選擇 AI runtime。

4. 檢查 starter AI company org chart 與 approval boundaries。

5. 建立 owner login。

6. 開始第一個 mission。

第一次測試建議：

• Workspace 使用預設 ~/praetor-workspace。
• Runtime 選 Dry-run demo provider，除非你已經準備好 API key 或 Codex bridge。
• Approval boundaries 先維持預設保守設定。
• Owner 密碼使用密碼管理器保存，不要重用其他服務的密碼。

3.1 前 30 分鐘怎麼開始

如果你是創業者，第一次進入 Praetor 不需要先理解所有功能。建議照這個順序：

1. 打開 辦公室。

2. 看最上方狀態列，確認 執行環境 是「就緒」還是「需要設定」。

3. 如果需要設定，先打開 執行環境，看 Praetor 明確列出的下一步。常見情況是需要設定 bridge URL / token，或在 host 上執行 codex login。

4. 回到 辦公室，在「創業者起步」選一個起點：

- 建立產品

- 研究市場

- 規劃行銷

- 整理營運

5. Praetor 會把 prompt 放進 CEO 對話框。你可以直接送出，也可以先補充公司背景、限制、預算或時間。

6. 要求 CEO 把討論轉成第一個 mission。好的第一個 mission 應該包含：

- 目標與範圍

- 會建立或更新哪些檔案

- 需要哪些決策

- 驗收標準

- 不能自動做的高風險事項

7. 到 任務 或 工作區 檢查結果。不要只看聊天，要確認檔案、決策、任務狀態與後續動作。

第一個有用 prompt 範例：

我想建立一個小型軟體產品。請幫我釐清目標使用者、核心問題、MVP 範圍、第一個技術任務、應該建立的檔案、驗收標準，以及執行前需要我做哪些決策。

如果你還沒有準備好讓 AI 實際執行，仍然可以用 dry-run 或只請 CEO 做規劃。先把公司思路、任務、檔案與決策整理出來，就已經有價值。

4. Runtime 怎麼選

Dry-run demo provider

適合：

• 第一次試用。
• 不想輸入 API key。
• 想先了解 UI、mission、workspace、approval flow。

限制：

• 輸出是 deterministic demo，不是實際外部模型推理。

API key mode

適合：

• 你已經有 OpenAI、Anthropic 或 OpenAI-compatible gateway API key。
• 你想讓 Praetor 實際呼叫模型完成工作。
• 你可以接受 API 成本。

注意：

• API key 是敏感資料，請只在本機可信環境設定。
• 涉及成本、外部呼叫與資料傳送時，應保留 owner approval。

Local subscription executor

適合：

• 你已經在主機上使用 Codex CLI。
• 你想透過既有 ChatGPT subscription 使用 Codex。
• 你接受在主機上執行 praetor-execd bridge。

設定文件：

• ChatGPT Subscription Executor
• Local Deploy: Subscription executor mode

不要把 ChatGPT 密碼或 browser session 放進 Praetor。設計上是讓 Codex CLI 在 host 上登入，Praetor 透過 scoped local bridge 呼叫它。

Runtime readiness 怎麼判斷

在 執行環境 頁，先看三件事：

• 健康檢查清單：紅色或等待中的項目會寫出 Praetor 需要你做什麼。
• 執行器 Bridge：如果 bridge URL、已選執行器、登入狀態或非互動批次能力顯示未設定，Praetor 只能規劃，不能可靠執行。
• 模型與 API：確認目前模式、供應商、模型與預算上限是否符合你的使用方式。

Praetor 能自己處理的事：

• 整理想法、產生 mission plan、建立草稿、更新低風險 workspace 檔案。
• 檢查目前狀態，指出缺少的設定。
• 在已有授權與 runtime 可用時啟動任務。

需要使用者協助的事：

• 登入 Codex CLI 或 Claude Code。
• 設定 API key、bridge token、workspace 權限、Docker/terminal 本機環境。
• 核准外部溝通、花費、刪除、覆寫、憑證、安全與法律相關動作。

4.1 Model profile 與原生 subagents

Praetor 內部使用統一的 model profile，而不是要求你記住每個 provider 的 model 名稱：

• fast：摘要、整理、格式化、狀態更新。
• standard：一般分析、普通文件或程式修改。
• reasoning：複雜 planning、debug、跨檔案變更、架構判斷。
• critical：安全、隱私、法律、財務、runtime、credentials、高風險 final review。

如果 Praetor 不確定任務複雜度，預設會保守升級到較高 profile。未來你可以在 Runtime 設定中把這些 profile 對應到 OpenAI、Claude、Codex 或 Claude Code 的實際 model。

Praetor 不會在 v1 自己管理一堆 sub-agent。對開發或研究任務，如果你選的 executor 例如 Codex 或 Claude Code 有原生 subagent / dynamic workflow 能力，Praetor 可以允許 executor 自己使用。Praetor 只保存最後的執行結果、證據、變更檔案、測試、風險提示與是否需要人工 review。

5. Workspace 怎麼理解

Praetor 的公司檔案放在你設定的 workspace root。預設是：

~/praetor-workspace

常見資料夾：

• Projects/：長期專案與專案狀態。
• Missions/：一次具體工作、報告、任務、決策紀錄。
• Wiki/：公司知識、策略、背景資訊。
• Decisions/：重要決策紀錄。
• Archive/：封存資料。

你可以直接用 Finder、File Explorer 或 terminal 查看這些檔案。這是 Praetor 的核心設計：AI 工作不只留在聊天裡，也要落成可檢查、可備份、可移動的本機檔案。

6. 什麼時候問 CEO，什麼時候開 Mission

直接問 CEO 適合：

• 查詢目前狀態。
• 要求簡短建議。
• 問某個設定在哪裡。
• 請 CEO 解釋 workspace 裡的內容。
• 讀取 public 或 read-only 資訊。

開 mission 適合：

• 需要多步驟工作。
• 需要寫入檔案或更新專案狀態。
• 需要多個 agent 分工。
• 需要產出報告、計畫、決策紀錄或 workspace artifact。
• 需要追蹤進度、blocker、owner approval 或完成標準。

如果不確定，先問 CEO。CEO 應該先判斷是否需要 mission，而不是每句話都自動開任務。

7. Approval 怎麼判斷

建議保留 approval 的情況：

• 刪除或覆寫重要檔案。
• 執行 shell command。
• 修改 runtime、API key、bridge、workspace permission。
• 對外發訊息或發布內容。
• 產生成本或消耗配額。
• 處理安全、憑證、私密資料。
• 改變長期記憶、公司策略或 standing order。

可以考慮低風險自動化的情況：

• 建立草稿。
• 讀取 workspace 中的非敏感文件。
• 更新 mission 內部狀態。
• 產生建議清單或待審文件。
• 對 demo provider 產生本機測試輸出。

原則是：AI 可以準備、整理、建議與執行低風險步驟；owner 應該保留高風險決策權。

8. 常用操作

檢查安裝狀態

~/.praetor/praetor/scripts/praetor.sh doctor
~/.praetor/praetor/scripts/praetor.sh validate-install --json

從 terminal 問 CEO

~/.praetor/praetor/scripts/praetor.sh ceo ask "What should I review first after installation?"

備份

~/.praetor/praetor/scripts/praetor.sh backup

升級 Praetor

當 Praetor 有新版本時，請使用內建 update command：

~/.praetor/praetor/scripts/praetor.sh update

這個指令會先建立備份，再更新 app source、重建 Docker image、重新啟動 Praetor，最後做 health check。正常升級不會刪除你的公司：

• ~/.praetor/data 會保留：owner account、settings、missions、agents、CEO sessions、memory、connector 狀態。
• ~/praetor-workspace 會保留：Wiki、Projects、Missions、Decisions 與公司檔案。
• ~/.praetor/praetor 會更新：這裡是 Praetor 程式碼，不是你的公司資料。

升級完成後，終端機會顯示：

• state path
• workspace path
• pre-update backup archive

如果升級失敗，先看錯誤訊息中列出的 backup archive。你可以用：

~/.praetor/praetor/scripts/praetor.sh restore /path/to/praetor-backup-YYYYMMDD-HHMMSS.tar.gz
~/.praetor/praetor/scripts/praetor.sh restart

不要把重新執行 one-line installer 當作日常升級方式。installer 現在會盡量保留既有 .env，但一般升級仍應使用 praetor.sh update，因為它會自動備份與檢查健康狀態。

重新安裝並清空本機公司

只有在你確定要刪除本機 Praetor 公司、owner account、settings、memory 與 workspace 時才使用：

~/.praetor/praetor/scripts/praetor.sh uninstall --purge

9. Telegram 入口

Telegram 適合做：

• CEO 簡短對話。
• 短語音 / 音訊訊息；前提是已設定 transcription。
• briefing。
• mission 狀態查詢。
• approval 通知。
• 低風險 approval reject / approve。

Telegram 不適合做：

• API key 管理。
• workspace permission 變更。
• 高風險安全審查。
• 私密文件詳細審閱。

設定方式請看 Telegram CEO Access。

語音輸入目前分兩種：

• Web Office：可以用瀏覽器錄音，上傳到 Praetor 的 transcription endpoint。
• Telegram：可以傳短語音給 bot；Praetor 會先轉文字，再送給 CEO。

語音轉文字可到 Settings -> 語音轉文字 設定。預設是 Auto：

• 先嘗試本機 whisper CLI 與設定的 Local Whisper model。
• 如果本機 Whisper 不可用或轉錄失敗，且已設定 OPENAI_API_KEY，則 fallback 到 OpenAI-compatible /audio/transcriptions。
• 如果你只想用本機，可選「本機 Whisper」；如果只想用雲端，可選「OpenAI-compatible」；也可以停用語音轉文字。

Local Whisper 不需要雲端 API，但仍需要你在主機或容器環境中安裝可執行的 whisper 指令，且本機 CPU/GPU 要能負擔轉錄工作。

10. 備份、還原與隱私

你至少要知道三個位置：

• ~/.praetor/praetor：app source，可重新下載。
• ~/.praetor/data：本機私有狀態，應備份。
• ~/praetor-workspace：公司檔案，應備份。

刪除或移動 workspace 前，請先備份。若你使用 API provider，資料可能會送到該 provider；若你使用 dry-run demo provider，則不會呼叫外部模型。

更多細節：

• Backup and Restore
• Privacy Boundaries
• Deployment Security

11. 疑難排解

App 打不開

先檢查 Docker 是否正在執行，然後跑：

~/.praetor/praetor/scripts/praetor.sh doctor

找不到 workspace 檔案

確認你第一次設定時選的 workspace root。預設是：

~/praetor-workspace

API mode 沒有回應

檢查：

• API key 是否設定。
• provider 是否正確。
• 網路是否可連外。
• 是否有 pending approval。
• 是否達到 provider quota 或 billing 限制。

Codex executor 連不上

檢查：

• Host 上 Codex CLI 是否已登入。
• praetor-execd 是否正在執行。
• bridge token 是否一致。
• Docker container 是否能連到 bridge URL。

先使用 helper：

~/.praetor/praetor/scripts/praetor.sh configure-executor codex

如果你要使用 Claude Code，改用：

~/.praetor/praetor/scripts/praetor.sh configure-executor claude_code

Telegram 沒收到訊息

檢查：

• Bot token 是否正確。
• Public HTTPS URL 是否可用。
• Webhook secret 是否一致。
• Telegram account 是否已 pairing。
• Allowed Telegram user ID 是否填對。

12. 文件怎麼讀

一般使用者建議順序：

1. 本手冊。

2. Local Deploy。

3. ChatGPT Subscription Executor，只在你要用 Codex subscription executor 時閱讀。

4. Telegram CEO Access，只在你要用 Telegram 時閱讀。

5. Backup and Restore。

6. Privacy Boundaries。

維護者、貢獻者與產品設計者再閱讀 內部設計與維護文件索引。