> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# 設定

> 設定服務商、外觀和代理行為

點擊側邊欄中的齒輪圖示開啟設定。設定視窗分為三個標籤頁：**一般**、**外觀**和**代理**。

## 一般

### 帳號

管理您的工作區設定檔和驗證狀態。

* 檢視所有已設定的設定檔及其工作區名稱
* 在設定檔之間切換
* 新增或移除設定檔
* 檢視連線狀態（綠色/紅色指示符）
* 登出目前設定檔

請參閱[驗證](/zh-Hant/ctor/guide/authentication)以了解設定設定檔的詳細資訊。

### 服務商

為每個 AI 模型服務商設定 API 金鑰。應用程式支援：

| 服務商                                   | 設定                                                |
| ------------------------------------- | ------------------------------------------------- |
| **Anthropic**                         | API 金鑰或 OAuth（Claude Pro／Max）                     |
| **OpenAI**                            | API 金鑰、可選的基礎 URL                                  |
| **OpenAI Codex**                      | OAuth 驗證                                          |
| **Google**                            | API 金鑰                                            |
| **Google Agent Platform (Vertex AI)** | ADC／服務帳戶金鑰／API 金鑰（僅限 Gemini）+ Project ID + Region |
| **GitHub Copilot**                    | OAuth 驗證                                          |
| **OpenCode Zen**                      | API 金鑰                                            |
| **OpenCode Go**                       | API 金鑰                                            |

在聊天期間，只有已設定憑證的服務商才會出現在模型選擇器中。

### Anthropic

Anthropic 服務商支援兩種驗證方式：

* **API 金鑰** —依 token 用量向您的 Anthropic 帳戶計費。在服務商卡片中輸入 `sk-ant-...` 金鑰。
* **使用 Claude 登入** —以額度方式使用，由您訂閱的 Claude Pro 或 Max 方案額度支應。點選 **使用 Claude 登入**會在瀏覽器中開啟 OAuth 流程；CTOR 透過本機回呼接收 token。登入後服務商列會顯示 **OAuth** 標記。

兩種憑證可同時保留在同一列；同時存在時以 OAuth 為優先。執行中的登入流程可透過相同按鈕、關閉瀏覽器分頁，或關閉設定視窗來取消。若目前裝置無法開啟瀏覽器，請將顯示的授權 URL 複製到其他裝置完成驗證。

### Google Agent Platform (Vertex AI)

Google 已將 Vertex AI 重新命名為 Agent Platform；CTOR 同時顯示兩個名稱，方便使用者以任一名稱找到此服務商。展開服務商卡片可設定下列項目：

* **Use default ADC** —從 `~/.config/gcloud/application_default_credentials.json` 讀取認證。建議 Claude 與 Gemini 皆採用此方式，Claude 合作夥伴模型必須使用。
* **Service Account Key File** —服務帳戶 JSON 檔案的路徑，**Browse…** 按鈕會開啟檔案選擇器。可作為預設 ADC 的替代方案。當 **Use default ADC** 開啟時，此欄位會停用。
* **Project ID** —您的 Google Cloud 專案 ID。Claude 使用 ADC 時為選填（會自動從認證的 `quota_project_id` 解析）；Gemini 以及使用 API 金鑰的請求則必填。
* **Region** —Vertex 區域，例如 `global`、`us`、`eu`、`us-east5` 或 `europe-west1`。留空時預設為 `global`。
* **API Key** —僅限 Gemini。Claude 合作夥伴模型不接受 API 金鑰，必須透過 ADC 或服務帳戶使用 OAuth2／IAM。

若要設定 ADC，請在終端機執行 `bash <(curl -sSL https://storage.googleapis.com/cloud-samples-data/adc/setup_adc.sh)`。API 金鑰可從 [Agent Platform Studio API keys 頁面](https://console.cloud.google.com/agent-platform/studio/settings/api-keys)產生；部分組織會停用 API 金鑰存取，此時只能使用 ADC。

### OpenAI 相容端點

在內建服務商下方新增自訂 OpenAI 相容 API 端點。每個端點有自己的名稱、基礎 URL、API 金鑰和模型清單。點擊 **+ 新增端點**來建立一個，然後設定：

* **端點名稱** —顯示於模型選擇器中的顯示名稱（例如「Ollama」）
* **基礎 URL** —API 端點 URL
* **API 模式** —**Chat Completions**（預設）或 **Responses**；推理模型請選擇 **Responses**
* **API 金鑰** —選填，視服務商而定
* **模型** —在此端點可用的一個或多個模型識別碼

已設定端點的模型會出現在模型選擇器和預設模型下拉選單中，並以端點名稱分組。

每個模型都有各自的**圖片**、**推理**和 **XHigh** 切換選項，以及選填的**上下文**視窗。**推理**僅在 **Responses** API 模式下可用，**XHigh** 則僅在啟用**推理**時可用。詳見[支援的模型](/zh-Hant/ctor/reference/models#個別模型選項)。

<Tip>
  若應用程式中未設定 API 金鑰，代理會退而使用 `ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY` 環境變數。
</Tip>

### 預設模型

選擇用於新工作階段的預設模型。您可以使用輸入列中的模型選擇器，按工作階段覆蓋模型設定。

### 更新

檢查並安裝應用程式更新：

* **檢查更新** —查詢更新伺服器以取得最新版本
* **下載並安裝** —下載更新並重新啟動應用程式

顯示您目前的版本和最新可用版本。

## 外觀

### 佈景主題

選擇應用程式佈景主題：

* **系統** —追蹤您的作業系統佈景主題
* **淺色** —淺色模式
* **深色** —深色模式

每個選項都顯示該佈景主題下聊天工作階段和差異檢視的縮圖預覽。佈景主題立即套用。

### 強調色

選擇整個介面使用的強調色，包含按鈕、焦點外框、連結，以及聊天中的使用者訊息泡。變更會立即套用，佈景主題預覽縮圖也會同步更新。

| 選項         | 色票            |
| ---------- | ------------- |
| **陶土**（預設） | 暖橘色 `#e2924b` |
| **天空**     | 冷藍色 `#4b8ae2` |
| **苔蘚**     | 柔和綠 `#6aad6c` |
| **石墨**     | 中性灰 `#86909b` |

### 減少動態效果

減少整個應用程式的動畫與轉場效果。預設為 **系統**。

* **系統** —追蹤作業系統的減少動態效果偏好設定
* **開啟** —一律減少動態效果，忽略作業系統設定
* **關閉** —一律保持完整動態效果，覆寫作業系統設定

變更會立即套用。

### 視窗

僅 macOS 可用。讓桌面透過應用程式視窗呈現，使用 macOS 原生 Vibrancy。

* **背景模糊** —啟用搭配符合主題的半透明介面，由 macOS Vibrancy 支援。預設停用。
* **介面不透明度** —滑桿用於調整應用程式介面的紮實程度。較低的值會顯示更多桌面模糊（**更多模糊**）；較高的值則讓介面保持紮實（**更不透明**）。範圍 25–95%，預設 78%。需先啟用 **背景模糊** 才能調整。

### 字型

自訂應用程式中使用的字型：

* **介面字型** —介面使用的字型（選單、標籤、訊息）。輸入 CSS 字型系列值。
* **程式碼字型** —程式碼區塊、終端機輸出和差異區段使用的字型。輸入 CSS 字型系列值。

介面字型預設為平台原生無襯線字型（macOS 上的 SF Pro，Linux 上的 Ubuntu/Noto Sans）。程式碼字型預設為跨平台等寬字型組合。輸入欄位會在您輸入時預覽您選擇的字型。

### 語言

選擇應用程式語言：

* English (US)
* Traditional Chinese（繁體中文）
* Japanese（日本語）

**系統**選項追蹤您的作業系統地區設定。

## 代理

設定代理行為：

* **自動核准 bash 指令** —啟用後，完整存取 bash 指令和受信任的 `bricks devtools` 指令無需確認即可執行。停用（預設）時，每個指令執行前需要您核准。無論此設定為何，沙箱化指令始終在[沙箱](/zh-Hant/ctor/reference/sandbox)中執行。[危險指令](/zh-Hant/ctor/reference/sandbox#危險指令偵測)（如 `sudo`、`rm -rf` 或改寫歷史的 `git`）即使啟用此設定也一律會顯示提示。
* **系統通知** —啟用（預設）後，當代理完成回合、失敗，或暫停等待工具核准，且沒有任何 CTOR 視窗取得焦點時，CTOR 會發出附帶作業系統提示音的系統通知。點選通知即可將 CTOR 帶到前景。停用後將不再發出任何背景提示。
* **啟用 ACP** —啟動本機通訊端伺服器，讓外部工具（acpx、OpenClaw）可以透過 [Agent Client Protocol](/zh-Hant/ctor/reference/acp) 與代理互動。預設停用。切換立即生效，無需重新啟動應用程式。
* **沙箱設定** —開啟 `sandbox.json` 以自訂沙箱的網路和檔案系統許可權。請參閱[沙箱](/zh-Hant/ctor/reference/sandbox)以了解詳細資訊。
* **Hooks 設定** —開啟 `hooks.json` 以在代理事件時執行自訂指令。專案層級的 hooks 可放置在 `.bricks/hooks.json`。請參閱 [Hooks](/zh-Hant/ctor/reference/hooks) 以了解詳細資訊。

### 預設思考層級

選擇新工作階段的預設思考層級。可用層級：`off`、`minimal`、`low`、`medium`、`high`、`xhigh`。留空則使用**高**。

### 子代理預設模型

選擇子代理生成的預設模型。請參閱[子代理](/zh-Hant/ctor/reference/sub-agents)，了解此設定如何融入模型解析。

### 子代理預設思考層級

選擇子代理的預設思考層級。可用層級：`off`、`minimal`、`low`、`medium`、`high`、`xhigh`。留空則使用模型特定的預設值。請參閱[子代理](/zh-Hant/ctor/reference/sub-agents#thinking-level-resolution)以了解完整的解析順序。

### 備援視覺模型

選擇一個視覺模型；當目前模型無法處理圖片時，改由它來描述圖片。部分模型不支援圖片，選用這類模型時，CTOR 會把每張圖片送交此備援模型，由它回傳目前模型可讀取的文字描述。留空（**已停用**，預設值）即可關閉此功能。

選擇器只會列出支援圖片輸入的模型。備援會涵蓋代理原本無法處理的所有圖片——您的附件、以 `read_file` 開啟的圖片、[模擬器](/zh-Hant/ctor/reference/preview#由代理驅動的預覽)截圖，以及 MCP 工具回傳的圖片。原始圖片仍會保留在對話中，產生的描述也會一併儲存，因此同一張圖片不會在後續回合重複描述。描述也會顯示在[訊息詳情](/zh-Hant/ctor/guide/agent-usage#檢視訊息)面板中每張圖片下方。設定備援後，即使使用不支援視覺的模型，仍可附加圖片並使用[繪圖模式](/zh-Hant/ctor/reference/preview#繪圖模式)。

### 主聊天工作目錄

選擇[主聊天](/zh-Hant/ctor/guide/main-chat#主工作區)寫入專案及其他產物的位置。預設為 `~/bricks-ctor`，欄位空白時會以預留位置顯示。

* **瀏覽……** —開啟目錄選擇器；選定的路徑會填入文字方塊，但須按 **儲存** 才會寫入。
* **儲存** —寫入輸入的路徑。儲存前會先驗證：
  * 必須是絕對路徑（會拒絕如 `./work` 的相對路徑）。
  * 不能是檔案系統根目錄（`/`、`C:\`）。
  * 上層目錄必須已存在—CTOR 會建立末端目錄，但不會建立中間階層。
* **重設** —清除已儲存的值並改回 `~/bricks-ctor`。僅在已儲存自訂路徑時顯示。

變更無需重新啟動應用程式即可生效—主代理的工具、沙箱範圍與檔案提及會立即改用新目錄。若已儲存路徑的上層目錄之後消失（外接磁碟未掛載、資料夾被刪除），欄位會顯示行內錯誤，主聊天在您重新選擇位置或重設前都無法啟動。

## 進階

* **顯示思考內容** —在聊天訊息中顯示模型思考內容。預設停用。
* **顯示訊息按鈕** —在輸入列中顯示**訊息**按鈕，可開啟**訊息詳情**面板，用於檢視並匯出傳送給模型的訊息。請參閱[檢視訊息](/zh-Hant/ctor/guide/agent-usage#檢視訊息)。預設停用。
* **顯示環境切換** —在登入畫面上顯示環境選擇器。預設停用。
* **啟用背景程序** —允許代理生成背景子程序。支援 daemon（持續）和 long-run（完成回呼）模式。預設啟用。

### 實驗性功能

* **Language Server Tools** —協助代理在每次編輯後即時發現 TypeScript 錯誤，並能跳到型別與函式的定義或使用位置。請參閱[使用 AI 代理](/zh-Hant/ctor/guide/agent-usage#typescript-語言伺服器工具)。預設停用。
* **語音輸入** —使用 Apple Speech 從輸入列以口述方式輸入訊息。需要 macOS 26 或更新版本以及麥克風存取權，因此此選項僅在支援的 Mac 上顯示。預設停用。啟用後，輸入列會新增一個麥克風按鈕——請參閱[語音輸入](/zh-Hant/ctor/guide/agent-usage#語音輸入)。
  * **語音語言** —口述辨識使用的語言：英文、繁體中文或日文。未變更時，預設採用應用程式語言。

## 資料儲存

應用程式將其資料儲存於以下位置：

| 資料       | 位置                                               |
| -------- | ------------------------------------------------ |
| 驗證設定     | `~/.bricks-cli/config.json`                      |
| 應用程式設定   | `~/.bricks-project-desktop/settings.json`        |
| 聊天工作階段   | `~/.bricks-project-desktop/sessions/`            |
| 全域技能     | `~/.bricks-project-desktop/skills/`              |
| 專案技能     | `<project>/.bricks/skills/`                      |
| MCP 設定   | `<project>/.mcp.json`                            |
| 沙箱設定     | `~/.bricks-project-desktop/sandbox.json`         |
| 每專案沙箱模式  | `~/.bricks-project-desktop/project-sandbox.json` |
| Hooks 設定 | `~/.bricks-project-desktop/hooks.json`           |

<Tip>
  設定 `BRICKS_PROJECT_DESKTOP_DATA_DIR` 環境變數可覆蓋預設資料目錄（`~/.bricks-project-desktop/`）。
</Tip>