Oysterun
返回使用指南

使用指南

一步一步設定 Oysterun

完整說明如何安裝 Oysterun、設定電腦、連接手機,並完成第一個工作對話與 Mail 報告。

本文目錄 文章開頭

這份指南會帶你完成第一個實用結果:

  • 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。終端機會標出七個步驟,文字如下:

  1. Host name — Name this Host 預設為 oysterun-<電腦名稱>。建議直接按 Enter 接受;也可以輸入另一個容易辨識的名稱。
  2. Project folders — Default Browse Root(Oysterun 可以瀏覽的最上層資料夾,你的專案資料夾都放在它底下)預設為 ~/OysterunAgents。建議直接按 Enter 接受,並把專案資料夾放在裡面。
  3. Host password — 設定瀏覽器和 App 使用的密碼。
  4. Managed connectivity — 這是不用固定 IP,也能從外面連到你的 Host 的連線技術。Setup 會註冊 Host,並分配 Managed Endpoint(Oysterun 分配給你的 Host 的專屬網址,在外面也能用它連回 Host)。
  5. Help improve Oysterun? — daily telemetry 是每天一次,把各功能的使用次數統計傳給 Oysterun,用來改善產品;只包含功能使用次數,不包含對話內容、檔案或密碼。這是選用功能;回答 Enable daily telemetry?,之後也能在 Host Preferences(Host 的設定頁)更改。
  6. Phone app — 準備配對 App 時,回答 Show phone app download link and QR code?。QR code 是手機相機可以掃描的方形圖案。
  7. 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;手機版先按左上角 >| 打開同一個側邊選單。

還沒有任何 Session 時顯示的畫面
還沒有任何 Session 時,No sessions yet 表示瀏覽器已透過 Managed Endpoint 進入新的 Host。Managed WebRTC 是連線狀態名稱;看到它表示已連線,不需要另外設定。OYSTERUN 功能磚裡有 New Session、Mail 和 Host Preferences。

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

在 Host Preferences 產生的登入 QR code
登入 QR code 會在 15 分鐘後失效。絕對不要把仍有效的登入 QR code 分享給任何人。
iPhone 模擬器上的 Oysterun App 登入畫面
App 可以輸入 Host 網址與密碼,也可以按 Scan QR code 開啟相機掃描畫面。

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:

  1. 選擇剛才登入的 Provider。
  2. 選擇可用的 Model,以及 Reasoning Effort(Agent 用多少時間與運算量思考)。
  3. 為 Agent 和 Session 取容易辨識的名稱。
  4. 選擇要交給 Agent 的確切專案資料夾。
  5. 保持勾選 Install/Overwrite Oysterun Skills(安裝或更新 Oysterun 說明檔)。它只會安裝或更新給 Agent 使用的 Oysterun 指令說明檔,不會覆寫專案檔案。
  6. 選擇 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。

Session Setup 裡已勾選 Oysterun Skills
第一個 Session 要保持勾選 Install/Overwrite Oysterun Skills。

先傳送一個範圍小、唯讀的要求:

只讀取這個專案,不要變更檔案。告訴我專案資料夾名稱,並用三個重點摘要內容。

準備傳送的第一個唯讀要求
範圍明確的第一個要求,請 Agent 讀取但不要變更檔案。

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

Codex 還在輸入時的第一個 Session
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 確認報告已送出。

手機:

  1. 按左上角 >| 開關打開側邊選單。
  2. 在 OYSTERUN 選 Mail(產品內信箱)。
  3. 在 Inbox(收件匣)最上方找到新報告。

桌面:

  1. 在左邊欄 OYSTERUN 選 Mail(產品內信箱)。
  2. 在 Inbox(收件匣)最上方找到新報告。

若 Agent 尚未確認送出,先等它完成;已確認但看不到時,再選一次 Mail 功能磚。若 Agent 回報缺少 Skills,macOS 按 ⌘⇧P,Windows 或 Linux 按 Ctrl+Shift+P,選 Open Session Profile(開啟 Session 設定頁)安裝或更新 Oysterun Skills,再重新要求傳送。Oysterun Mail 不是寄到外部的電子郵件。

Oysterun Mail Inbox 裡的第一份報告
Mail 功能磚會打開 Inbox,顯示新報告的標題和一句話摘要。
已開啟的 Getting Started Demo 報告
開啟 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。