Oysterun 讓 Codex 或 Claude Code 在你自己的 Mac 或 Linux 電腦上執行，並讓你透過 iPhone 或瀏覽器操作 Agent。本教學會從乾淨環境開始，帶你完成第一個可驗證的 Session。

1. 選擇執行 Host 的電腦

Host 是實際執行 Oysterun、Agent provider、專案檔案與 Agent process 的 Mac 或 Linux 電腦。你可以先用現在的電腦測試，之後再搬到長時間開機的 Mac mini、Mini PC 或 VPS。

作業系統：仍受支援的 macOS 或 Linux 版本。
Node.js：20 或更新版本。
記憶體：長時間運作的 Host 建議至少 2 GB。
Client：Oysterun iPhone App 或現代瀏覽器。
Provider：Codex 或 Claude Code，而且必須安裝並登入在將要執行 Oysterun 的同一個作業系統使用者。

設定期間，Oysterun 會詢問手機或瀏覽器要如何連到這台 Host。只在 Host 本機開瀏覽器時可用 localhost；兩台裝置位於可互通的同一網路時可用 LAN 位址；需要遠端連線時則使用既有的 VPN 或 tunnel 位址。不要把未受保護的 Oysterun port 直接暴露到公開網路。

檢查點

node --version
npm --version
whoami

確認 Node 顯示 20 或更新版本，並記住這個使用者；Provider 與 Oysterun 都要由同一個使用者執行。

2. 安裝並登入 Codex 或 Claude Code

選擇其中一個 Provider。如果已經由目前使用者安裝並登入，只要確認狀態即可繼續。

使用 Device Code 登入 Codex

npm install -g @openai/codex@latest
codex --version
codex login --device-auth
codex login status

開啟 Codex 顯示的裝置授權頁面，輸入當次的一次性 Device Code，並且只核准預期中的 OpenAI Codex 權限。不要公開或錄下 Device Code。

Claude Code

npm install -g @anthropic-ai/claude-code@latest
claude --version
claude auth login --claudeai
claude auth status

如果登入流程出現非預期帳號、scope、密碼、MFA、CAPTCHA 或要求略過安全警告，先停止並確認要求內容。

3. 安裝 Oysterun Host

使用相同作業系統使用者安裝 Oysterun。不要讓 Provider 與 Oysterun 分別由不同使用者或 root 執行。

npm install -g oysterun@latest --prefer-online
oysterun --version
oysterun

第一次執行時，oysterun 會發現設定尚未完成，自動開啟引導式設定。之後也可以用以下指令重新執行：

oysterun setup

4. 完成引導式設定

Host 名稱：設定用來辨識這台電腦的名稱。
Host port：除非 8802 已被使用，否則接受預設值。
連線 URL 與專案：選擇 Client 可以連到的 URL，再設定 Explorer 的 Default Browse Root。
Host 密碼：建立並再次確認瀏覽器登入密碼；輸入內容會隱藏。
Telemetry：決定是否分享有限範圍的每日診斷資料。
手機 App：需要時先開啟 Oysterun 下載頁面。
啟動 Host：接受預設啟動動作，等待 Host health 完成。

Default Browse Root 只是 Explorer 的起始位置。建立 Session 時，仍然需要明確選擇 Agent 的實際工作資料夾。

檢查點

設定完成後應該看到健康的 Host、你選擇的 Host URL，以及短效登入 QR 或密碼登入說明。在 SSH terminal 中，Oysterun 會顯示 URL，不會強制開啟遠端電腦上的瀏覽器。

5. 使用 iPhone App 或瀏覽器連線

如果要使用原生手機體驗，請先從 App Store 安裝 Oysterun。

App Store 上的 Oysterun App 頁面 — 顯示一次性 Host 登入 QR 之前，先完成 App 安裝。

手機：掃描 Host 啟動後顯示的 QR，然後開啟已儲存的 Host。
瀏覽器：開啟設定時選擇、而且目前裝置可連線的 Host URL，輸入 Host 密碼。

QR 是短效登入憑證，不應出現在截圖或錄影中。如果已經過期，可以在不重跑設定的情況下產生新 QR：

oysterun show-qr

6. 啟動第一個 Agent Session

建立或選擇一個你允許 Agent 存取的專案資料夾。
開啟 Sessions，選擇 New Session。
選擇 Codex 或 Claude Code。
將專案資料夾設為 Session Start Folder。
啟動 Session，先傳送一個小型驗證指令，例如：「列出這個資料夾中的檔案，並告訴我這個專案包含什麼。」
確認收到一則完整 Provider 回覆，再開始更大的任務。

顯示進行中 Agent Session 與操作控制的 Oysterun chat 頁面 — 同一個 Session 可以從手機 App 或 Host Web interface 開啟。

7. 檢查狀態與處理常見首次啟動問題

無法開啟 Host

oysterun service:status
oysterun service:logs

確認 service 正在執行。如果其他裝置無法連到 Host，先確認所選 URL 可由該裝置連線，再重跑 oysterun setup 選擇 LAN、VPN 或 tunnel 位址。

Provider 無法使用

codex login status
# 或
claude auth status

使用執行 Oysterun 的同一個作業系統使用者完成 Provider 登入，再建立新的 Session 或重新啟動原有 Session。

QR 已過期

oysterun show-qr

產生新的 QR，不要重用或分享錄影中的過期畫面。

接下來可以嘗試什麼

第一則回覆成功後，就可以開始真實專案任務。你可以透過 Oysterun 繼續 Session、停止失控工作、瀏覽 Agent 產生的檔案、開啟 HTML report 與網站、安排週期性工作，並在 Agent 需要你處理時收到通知。