# 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://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://llmoxy.com/docs-assets/tutorial-vscode-agents/agents-window.png)

新建会话时，在输入区选择工作区、Agent harness 和语言模型。

![新建会话输入区](https://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://llmoxy.com/docs-assets/tutorial-vscode-agents/model-picker.png)

![语言模型管理器](https://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://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://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://llmoxy.com/docs/code-tutorials/vscode-agents 的 markdown 版本。
