# 選擇 Session 資料夾並控制設定是否儲存

選擇範圍明確的 Start Folder、在 Folder Picker 取消或確認時保留設定草稿，並判斷 Session 設定只套用一次或寫入專案設定。

使用 Session Setup 選擇範圍明確的任務根目錄；瀏覽資料夾時保留其他設定草稿，並決定可儲存的設定只套用於這次啟動，或跟著專案保存。

安全結果：

選擇

Start Session

前，畫面上的

Start Folder

是你預期的明確任務資料夾、provider 設定仍正確，而且設定檔選項符合你是否要讓未來的 Session 重用這些設定。啟動後，

Working Directory

與

Workspace Policy Root

都指向同一個資料夾。

## 1. 準備範圍明確的任務資料夾

從 Oysterun 的 **Sessions** 頁面開始。你必須能存取預期的 Host，而且該 Host 必須能讀取現有的任務資料夾。

1. 把本次工作需要的檔案集中在一個範圍明確的資料夾。
1. 不要只為了方便設定，就選擇磁碟根目錄、整個家目錄，或範圍很大的共用上層資料夾。
1. 確認你要使用的 provider 已經可在這個 Host 上使用。

目前的資料夾保護限制：

正常產品刻意不提供並隱藏

Allowed Paths

。縮小 Start Folder 可以清楚表達預期工作範圍，但它不是與 provider 無關的安全邊界。仍要檢查 provider 的權限請求；如果請求出現非預期路徑，就停止操作。

## 2. 了解畫面上哪些設定優先

全新的 Session Setup 依照以下順序組合設定：

1. **Host 預設值**先填入新表單，包括預設 Browse Root 與 runtime。
1. 所選資料夾中的**專案設定**可以提供共用的 Session 預設值。
1. **你目前在 Session Setup 選擇的值**是這次啟動使用的值。即將生效的草稿，以表單上看得到的值為準。

共用的專案設定屬於 `.oysterun/config.json`。密碼、token 與其他私密值不應寫入這個檔案。之後若在 **Session Profile** 只做 runtime 變更，預設只影響執行中的 Session；必須明確選擇該區域的 update-config 選項，才會影響未來設定。

## 3. 開啟 Session Setup 並檢查草稿

1. 在 **Sessions** 選擇 **New Session**。
1. 確認頁面標題是 **Session Setup**。
1. 檢查 **Agent ID**、**Session Name**、**Agent Runtime**、**Model**、reasoning 與 **Start Folder**。
1. 如果這個 Session 不採用目前顯示的預設值，現在就調整 provider 欄位。

**檢查點：**開啟 Folder Picker 前，你能說出草稿中顯示的完整 Start Folder、Agent ID、Session Name、provider、model 與 reasoning 值。

![Session Setup 顯示 Agent ID、Session Name、完整任務 Start Folder、Choose folder 控制項，並已選擇 Codex Agent Runtime。](../assets/publication/session-setup-confirmed.png)

畫面 checkpoint：確認後的 Session Setup 同時顯示 identity 欄位、完整任務資料夾、資料夾控制項與已選擇的 Codex runtime。

## 4. 確認或取消資料夾選擇，而且不遺失草稿

只瀏覽資料夾不會確認選擇。使用 **Go back** 取消並回到同一份草稿；若要確認目前顯示的資料夾，則使用 breadcrumb 旁的三角形 **Use this folder** 動作。

![Folder Picker 聚焦在任務資料夾，並顯示完整 breadcrumb、Go back 控制項與三角形 Use this folder 動作。](../assets/publication/folder-picker-focused.png)

畫面 checkpoint：完整 breadcrumb 指出目前的任務資料夾；Go back 會取消，而三角形 Use this folder 動作會確認畫面上的資料夾。

### 取消 Folder Picker

1. 使用 **Start Folder** 旁的 **Choose folder** 控制項。
1. 在 **Folder Picker** 中瀏覽其他資料夾；你也可以只是檢查內容。
1. 若要取消，使用頂端列的 **Go back** 控制項，不要選擇 **Use this folder**。

**取消檢查點：**回到 Session Setup 後，Start Folder、Agent ID、Session Name、provider、model 與 reasoning 都沒有改變。只在 Folder Picker 裡瀏覽，不會確認任何選擇。

### 確認預期的資料夾

1. 再次開啟 **Choose folder**，前往範圍明確的任務資料夾。
1. 對那個正確資料夾選擇 **Use this folder**。
1. 回到 Session Setup 後，閱讀完整的 **Start Folder** 值，不要只看路徑最後一段名稱。
1. 如果 Agent ID 或 Session Name 是由 Oysterun 根據資料夾產生，請再次檢查；也要重查你輸入的 provider、model 與 reasoning。

**確認檢查點：**Start Folder 現在顯示預期的資料夾。**Use this folder** 只更新 Session Setup 草稿；它本身不會啟動 Session，也不會寫入專案設定。

## 5. 決定是否儲存設定

Session Setup 的啟動動作是 **Start Session**。使用前先看清楚設定檔 checkbox 的標籤；它的含義取決於所選資料夾是否已經有共用設定檔。標籤說明的是勾選後會採取的動作。

### 資料夾已有 `.oysterun/config.json`

- 勾選 **Update .oysterun/config.json**，把符合資格的共用值儲存給之後的 Session。
- 不要勾選，則畫面上的選擇只用於這次啟動，既有的共用設定檔不會改變。

### 資料夾沒有共用設定檔

- 標籤會改成 **Do not create .oysterun/config.json**。
- 正常預設行為是不勾選：Session 啟動時會建立共用設定檔。
- 如果這次啟動必須讓共用設定檔維持不存在，才勾選它。

若要取消整個設定流程，直接離開 Session Setup，不要選擇 **Start Session**。草稿中的資料夾選擇不等於持久儲存。

## 6. 啟動一次，並驗證所選 Root

1. 最後再次檢查完整 Start Folder 與設定檔選項。
1. 選擇 **Start Session**。
1. 無論使用桌面或手機，Session 聊天開啟後，先使用頂端列的 **More Options** 控制項（垂直省略號），再選擇 **Session Profile**。
1. 確認 **Working Directory** 是你選擇的完整 Start Folder。
1. 在 **Workspace Policy** 中，確認 **Root** 顯示同一個完整資料夾。

![同一個 Session 的 Session Profile 顯示完整 Working Directory 與完全一致的 Workspace Policy Root。](../assets/publication/session-profile-root.png)

畫面 checkpoint：同一個 Session 把同一條完整任務路徑同時顯示為 Working Directory 與 Workspace Policy Root。

最終檢查點：

執行中的 Session 把預期資料夾同時顯示為 Working Directory 與 Workspace Policy Root，而且你知道符合資格的共用設定是只用於這次啟動、已更新、已新建，或刻意維持不存在。

## 安全復原與停止條件

- **Folder Picker 無法開啟資料夾：**回到 Sessions，確認 Host 能讀取該資料夾，或選擇另一個你有權限使用、範圍明確的資料夾。
- **取消後草稿改變：**不要啟動。回到 Sessions，開啟全新的 New Session，再做一次取消檢查；目前產品預期會保留草稿。
- **設定檔選項不符合你的目的：**在 Start Session 前修正。不要把手動編輯 runtime 檔案當作主要復原方式。
- **Session Profile 顯示不同的 Root：**不要進行檔案操作。停止使用該 Session，並用預期的 Start Folder 建立新 Session。
- **畫面出現 Allowed Paths：**不要把它當成有效的資料夾保護。目前產品只把它當作診斷用介面。

**安全停止：**完整路徑、可見的 provider 設定與設定檔選項尚未全部正確前，不要選擇 Start Session。