這份指南會帶你完成第一個實用結果:
- Host(你自己電腦或伺服器上執行的 Oysterun 服務)。
- Session 是 Agent 在某個專案資料夾裡工作的對話。
- Agent 是替你在專案資料夾裡工作的 AI(人工智慧)助手。
- Provider 是執行 Agent 的 AI 工具,例如 Codex、Claude Code、Grok、Antigravity 或 OpenCode。
- Oysterun Mail 是接收 Agent 報告的產品內信箱。
你需要一台 Mac 或 Ubuntu(一種 Linux 系統)電腦、一個瀏覽器和一台安裝 Oysterun App(手機應用程式)的 iPhone。開始時只要安裝一個 Provider。
確認系統需求
執行 Oysterun Host 的電腦需要:
- macOS(用
sw_vers -productVersion檢查),或 Ubuntu 22.04 以上版本(用lsb_release -ds檢查); - 1 個處理器核心(畫面或規格可能寫作 vCPU);用
getconf _NPROCESSORS_ONLN檢查; - 2 GB 記憶體,或 1 GB 記憶體加上至少 2 GiB 交換空間(swap,也就是硬碟上暫時當記憶體用的空間);Ubuntu 可用
free -h檢查; - 10 GB 磁碟空間,更新時至少保留 2 GiB 可用空間;
- 可在安裝、登入和使用 Managed connectivity(不用固定 IP,也能從外面連到你的 Host 的連線技術)時連上網路;開啟
https://oysterun.com即可檢查。
GB 和 GiB 都是容量單位。用 df -h . 檢查磁碟空間。Node.js 是 Oysterun 執行時需要的工具,npm 是用來安裝 Oysterun 的工具;用 node -v && npm -v 檢查。安裝程式會處理 Node.js 22。Homebrew 是 Mac 上安裝軟體的工具;用 brew --version 檢查。如果 Node.js 22 和 Homebrew 都沒有,安裝程式會引導你安裝 Node.js。
新增 Linux 交換空間(swap,記憶體不足時才需要)
如果 Linux Host 只有 1 GB 記憶體,就需要至少 2 GiB 交換空間(swap)。它是硬碟上暫時當記憶體用的空間。若你不熟悉終端機管理指令,請交給管理這台電腦的人。先檢查目前狀態:
free -h
swapon --show
/swapfile 是提供交換空間的檔案;/etc/fstab 是記錄開機時要啟用哪些磁碟和交換空間的設定檔。如果 /swapfile 已存在,但沒有列在 swapon --show,請停止並檢查這兩處,不要覆寫它。如果檔案不存在,管理員可以執行:
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
grep -qF '/swapfile none swap sw 0 0' /etc/fstab || echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h
swapon --show
建立交換空間需要管理員權限,因此 Oysterun 不會自動建立。
成功時,swapon --show 會列出約 2G 的 /swapfile,而 free -h 的 Swap 列約為 2.0Gi。若指令失敗或結果不同,請停止,不要重跑或覆寫既有交換空間檔案;請電腦管理員或 Ubuntu 支援人員檢查 /swapfile 和 /etc/fstab。
安裝 Oysterun
請用你登入這台 Mac 或 Ubuntu 電腦時使用的帳號(不是 Oysterun 帳號)執行安裝程式。之後也用這個帳號執行 Host 和 Provider。Oysterun 終端機指令會放在 npm 為這個帳號準備的安裝資料夾。不要使用 sudo npm install -g oysterun。
curl -fsSL https://oysterun.com/install.sh | bash
成功時套件會完成準備並開啟 Setup(設定引導流程)。若失敗,請檢查能否下載、目前使用者是否可寫入畫面顯示的 npm 安裝資料夾,以及作業系統是否受支援。若安裝成功但 Setup 沒有開啟,請用同一個使用者執行 oysterun setup。
安裝程式會選擇目前的 Oysterun 版本,將 Oysterun 終端機指令安裝在目前使用者的 npm 安裝資料夾;如果還沒有設定,它會開啟 Host Setup 引導流程。
安裝程式會先顯示選定的版本與已準備好的套件,接著開始 Setup:
✓ Oysterun release selected: [current version] ([release channel])
✓ Package prepared: [current version]; running Host qualification follows onboarding.
- Oysterun release selected: … (release channel):已選好要安裝的版本和發布管道。
- Package prepared … running Host qualification follows onboarding:套件已準備完成;接下來會在設定流程中檢查 Host。
完成 Host Setup
Setup 不需要先安裝 Provider。終端機會標出七個步驟,文字如下:
- Host name — Name this Host 預設為
oysterun-<電腦名稱>。建議直接按 Enter 接受;也可以輸入另一個容易辨識的名稱。 - Project folders — Default Browse Root(Oysterun 可以瀏覽的最上層資料夾,你的專案資料夾都放在它底下)預設為
~/OysterunAgents。建議直接按 Enter 接受,並把專案資料夾放在裡面。 - Host password — 設定瀏覽器和 App 使用的密碼。
- Managed connectivity — 這是不用固定 IP,也能從外面連到你的 Host 的連線技術。Setup 會註冊 Host,並分配 Managed Endpoint(Oysterun 分配給你的 Host 的專屬網址,在外面也能用它連回 Host)。
- Help improve Oysterun? — daily telemetry 是每天一次,把各功能的使用次數統計傳給 Oysterun,用來改善產品;只包含功能使用次數,不包含對話內容、檔案或密碼。這是選用功能;回答 Enable daily telemetry?,之後也能在 Host Preferences(Host 的設定頁)更改。
- Phone app — 準備配對 App 時,回答 Show phone app download link and QR code?。QR code 是手機相機可以掃描的方形圖案。
- Start Host — Setup 會安裝並啟動 Host 服務。Ubuntu 還會顯示伺服器重開後,Host 是否會自動啟動。
Setup 會顯示類似以下內容;方括號裡的值來自你的電腦或選擇:
[1/7] Host name
? Name this Host [oysterun-<computer name>]:
[2/7] Project folders
Default Browse Root [~/OysterunAgents]:
[3/7] Host password
[4/7] Managed connectivity
Registering with backend at https://api.oysterun.com...
Allocating Oysterun Managed Endpoint...
[5/7] Help improve Oysterun?
? Enable daily telemetry? (Y/n)
✓ Cloud registration complete
Oysterun Managed Endpoint: [your Host URL]
[6/7] Phone app
? Show phone app download link and QR code? (y/N)
[7/7] Start Host
Installing LaunchAgent and starting Oysterun Host ([Host name])...
✓ Oysterun Host is running at [local Host URL]
Oysterun is ready.
Config: [Host config path]
Host URL: [Managed Host URL]
Host configuration, Cloud identity, service health, and endpoint were verified.
[Ubuntu 接著只會顯示以下其中一種結果:]
Start at boot: enabled. The Host starts by itself after this server restarts.
Start at boot: not enabled yet. Run this once, then the Host starts by itself after a restart:
sudo loginctl enable-linger [你的 Ubuntu 帳號]
Start at boot: not set up. Run Setup again (or the installer with --reinstall) to set it up.
Start at boot: this system does not support it (no systemd). After a restart, run: oysterun service:start
重要英文輸出的意思:
- Registering with backend:正在向 Oysterun 的後端服務登記這台 Host。
- Cloud registration complete:雲端登記已完成。
- Installing LaunchAgent and starting Oysterun Host:正在安裝 Mac 的背景啟動項目並啟動 Host。
- Oysterun Host is running 和 Oysterun is ready:Host 已啟動並可使用。
- Config: …:後面是 Host 設定檔的位置。
- Host URL: …:後面是從外面連到這台 Host 的網址。
- Host configuration, Cloud identity, service health, and endpoint were verified:設定、雲端身分、程式狀態和外部網址都已通過檢查。
Ubuntu 只會顯示一種 Start at boot(伺服器重開後自動啟動)結果:
- enabled(已開啟):不用再操作。
- not enabled yet(尚未開啟):貼上畫面顯示的
sudo loginctl enable-linger [你的 Ubuntu 帳號],再按 Enter。若系統要求密碼,輸入你登入這台 Ubuntu 電腦使用的密碼;輸入時畫面不會顯示。接著執行loginctl show-user [你的 Ubuntu 帳號] -p Linger;看到Linger=yes就成功了。 - not set up(尚未設定):執行
oysterun setup再跑一次 Setup,或使用--reinstall重新執行安裝程式,再依新的結果處理。 - this system does not support it (no systemd)(這個系統不支援):每次伺服器重開後,執行
oysterun service:start。
macOS 不會顯示這段 Ubuntu 專用結果。
在引導流程中,Setup 會顯示 Host 網址。Host 網址和 Host 密碼都要保密。登入 QR code(二維碼)可能包含暫時登入資訊,因此絕對不要把仍有效的 QR code 發佈到文件或聊天中,也不要保存它。
如果看不到 Oysterun is ready,記下最後一個錯誤,再執行 oysterun setup 完成未成功的步驟。下載、權限或作業系統問題請回到安裝段落逐項檢查;其他錯誤可到 Oysterun Issues 回報,附上錯誤文字和系統版本,但絕對不要附密碼或 token(登入憑證)。只安裝終端機指令不算成功;還要能開啟顯示的 Managed Endpoint。
登入並配對手機 App
用一般瀏覽器開啟 Host 網址,以 Host 密碼登入。電腦版在左邊欄 OYSTERUN 選 Host Preferences;手機版先按左上角 >| 開關打開側邊選單,再選 Host Preferences。在 Host Identity And Browse Root(Host 識別資訊和瀏覽根目錄)下比較 Host Display Name(Host 顯示名稱)和 Setup 時輸入的名稱。
還沒有任何 Session 時,這個畫面會顯示 No sessions yet。建立第一個 Session 後,登入會直接打開上次的對話。電腦版從側邊欄的 Running Sessions 找到所有 Session;手機版先按左上角 >| 打開同一個側邊選單。

安裝 Oysterun iOS App。掃描 Setup Phone app 步驟顯示的新登入 QR code(手機相機可以掃描的方形圖案)。之後要重新產生時,從 OYSTERUN 功能磚(手機版是側邊選單)打開 Host Preferences → Connection(連線設定)→ Login QR code(登入二維碼),再選擇 Generate Login QR(產生登入二維碼)。每個登入 QR code 會在 15 分鐘後失效;請等手機準備掃描時再產生。


App 也可以使用相同的 Host 網址和 Host 密碼。瀏覽器和手機是使用同一台 Host 和相同 Sessions 的兩種方式;配對手機不會建立另一台 Host。
如果顯示不同的 Host 名稱或網址,請關閉頁面,再從 Setup 成功輸出複製正確的 Managed Endpoint。若仍出現安全性警告,不要輸入密碼;到 Oysterun Issues 回報警告文字和系統版本,但不要附密碼、QR code 或 token。
如果密碼被拒絕,請回到登入畫面,重新輸入 Setup 設定的 Host 密碼。如果網址無法開啟,重新複製 Setup 成功輸出裡的 Managed Endpoint 並檢查網路;仍無法開啟時,執行 oysterun setup 並完成失敗的 Host 步驟。
安裝並登入一個 Provider
Provider 會在每個 Session 中執行 Agent。Oysterun 平等支援五種選擇;只要安裝其中一種就能繼續。請用執行 Host 的同一個作業系統帳號安裝。
Codex
安裝:
npm install -g @openai/codex
執行下面的指令後,瀏覽器會打開;選 Sign in with ChatGPT,或你平常使用的登入方式。完成瀏覽器流程後回到終端機:
codex login
確認畫面顯示目前使用的登入方式:
codex login status
Claude Code
安裝:
curl -fsSL https://claude.ai/install.sh | bash
執行下面的指令後,瀏覽器會打開;使用你的 Claude 帳號。終端機顯示 Login successful 後按 Enter:
claude auth login
確認狀態顯示已登入:
claude auth status --text
Grok
安裝:
npm install -g @xai-official/grok
執行下面的指令後,瀏覽器會打開;完成 Grok 登入後回到終端機:
grok login
再次打開 Grok;如果直接進入互動畫面,沒有要求登入,就表示已登入。離開後回到 Oysterun:
grok
Antigravity
安裝:
curl -fsSL https://antigravity.google/cli/install.sh | bash
執行下面的指令後,瀏覽器會打開。依照 Google 登入流程,個人 Google 帳號選 Google OAuth,組織帳號則選組織使用的 Google Cloud 方式。完成瀏覽器流程後回到終端機:
agy
Antigravity 直接打開主畫面,標題列顯示帳號電子郵件而不是要求登入,就表示已登入。
Oysterun 沒有規定 Antigravity 的最低版本。
OpenCode
使用 OpenCode 官方安裝程式:
curl -fsSL https://opencode.ai/v2/install | bash
在終端機登入,並依照OpenCode 官方登入說明選擇模型服務(例如 OpenAI 或 Anthropic)和登入方式。若使用 OAuth(由瀏覽器授權的登入方式),完成瀏覽器或授權碼流程後回到終端機:
opencode auth login
確認清單裡出現剛才登入的模型服務:
opencode auth list
Oysterun 沒有規定 OpenCode 的最低版本。
如果第一個 Oysterun Session(工作對話)顯示 Login required,請回到這一節,重新登入該工具。
登入後,從電腦版側邊欄的 OYSTERUN 功能磚選 New Session 開啟 Session Setup。手機版先按左上角 >| 開關打開側邊選單。Mac 也可按 ⌘⇧P 打開指令選單,再選 Open New Session。選擇該 Provider,再按 Refresh provider models(重新尋找 Provider 和模型)。Model(模型)是 Provider 用來回答和工作的 AI 版本。Host 已在執行時,這個按鈕會尋找剛安裝的 Provider 執行程式和模型;如果不按,要等到下一次 Host 啟動才會自動找到。
- Installed: version … (found automatically):已找到可用版本,可以繼續。
- Not installed:尚未找到;先依上表安裝並登入,再按 Refresh provider models。
- Update required: …:版本太舊;依該 Provider 的官方連結更新,再按 Refresh provider models。
建立第一個 Session
從電腦版側邊欄的 OYSTERUN 選 New Session。手機版先以 >| 打開側邊選單。這會開啟 Session Setup:
- 選擇剛才登入的 Provider。
- 選擇可用的 Model,以及 Reasoning Effort(Agent 用多少時間與運算量思考)。
- 為 Agent 和 Session 取容易辨識的名稱。
- 選擇要交給 Agent 的確切專案資料夾。
- 保持勾選 Install/Overwrite Oysterun Skills(安裝或更新 Oysterun 說明檔)。它只會安裝或更新給 Agent 使用的 Oysterun 指令說明檔,不會覆寫專案檔案。
- 選擇 Start Session。
成功時會開啟新的對話,並在側邊欄的 Running Sessions 列出它。若無法啟動:Not installed 先安裝並登入;Update required 先更新;沒有 Model 時按 Refresh provider models;資料夾錯誤時選擇 Default Browse Root 裡的專案。其他啟動錯誤可到 Oysterun Issues 回報錯誤文字和系統版本,但不要附密碼或 token。
如果現有 Session 缺少產品 Skills,請開啟該 Session,macOS 按 ⌘⇧P,Windows 或 Linux 按 Ctrl+Shift+P,再選擇 Open Session Profile。在 Oysterun Skills 選擇 Install/Update Oysterun Skills,再請 Agent 使用 Mail。

先傳送一個範圍小、唯讀的要求:
只讀取這個專案,不要變更檔案。告訴我專案資料夾名稱,並用三個重點摘要內容。

等待最後回覆。Connected(已連線)只表示瀏覽器或 App 已連到 Host;Typing(正在輸入)或 Working(正在處理)表示 Agent 還沒完成。完整回覆出現在對話最下方,而且 Typing/Working 消失後,工作才算完成。

電腦版從側邊欄的 Running Sessions(正在執行的對話)開啟同一個 Session;手機版先按左上角 >| 打開側邊選單。若 Session 已停止,展開 Stopped,在該列點 ••• 再選 Resume Chat(繼續對話)。確認 Session 名稱、Agent、專案資料夾和剛才的回覆都相同。要繼續同一份工作時,請打開這個 Session,不要重複建立一個新的。
收到第一份 Mail 報告
請該 Session 裡的 Agent 把結果整理成簡短報告,並透過 Oysterun Mail Skill(讓 Agent 學會使用 Oysterun 功能的說明檔)傳送:
請用剛才的專案摘要建立一份簡短的網頁格式(HTML)報告。使用清楚的標題和一句話摘要,不要包含私人資料,並使用 Oysterun Mail Skill 傳送到我的 Oysterun Mail。
等 Agent 確認報告已送出。
手機:
- 按左上角 >| 開關打開側邊選單。
- 在 OYSTERUN 選 Mail(產品內信箱)。
- 在 Inbox(收件匣)最上方找到新報告。
桌面:
- 在左邊欄 OYSTERUN 選 Mail(產品內信箱)。
- 在 Inbox(收件匣)最上方找到新報告。
若 Agent 尚未確認送出,先等它完成;已確認但看不到時,再選一次 Mail 功能磚。若 Agent 回報缺少 Skills,macOS 按 ⌘⇧P,Windows 或 Linux 按 Ctrl+Shift+P,選 Open Session Profile(開啟 Session 設定頁)安裝或更新 Oysterun Skills,再重新要求傳送。Oysterun Mail 不是寄到外部的電子郵件。


接下來讀什麼
前往使用指南,閱讀各項工作和功能的說明。
解除安裝 Oysterun
請用你登入這台 Mac 或 Ubuntu 電腦時使用的帳號(不是 Oysterun 帳號),在終端機先預覽確切的移除計畫:
oysterun uninstall --dry-run --confirm DELETE
繼續前先讀取 --dry-run 顯示的預覽內容。它必須是你準備移除的 Host 服務、設定和為這個使用者安裝的 Oysterun 終端機指令;只要有一項不符就停止。
要移除選定的 Host 服務、設定和同一份全域 Oysterun 終端機指令,請執行:
oysterun uninstall --confirm DELETE
Default Browse Root、Agent 資料夾、專案、Node.js、npm 和不相關的全域套件都會保留。如果要移除 Host 服務但保留 Oysterun 設定和終端機指令,請改用 oysterun uninstall --keep-config;不要和 --confirm DELETE 一起使用。
成功時會顯示 Complete uninstall succeeded: service removed, configuration removed, CLI removed; user data preserved.,意思是 Host 程式、設定和 Oysterun 終端機指令已移除,使用者資料保留。Complete uninstall failed at … 表示在標出的步驟失敗,移除尚未完成;移除前檢查錯誤表示 Oysterun 無法確認要移除的檔案或權限。保留完整輸出,依標出的步驟修正;無法判斷時到 Oysterun Issues 回報,但不要附密碼或 token。