# VS Code Agents 視窗設定教學

> 在 VS Code Agents 視窗中用自訂端點接入 LLMoxy，設定 API Key、模型 ID，並讓 Agent Host 會話使用自有模型。

網址：[https://code.visualstudio.com/（點擊跳轉下載！）](https://code.visualstudio.com/)

官方參考：[AI language models in VS Code](https://code.visualstudio.com/docs/agent-customization/language-models)、[Use the Agents window](https://code.visualstudio.com/docs/copilot/agents/agents-window)

> **📌 關於 Agents 視窗**
> Agents 視窗是 VS Code 的獨立 Agent 工作台，用來建立會話、選擇模型並追蹤任務。本文只說明如何把 LLMoxy 設定進去，不展開會話管理。

## 準備

- 已安裝 [VS Code](https://code.visualstudio.com/)（建議使用較新的穩定版或 Insiders）
- 在 LLMoxy 控制檯建立權杖，見 [取得權杖](https://tw.llmoxy.com/docs/get-started/get-token)
- 建議使用 **default** 分組權杖（GPT 文字模型）；生圖用的 Key 不要混用

接入資訊：

| 項目 | 值 |
| --- | --- |
| 閘道 | `https://llmoxy.com` |
| Chat Completions | `https://llmoxy.com/v1/chat/completions` |
| API Key | 控制檯複製的權杖 |
| 推薦模型 | `gpt-6-astra`、`grok-4.7` |

Agent 必須能呼叫工具，模型設定中要把 `toolCalling` 設為 `true`，否則不會出現在 Agents 視窗的模型清單中。

## 開啟 Agents 視窗

任選一種方式：

- 標題列點擊 **Open in Agents**
- 命令面板（`Ctrl+Shift+P` / `⌘⇧P`）執行 **Chat: Open Agents Window**
- 終端機執行 `code --agents`

![Agents 視窗介面](https://tw.llmoxy.com/docs-assets/tutorial-vscode-agents/agents-window.png)

建立新會話時，在輸入區選擇工作區、Agent harness 和語言模型。

![新建會話輸入區](https://tw.llmoxy.com/docs-assets/tutorial-vscode-agents/new-session.png)

## 允許 Agent Host 使用自有模型

Agents 視窗中的會話走 Agent Host。要使用 LLMoxy 這類自帶 Key 的模型，請先開啟實驗開關。

1. 開啟設定（`Ctrl+,` / `⌘,`）
2. 搜尋 `agentHost.byok`
3. 勾選 **Chat > Agent Host: Byok Models Enabled**（`chat.agentHost.byokModels.enabled`）

不想登入 GitHub、只用 LLMoxy 時，再勾選 **Chat > Agent Host: Allow Signed Out When Usable**（`chat.agentHost.allowSignedOutWhenUsable`）。

也可以直接寫入 `settings.json`：

```json
{
  "chat.agentHost.byokModels.enabled": true,
  "chat.agentHost.allowSignedOutWhenUsable": true
}
```

> **💡 提示**
> 這兩項預設關閉。不開啟的話，Chat 檢視中能看到 LLMoxy 模型，Agents 視窗裡卻選不到。

## 新增 LLMoxy 自訂端點

使用 VS Code 的 **Custom Endpoint**（自訂端點）接入，不要再使用已棄用的 OpenAI Compatible 舊項。

### 1. 開啟語言模型管理

在 Chat 或 Agents 視窗的輸入框開啟模型選擇器，點擊齒輪 **Manage Language Models**，或在命令面板執行 **Chat: Manage Language Models**。

![Chat 輸入框中的模型選擇器](https://tw.llmoxy.com/docs-assets/tutorial-vscode-agents/model-picker.png)

![語言模型管理器](https://tw.llmoxy.com/docs-assets/tutorial-vscode-agents/language-models-editor.png)

### 2. 新增自訂端點

1. 點擊 **Add Models**
2. 選擇 **Custom Endpoint**
3. 分組名稱填 `LLMoxy`（會顯示在模型清單中）
4. 填寫顯示名稱和 API Key（LLMoxy 權杖）
5. API 類型選擇 **Chat Completions**

![選擇模型提供方](https://tw.llmoxy.com/docs-assets/tutorial-vscode-agents/add-provider.png)

### 3. 編輯 chatLanguageModels.json

VS Code 會開啟 `chatLanguageModels.json`。依下方內容儲存（把 Key 換成自己的權杖）：

```json
[
  {
    "name": "LLMoxy",
    "vendor": "customendpoint",
    "apiKey": "${input:llmoxyApiKey}",
    "apiType": "chat-completions",
    "models": [
      {
        "id": "gpt-6-astra",
        "name": "GPT-6 Astra",
        "url": "https://llmoxy.com/v1/chat/completions",
        "apiType": "chat-completions",
        "toolCalling": true,
        "vision": true,
        "thinking": true,
        "maxInputTokens": 922000,
        "maxOutputTokens": 128000,
        "supportsReasoningEffort": ["low", "medium", "high", "xhigh", "max"],
        "reasoningEffortFormat": "chat-completions"
      },
      {
        "id": "grok-4.7",
        "name": "Grok 4.7",
        "url": "https://llmoxy.com/v1/chat/completions",
        "apiType": "chat-completions",
        "toolCalling": true,
        "vision": true,
        "thinking": true,
        "maxInputTokens": 500000,
        "maxOutputTokens": 128000
      }
    ]
  }
]
```

保存後，在模型選擇器中應能看到 **GPT-6 Astra**、**Grok 4.7**。沒有的話請重新啟動一次 VS Code。

## 在 Agents 視窗切換模型

1. 開啟 Agents 視窗，建立或選取一個會話
2. 在輸入框的模型選擇器中選擇 LLMoxy 下的模型
3. 推理模型可點擊名稱旁的 **>**，設定 Thinking Effort（如 Low / Medium / High）

![Thinking Effort 子選單](https://tw.llmoxy.com/docs-assets/tutorial-vscode-agents/thinking-effort.png)

選擇器會顯示類似 `GPT-6 Astra · High` 的內容。該會話會記住這次設定的推理強度。

> **⚠️ 注意**
> 未信任工作區（Restricted Mode）下，選擇器只會顯示 **Auto**。請先信任工作區。
> 企業版 Copilot 可能關閉了 **Bring Your Own Language Model Key in VS Code**，需由管理員在 GitHub Copilot 策略中開啟。

## 常見問題

- **Agents 視窗沒有 LLMoxy 模型**：確認已開啟 `chat.agentHost.byokModels.enabled`，且該模型的 `toolCalling` 為 `true`
- **422 / model not found**：核對 `id` 是否與控制檯一致，例如 `gpt-6-astra`、`grok-4.7`
- **401 / Invalid token**：權杖複製時不要帶空格或換行；確認 Key 未停用、未超額
- **位址寫錯**：API 類型選擇 **Chat Completions**，`url` 填 `https://llmoxy.com/v1/chat/completions`
- **生圖 Key 呼叫文字模型失敗**：生圖請使用「GPT Image 2 生圖分組」的獨立 Key，不要與文字模型混用

本文是 https://tw.llmoxy.com/docs/code-tutorials/vscode-agents 的 markdown 版本。
