# 一步一步設定 Oysterun

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

- **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。

## 確認系統需求 {#requirements}

執行 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，記憶體不足時才需要） {#add-linux-swap}

如果 Linux Host 只有 1 GB 記憶體，就需要至少 2 GiB 交換空間（swap）。它是硬碟上暫時當記憶體用的空間。若你不熟悉終端機管理指令，請交給管理這台電腦的人。先檢查目前狀態：

```bash
free -h
swapon --show
```

`/swapfile` 是提供交換空間的檔案；`/etc/fstab` 是記錄開機時要啟用哪些磁碟和交換空間的設定檔。如果 `/swapfile` 已存在，但沒有列在 `swapon --show`，請停止並檢查這兩處，不要覆寫它。如果檔案不存在，管理員可以執行：

```bash
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 {#install-oysterun-host}

請用你登入這台 Mac 或 Ubuntu 電腦時使用的帳號（不是 Oysterun 帳號）執行安裝程式。之後也用這個帳號執行 Host 和 Provider。Oysterun 終端機指令會放在 npm 為這個帳號準備的安裝資料夾。不要使用 `sudo npm install -g oysterun`。

```bash
curl -fsSL https://oysterun.com/install.sh | bash
```

成功時套件會完成準備並開啟 Setup（設定引導流程）。若失敗，請檢查能否下載、目前使用者是否可寫入畫面顯示的 npm 安裝資料夾，以及作業系統是否受支援。若安裝成功但 Setup 沒有開啟，請用同一個使用者執行 `oysterun setup`。

安裝程式會選擇目前的 Oysterun 版本，將 Oysterun 終端機指令安裝在目前使用者的 npm 安裝資料夾；如果還沒有設定，它會開啟 Host Setup 引導流程。

安裝程式會先顯示選定的版本與已準備好的套件，接著開始 Setup：

```terminal
  ✓ 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 {#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 會顯示類似以下內容；方括號裡的值來自你的電腦或選擇：

```terminal
[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](https://github.com/GoatWang/OysterunCore/issues) 回報，附上錯誤文字和系統版本，但絕對不要附密碼或 token（登入憑證）。只安裝終端機指令不算成功；還要能開啟顯示的 Managed Endpoint。

## 登入並配對手機 App {#browser-and-phone}

用一般瀏覽器開啟 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 時顯示的畫面](media/sessions-ready.png "還沒有任何 Session 時，No sessions yet 表示瀏覽器已透過 Managed Endpoint 進入新的 Host。Managed WebRTC 是連線狀態名稱；看到它表示已連線，不需要另外設定。OYSTERUN 功能磚裡有 New Session、Mail 和 Host Preferences。")

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

![在 Host Preferences 產生的登入 QR code](media/login-qr.png "登入 QR code 會在 15 分鐘後失效。絕對不要把仍有效的登入 QR code 分享給任何人。")

![iPhone 模擬器上的 Oysterun App 登入畫面](media/app-sign-in.png "App 可以輸入 Host 網址與密碼，也可以按 Scan QR code 開啟相機掃描畫面。")

App 也可以使用相同的 Host 網址和 Host 密碼。瀏覽器和手機是使用同一台 Host 和相同 Sessions 的兩種方式；配對手機不會建立另一台 Host。

如果顯示不同的 Host 名稱或網址，請關閉頁面，再從 Setup 成功輸出複製正確的 Managed Endpoint。若仍出現安全性警告，不要輸入密碼；到 [Oysterun Issues](https://github.com/GoatWang/OysterunCore/issues) 回報警告文字和系統版本，但不要附密碼、QR code 或 token。

如果密碼被拒絕，請回到登入畫面，重新輸入 Setup 設定的 Host 密碼。如果網址無法開啟，重新複製 Setup 成功輸出裡的 Managed Endpoint 並檢查網路；仍無法開啟時，執行 `oysterun setup` 並完成失敗的 Host 步驟。

## 安裝並登入一個 Provider {#choose-provider}

Provider 會在每個 Session 中執行 Agent。Oysterun 平等支援五種選擇；只要安裝其中一種就能繼續。請用執行 Host 的同一個作業系統帳號安裝。

### [Codex](https://developers.openai.com/codex/cli/) {#install-codex}

安裝：
```bash
npm install -g @openai/codex
```
執行下面的指令後，瀏覽器會打開；選 **Sign in with ChatGPT**，或你平常使用的登入方式。完成瀏覽器流程後回到終端機：
```bash
codex login
```
確認畫面顯示目前使用的登入方式：
```bash
codex login status
```

### [Claude Code](https://code.claude.com/docs/en/setup) {#install-claude-code}

安裝：
```bash
curl -fsSL https://claude.ai/install.sh | bash
```
執行下面的指令後，瀏覽器會打開；使用你的 Claude 帳號。終端機顯示 **Login successful** 後按 Enter：
```bash
claude auth login
```
確認狀態顯示已登入：
```bash
claude auth status --text
```

### [Grok](https://x.ai/cli) {#install-grok}

安裝：
```bash
npm install -g @xai-official/grok
```
執行下面的指令後，瀏覽器會打開；完成 Grok 登入後回到終端機：
```bash
grok login
```
再次打開 Grok；如果直接進入互動畫面，沒有要求登入，就表示已登入。離開後回到 Oysterun：
```bash
grok
```

### [Antigravity](https://antigravity.google/docs/getting-started?tab=cli) {#install-antigravity}

安裝：
```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
```
執行下面的指令後，瀏覽器會打開。依照 [Google 登入流程](https://antigravity.google/docs/install?tab=cli)，個人 Google 帳號選 Google OAuth，組織帳號則選組織使用的 Google Cloud 方式。完成瀏覽器流程後回到終端機：
```bash
agy
```
Antigravity 直接打開主畫面，標題列顯示帳號電子郵件而不是要求登入，就表示已登入。

Oysterun 沒有規定 Antigravity 的最低版本。

### [OpenCode](https://opencode.ai/docs/) {#install-opencode}

使用 OpenCode 官方安裝程式：
```bash
curl -fsSL https://opencode.ai/v2/install | bash
```
在終端機登入，並依照[OpenCode 官方登入說明](https://opencode.ai/docs/cli/providers)選擇模型服務（例如 OpenAI 或 Anthropic）和登入方式。若使用 OAuth（由瀏覽器授權的登入方式），完成瀏覽器或授權碼流程後回到終端機：
```bash
opencode auth login
```
確認清單裡出現剛才登入的模型服務：
```bash
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 {#first-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](https://github.com/GoatWang/OysterunCore/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](media/session-skills.png "第一個 Session 要保持勾選 Install/Overwrite Oysterun Skills。")

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

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

![準備傳送的第一個唯讀要求](media/first-prompt.png "範圍明確的第一個要求，請 Agent 讀取但不要變更檔案。")

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

![Codex 還在輸入時的第一個 Session](media/session-working.png "Typing 或 Working 都表示還在處理，不是最後答案。")

電腦版從側邊欄的 **Running Sessions**（正在執行的對話）開啟同一個 Session；手機版先按左上角 **>|** 打開側邊選單。若 Session 已停止，展開 **Stopped**，在該列點 **•••** 再選 **Resume Chat**（繼續對話）。確認 Session 名稱、Agent、專案資料夾和剛才的回覆都相同。要繼續同一份工作時，請打開這個 Session，不要重複建立一個新的。

## 收到第一份 Mail 報告 {#first-mail-report}

請該 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 裡的第一份報告](media/mail-inbox.png "Mail 功能磚會打開 Inbox，顯示新報告的標題和一句話摘要。")

![已開啟的 Getting Started Demo 報告](media/mail-report.png "開啟 Mail 項目即可閱讀完整的網頁格式報告。")

## 接下來讀什麼 {#what-to-read-next}

前往[使用指南](/guides/zh/index.html)，閱讀各項工作和功能的說明。

## 解除安裝 Oysterun {#uninstall-oysterun}

請用你登入這台 Mac 或 Ubuntu 電腦時使用的帳號（不是 Oysterun 帳號），在終端機先預覽確切的移除計畫：

```bash
oysterun uninstall --dry-run --confirm DELETE
```

繼續前先讀取 `--dry-run` 顯示的預覽內容。它必須是你準備移除的 Host 服務、設定和為這個使用者安裝的 Oysterun 終端機指令；只要有一項不符就停止。

要移除選定的 Host 服務、設定和同一份全域 Oysterun 終端機指令，請執行：

```bash
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](https://github.com/GoatWang/OysterunCore/issues) 回報，但不要附密碼或 token。
