首次設定

首次啟動的步驟順序為：Environment、Data location、Agent runtime、Model provider、Notebook runtime。底部 Back 和主操作按鈕負責移動步驟；只有當前步驟達到可繼續條件時，主操作才可用。

閱讀平臺

macOSWindowsLinux

選擇會在章節間保留。

首次設定完成後，較舊的應用管理 Codex 執行時可在 Agent 設定更新。這與選擇模型提供方是兩項操作。

1. Environment

首次啟動進入 Prepare environment。應用先檢查電腦環境，再讓你安裝智慧體或連線模型。每一行都有狀態和解釋；某項失敗時，應先根據該行資訊定位原因。

檢查項或控制元件	含義	操作方法
System compatibility	檢查作業系統和處理器架構	確認識別結果與你的電腦一致
App storage permission	檢查應用配置目錄的寫入權限	失敗時處理所示路徑的權限，再重新檢查
Secure credential storage	檢查作業系統憑據庫是否可用	先解決憑據庫存取問題，再填寫金鑰
Installation network	檢查受支援的軟體包來源並顯示可訪問來源	閱讀來源與延遲；實際結果隨網路環境變化
Check again	重新執行環境檢查	檢查期間變為 Checking… 並禁用，避免重複發起
Continue	進入資料位置設定	必需檢查透過後可用，檢查過程中禁用

開啟 Environment 步驟，閱讀四項結果，點選 Check again，等待底部出現 All required environment checks passed.，再點選 Continue。這一步環境檢查不需要 API key 或付費模型呼叫；模型認證在後續步驟配置。

選擇空間充足的穩定資料位置，不要把截圖中的臨時路徑用於長期儲存。應用使用英文時，系統原生檔案選擇器仍可能使用作業系統語言。

閱讀每行檢查的結果和說明。若某項標為 Ready，仍需閱讀說明；例如使用已有代理時，安裝網路檢查可能無需下載檔案，並不代表所有外部服務都已連通。

2. Data location

在安裝執行時之前確定大型檔案的存放位置。產物、Notebook 和環境使用資料目錄；配置和歷史記錄留在配置位置。頁面顯示的路徑是隻讀摘要，不能直接在其中輸入。

控制元件	操作和結果
Location／路徑顯示	展示預設資料目錄，或你剛選定的目標目錄
Browse…	開啟系統目錄選擇器；選擇父資料夾後，回到頁面檢查最終的應用管理路徑
系統選擇器 Cancel	取消本次選擇，保留此前路徑
Use default location instead	選過自定義目錄後出現；清空自定義選擇及相關錯誤
Back	返回 Environment
保持預設位置時點選 Continue	進入 Agent runtime
選過新位置後點選 Continue	開啟 Restart to set up your data?，不會靜默切換目錄
Retry	預設位置讀取失敗時出現，用於重新讀取

點選 Browse…，在空間充足的磁碟上選擇空父資料夾，檢查嚮導顯示的完整受管理路徑。選擇 Continue 並閱讀重啟確認。研究資料應放在穩定位置，不要使用臨時目錄。

確認框控制元件	結果
關閉按鈕 ×	返回位置頁，並保留剛選的路徑
Keep default	清除剛選的路徑，以預設位置繼續下一步
Restart	啟用所選資料位置並重啟應用；重啟後繼續 Agent runtime

應用會先檢查目標資料夾。已有且可識別的資料目錄可以原地接管，頁面會說明沒有搬移資料；不可用目錄會顯示錯誤。啟用或重啟失敗時可顯示錯誤，並允許重試或使用預設位置。不要手動搬動或改名應用管理的資料資料夾。

接管已有資料目錄

1. 選擇 Browse…，選中包含已識別應用資料目錄的父資料夾。
2. 確認提示 This folder already contains Open Science data — it will be used as-is (nothing is moved).，核對完整路徑後選擇 Continue → Restart。
3. 重啟後向導續接到 Agent runtime，所選資料位置保留，再完成後續設定。

接管後開啟代表性檔案，確認所需資料仍在。接管針對大檔案儲存，不會匯入另一安裝的設定、會話資料庫或憑據。Keep default 清除擬用位置並繼續使用原生效位置。

資料位置無法儲存時如何恢復

若提示 Could not finish setting up storage: EACCES: permission denied，先看報錯指向的路徑。配置目錄同樣需要可寫；只選擇可寫的資料目標目錄未必能解決問題。恢復受影響的應用專用配置位置訪問權限後，可重試，或選擇 Use default location instead → Continue。

如果重啟在新位置生效前失敗，恢復應用配置目錄的寫入權限後重新開啟向導。先核對當前生效路徑並開啟已有檔案，再決定是否重試切換位置。具體檢查見儲存與歸檔內容。

3. Agent runtime

選擇執行會話的 Agent 後端。可使用檢測到的已安裝框架，也可下載由應用管理的副本。狀態就緒後繼續。

1. 開啟 Install Codex。
2. 選擇選單推薦的應用管理安裝來源；另一種來源使用全域 npm 安裝。
3. 等待安裝完成，期間不要啟動另一個安裝任務。
4. 確認 Codex 顯示版本號和 Active。
5. 選擇 Continue 進入 Model provider。

版本標籤指的是已安裝代理或介面卡，不是所選模型；核對實際安裝值，無需與截圖版本完全相同。

控制元件或狀態	行為
框架卡片	顯示安裝狀態、版本、執行時路徑和活動狀態
Install…	展示該框架支援的安裝來源
安裝進度	顯示準備狀態；安裝期間不能啟動衝突的安裝操作或重新檢測
Re-detect	重新整理執行時檢測資訊，檢查期間變為 Detecting…。也可在 Settings → Agent 中重新檢測
Uninstall	活動執行時不可解除安裝；需先切換到另一個已安裝框架
Back	沒有阻塞的安裝操作時，返回 Data location
Continue	活動執行時就緒後進入下一步

各框架的安裝來源、切換、修復和解除安裝方法見安裝與切換代理框架。

4. Model provider

表單會根據 Provider type、活動代理和認證方式變化。使用 Codex 訂閱時，Import existing Codex sign-in 會將本機已有登入複製到 Open-Science。需要連線該賬號時選擇匯入，再等待連線檢查。

使用 API 提供商時，選擇型別，填寫其要求的端點和模型資訊，然後選擇 Test & continue。嚮導先檢查必填欄位，再執行連線測試。測試成功後推進嚮導；輸入或連線錯誤會保留在表單中供修改。

認證方式、高階欄位及連線失敗的處理見提供方設定。

API Key 只填寫在專用憑據欄位中，不放入截圖、專案指令或對話訊息。

5. Notebook runtime

最後一步為可選設定，複用完整的 Settings → Runtimes 介面。預設使用應用管理的 Python，也可以選擇已檢測到的直譯器，或稍後配置其他環境。

嚮導控制元件或狀態	操作結果
Back	返回 Model provider。執行時準備中或正在完成設定時禁用
Finish	儲存初始設定完成狀態。Notebook 配置可選，不要求先準備好自定義直譯器
已啟動環境準備	等待完成或先取消準備任務；期間 Back 與 Finish 禁用，避免遺留半成品環境
完成失敗	顯示錯誤，並允許重試

選擇 Finish，確認首頁開啟，再按首次專案建立小專案並儲存結果。重新開啟應用，確認專案仍可訪問。若向導意外重新出現，先檢查資料位置和配置寫入錯誤，不要立即新建另一套配置。

設定後的驗收清單

檢查項	應看到的證據	失敗時處理
Environment	必需檢查透過	解決具體要求後重新檢查
Data location	最終託管路徑符合預期	回到路徑頁檢查，不能只憑選擇器裡的父目錄判斷
Agent	已安裝版本與 Active 狀態	檢視安裝日誌並重新檢測
Provider	連線已驗證，主模型已選擇	檢查登入或提供方專有欄位
Notebook	需要程式碼執行時，執行時 Ready 且已啟用	先配置 Settings → Runtimes
首個任務	有代理回覆與可開啟的儲存結果	分別檢查權限、工具錯誤和模型連線

重新配置

完成引導後不需要重新執行 wizard：Model、Agent、Runtimes、Storage 分別對應上述設定。若資料目錄損壞或應用配置目錄不可寫，Settings → Storage 會顯示修復入口。

原始碼依據

OnboardingWizard.tsx, EnvironmentStep.tsx, LocationStep.tsx.