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

# Agent 與供應商設定

> 新增 Agent、安裝託管執行階段、登入賬號，併為每個 Agent 配置模型供應商。

Vibex 使用 [Agent Client Protocol](https://agentclientprotocol.com/)（ACP）連線線上 Agent。**Agent**（誰來做）和**模型供應商設定**（用哪個模型、走哪條線路）是分開管理的兩件事。

一個 Agent 可以有多套模型供應商設定；一套共享 Provider 也可以被多個 Agent 使用。這一頁講 Agent 自己的配置；共享 Provider、路由組和本地閘道器見[供應商、路由組與本地閘道器](https://vibex.peatboy.com/docs/zh-TW/providers-and-gateway.md)。

## Agent 標籤頁的結構

開啟 **配置中心 → Agent** 後，左側是 Agent 列表，右側是所選 Agent 的詳情區。詳情區從上到下包含：

| 卡片 | 作用 |
| - | - |
| **Agent 安裝** | 檢視安裝狀態，安裝 / 升級 / 回滾 / 解除安裝託管執行階段。 |
| **原生憑證** | 登入 Agent 自己的賬號。 |
| **模型供應商設定** | 為該 Agent 配置模型供應商、模型和憑據。 |
| **內建工具** | 按 Agent 開關終端機、瀏覽器、電腦操作等工具面板。 |

> [!NOTE]
>
> 模型供應商**不是**獨立主分區。每個 Agent 的模型供應商設定掛在 Agent 詳情裡；共享 Provider 和路由組在 **供應商** 分區裡。

## 新增 Agent

左側列表按狀態分組：已啟用、已新增但停用、尚未新增。每個條目右側的動作取決於當前狀態：

| 狀態 | 可做的操作 |
| - | - |
| **未新增** | 點選 **+** 加入。 |
| **未安裝** | 點選 **安裝**，Vibex 會下載並校驗託管執行階段。 |
| **有可用更新** | 點選 **升級** 升級到新版本。 |
| **可用** | 已就緒，可用啟用開關控制它是否出現在會話的 Agent 選擇器裡。 |
| **由使用者管理** | 該 Agent 不在託管目錄中，Vibex 會使用你 `PATH` 上的命令列程式。 |
| **已停用** | 已停用，但仍保留配置和會話歷史。 |

Vibex 自帶四個內建預設：**Claude Code**、**Codex**、**ZCode**、**OpenCode**。ACP 目錄另外提供 **Antigravity**、**Cline**、**Codebuddy**、**GitHub Copilot**、**Cursor**、**DeepSeek Harness**、**Devin**、**Gemini CLI**、**Grok Build**、**Hermes**、**Kimi Code**、**Pi** 等整合。

### 託管執行階段

* **安裝** 會從網路下載並校驗執行階段；安裝過程中不能取消。
* **檢查更新** 會讀取該 Agent 的釋出通道和固定版本。
* **升級** 只移動到相容的更新版本。
* **回滾** 可以把託管安裝退回到 Vibex 為該 Agent 固定的版本；回滾不是“鎖定”，之後仍會繼續跟蹤釋出通道。
* **解除安裝** 會彈出確認對話方塊，刪除託管執行階段和快取版本；會話歷史會保留。

> [!WARNING]
>
> 託管安裝失敗時，先檢查網路是否能訪問 GitHub 和執行階段自己的分發源。不要把完整安裝日誌或 token 貼上到公開 Issue。

### 新增自定義 ACP Agent

點選列表底部的 **新增自定義 ACP Agent**，填寫：

| 欄位 | 說明 |
| - | - |
| **Agent ID** | 小寫 kebab-case 標識，例如 `my-acp-agent`。 |
| **顯示名稱** | 顯示名稱。 |
| **描述** | 可選，說明用途。 |
| **ACP 命令** | 執行檔、`npx` 或 `uvx` 形式的命令。 |
| **引數** | 以空格分隔的引數。 |
| **環境變數（可選）** | 每行一個 `KEY=value`。 |

自定義 Agent 目前只能新建，不能編輯；關閉開關會刪除它，但會話歷史保留。

### 內建工具

每個 Agent 的內建工具面板可以在 Agent 列表裡開關。啟用的工具圖示會亮成綠色：

* **終端機**：Agent 可以請求執行命令。
* **瀏覽器**：Agent 可以使用內嵌瀏覽器工具。
* **電腦操作**：Agent 可以使用桌面操作工具（還需要在設定裡安裝驅動並開啟總開關）。

工具開關只決定 Agent 能不能收到這個工具面，不改變會話裡已有的權限核准。關閉工具不會撤銷已經執行的操作。

## 登入 Agent 賬號

**原生憑證** 卡片管理 Agent 自己的賬號，它與外部 CLI 共享同一份憑據——卡片上會明確寫出 "Agent-native account · shared with the external Agent CLI"。

* 可用的登入方式由 Agent 決定，常見的有 **登入**、**儲存並登入**、**開啟登入終端機**。
* 卡片提供 **重新整理認證方式**、**驗證賬號**、**重新整理模型**、**重新認證**、**退出登入**。
* 重新認證會影響正在使用舊憑據的 Agent 程序；介面會先給出提示。
* **退出登入** 同時影響外部 CLI 和 Vibex 會話，執行前會顯示受影響的會話數量。

瀏覽器授權的登入（Cursor、Grok、Gemini、Cline、CodeBuddy、Antigravity 等）可能不宣告退出登入能力；Vibex 會把它們識別為可用的 OAuth 方式，而不是當成不可用。

## 配置模型供應商

在 **模型供應商設定** 卡片中點選 **新增配置**，或對已有配置點選編輯。編輯器分三段：

### 基本資訊

| 欄位 | 說明 |
| - | - |
| **供應商名稱** | 必填。顯示用名稱。 |
| **備註** | 可選備註。 |
| **官網連結** | 可選。 |
| **型別** | 官方、官方 / 中轉 / 本機等來源標記。 |

### 連線與憑證

| 欄位 | 說明 |
| - | - |
| 憑據 | 由所選 Agent 決定用 API Key、OAuth 還是 Agent 賬號。 |
| **預設 API 請求地址** | 供應商的 API 地址，例如 `https://provider.example/v1`。部分 Agent 會鎖定此項。 |
| **按協議分別設定地址** | 摺疊區，需要為不同協議分別指定地址時展開。 |
| **請求頭** | 可選。支援字面值和內建 `session_id` 變數。 |
| **代理** | 直連、系統代理或自定義代理地址。 |

API Key 輸入框是**只寫**的：預設掩碼顯示，點眼睛圖示可以顯示明文；已儲存時會標出 **已儲存**。沒有改動過的欄位不會重寫已儲存的值，留空儲存會保留原值；要清除就點 **清除**。

### 模型

編輯器把模型分成兩欄：左欄是 **可選模型** 選擇器，右欄是所選模型的 **模型設定**。

Vibex **不預置模型列表**：

* **拉取模型** —— 需要已填 API Key 和地址，拉取該賬號可用的模型來填充 **可選模型**。拉取本身不寫入任何配置。
* **可選模型** —— 勾選一行會把這個模型加入草稿；取消勾選會移除它但保留已宣告的能力，重新勾選即可恢復。**全選** / **全部啟用** 可以批次處理；沒有可拉取的模型時，在 **自定義模型** 裡手動輸入 id 再加入。
* **Model ID** / **顯示名稱** —— 在右欄編輯。選中狀態按模型 id 跟蹤，所以重新命名之後右欄仍停在正在編輯的模型上。
* **模型介面協議** —— 每個模型可以單獨指定通訊協議，預設 **繼承**（繼承供應商設定）。
* **推理能力** / **思考檔位** —— 選擇是否推理，或宣告**思考深度**檔位。
* **上下文視窗 / 最大輸出 Token** —— 在 **高階** 摺疊區中宣告模型上限。

供應商不提供的模型，右欄會顯示 **新增該模型**，點它把該模型加入列表。

思考深度的可選檔位來自供應商或 Agent 宣告，常見取值為 `off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。宣告錯誤會讓 Agent 收到它不支援的檔位；不確定時留空。

## 在會話中使用

傳送訊息前，從輸入框頂部的級聯選單選擇 **Agent**、**模型供應商**、**模型** 和 **思考深度**。如果 Agent 繫結的是路由組，模型列表裡會出現路由組對外提供的模型名。

切換隻影響後續執行；已有時間線保留原執行的 Agent 和模型資訊。

> [!WARNING]
>
> **測試連線** 和 **拉取模型** 會真實訪問供應方網路並可能消耗額度。行動端的 `read_only` 裝置不能觸發這些操作。

## 故障排查

* **Agent 不在列表中**：確認執行檔在 `PATH` 中，或檢查自定義命令和引數。
* **模型不可選**：先 **重新整理模型**，再檢查該模型是否已啟用，以及 Agent 是否綁定了包含它的 Provider 或路由組。
* **認證失敗**：確認賬號狀態，重新登入；不要在 Issue 中貼上響應頭或 token。
* **遠端端看不到配置**：確認裝置權限級別是否為 `full_control`，以及當前連的是哪個權威執行階段。本機和遠端執行階段的配置是分開的。
* **託管 Agent 安裝失敗**：檢查網路是否能訪問 GitHub 與執行階段自己的分發源，然後重試。
* **Agent 收不到瀏覽器或電腦工具**：檢查 Agent 的內建工具開關，以及電腦操作的總開關和驅動狀態。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.