> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 設定 AI

通過便宜、快速和智慧模型別名連線真實模型；金鑰始終留在伺服器。

## 安裝與配置

在執行任何步驟之前，請閱讀[開始之前](https://supastack.dev/zh-tw/docs/web/before-you-start.md) 和[終端基礎知識](https://supastack.dev/zh-tw/docs/web/terminal-basics.md)。這些說明假設您在 VS Code 中開啟了完整的 supastack monorepo；它的根 package.json 標記儲存庫根。在 pnpm 命令中，工作區包是應用程式或共享程式碼資料夾；在產品中，工作空間是團隊的資料容器和安全邊界。 corepack pnpm --filter ... 從 monorepo 選擇一個包，同時從其根執行命令。如果您僅開啟同步的移動或桌面資料夾，則它不包含 Web 後端、Docker 設定或根指令碼：從此 monorepo 或可訪問的託管伺服器執行後端，並使用平臺資料夾自己的指令碼。環境變數是儲存在本地 .env 檔案或託管儀錶板中的命名設定；更改後重新啟動相關應用程式，並將伺服器機密保留在 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值之外。

1. 本地Web伺服器開啟apps/web/.env.local，提供商選擇開啟apps/web/src/agent-runtime.ts； .env.example 是支援的設定名稱列表。

2. 保留 AI_PROVIDER=fake 用於本地介面工作，除非您有自己的提供商帳戶並想要測試真實生成；切勿將提供程式金鑰放入 NEXT_PUBLIC_ 或 EXPO_PUBLIC_ 設定中。

3. 使用 corepack pnpm --filter @supastack/web dev 從儲存庫根啟動 Web 應用程式。預期：無需配置付費提供商即可探索本地螢幕；實際生成需要有效的伺服器提供程式並在資料庫目錄中啟用模型選擇。

預設的 AI_PROVIDER=fake 支援本地確定性工作。真實供應商配置屬於服務端環境。.env.example 中列出的供應商金鑰包括 OpenAI、Anthropic 與一個 OpenAI 相容端點。

AI_MODEL_POLICY 包含 cheap、fast、smart 別名的有序模型 ID。空的別名列表會停用該選項。模型 ID 必須對應資料庫目錄中已啟用且帶有有效不可變價格的條目。

```
AI_MODEL_POLICY='{"cheap":[],"fast":["catalog-model-id"],"smart":["catalog-model-id"]}'
AGENT_FRAMEWORK=ai-sdk    # ai-sdk | mastra | langgraph | openai-agents
```


## 要複製的命令

按照註釋檢視命令在哪個資料夾中執行。如果標記了兩個終端，請開啟兩個終端視窗，並在使用第二個命令時保持第一個命令執行。

```
corepack pnpm --filter @supastack/web dev
```


## 實現流程

接受生產任務之前，先配置目錄與工作區策略。瀏覽器拿到的是已啟用的別名；能力匹配、模型選擇、許可權檢查與預算執行都留在服務端。

憑證不要放進 NEXT_PUBLIC_ 或 EXPO_PUBLIC_ 變數。自帶金鑰模式使用現有的加密信封與服務端解密邊界；絕不要把已存的供應商金鑰返回給介面。


## 驗證與排障

如果應用程式報告沒有可用的AI模型，請檢查伺服器的AI_PROVIDER、管理目錄中啟用的模型和價格以及便宜/快速/智慧別名策略。如果真實提供者返回身份驗證錯誤，請檢查 apps/web/.env.local 中的金鑰並重新啟動伺服器。字首為 NEXT_PUBLIC_ 的金鑰對瀏覽器可見，必須刪除。

驗證停用別名、缺失能力、失效許可權與耗盡預算。真實生成使用單獨授權的供應商冒煙執行。如果沒有別名可用，檢查服務端策略與目錄配置，而不是暴露一個原始模型選擇器。


如果你想繼續完成設定，可以閱讀《[設定後臺任務](https://supastack.dev/zh-tw/docs/web/setup-jobs.md)》。


## 下一篇

[AI 與後臺任務](https://supastack.dev/zh-tw/docs/modules/ai.md)