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

# CodeBuddy / WorkBuddy

> 通过 models.json 配置将 CodeBuddy 或 WorkBuddy 连接到 AihubMax

## 概述

[CodeBuddy](https://codebuddy.ai) 和 [WorkBuddy](https://workbuddy.ai) 是腾讯云推出的 AI 编程助手，可直接集成到你的 IDE 中。通过将它们连接到 AihubMax，你可以借助 AihubMax 的统一 API 使用多种 AI 模型。

<Info>
  CodeBuddy 和 WorkBuddy 通过 `models.json` 配置文件来定义自定义模型供应商。AihubMax 提供的 OpenAI 兼容端点可以无缝对接这一配置方式。
</Info>

## 前置条件

<CardGroup cols={2}>
  <Card title="AihubMax API Key" icon="key">
    一个有效的 AihubMax API Key，并确保有权限访问你想使用的模型。
  </Card>

  <Card title="CodeBuddy / WorkBuddy" icon="code">
    已在 IDE（VS Code、JetBrains 等）中安装 CodeBuddy 或 WorkBuddy 扩展。
  </Card>
</CardGroup>

## 配置步骤

CodeBuddy 和 WorkBuddy 从 `models.json` 文件中读取模型定义，支持两个层级的配置：

* **用户级**（对所有项目生效）：存放在用户主目录下
* **项目级**（优先级更高，仅对当前项目生效）：存放在项目根目录下

<Steps>
  <Step title="确认配置文件路径">
    根据你使用的工具和操作系统，选择对应的路径：

    <Tabs>
      <Tab title="CodeBuddy">
        | 层级      | macOS / Linux                    | Windows                                 |
        | ------- | -------------------------------- | --------------------------------------- |
        | **用户级** | `~/.codebuddy/models.json`       | `C:\Users\<用户名>\.codebuddy\models.json` |
        | **项目级** | `<项目根目录>/.codebuddy/models.json` | `<项目根目录>\.codebuddy\models.json`        |
      </Tab>

      <Tab title="WorkBuddy">
        | 层级      | macOS / Linux                    | Windows                                 |
        | ------- | -------------------------------- | --------------------------------------- |
        | **用户级** | `~/.workbuddy/models.json`       | `C:\Users\<用户名>\.workbuddy\models.json` |
        | **项目级** | `<项目根目录>/.workbuddy/models.json` | `<项目根目录>\.workbuddy\models.json`        |
      </Tab>
    </Tabs>

    <Tip>
      项目级配置的优先级高于用户级配置。当你需要为特定项目使用不同的模型或 API Key 时，可以使用项目级配置。
    </Tip>
  </Step>

  <Step title="创建 models.json 文件">
    在上一步确认的路径下创建 `models.json` 文件。以下是包含一个模型的基础示例：

    ```json theme={null}
    {
      "models": [
        {
          "id": "gpt-5.4",
          "name": "AihubMax Auto (智能路由)",
          "vendor": "AihubMax",
          "apiKey": "sk-your-foxapi-api-key",
          "url": "https://api.aihubmax.com/v1/chat/completions",
          "supportsToolCall": true,
          "supportsImages": true
        }
      ]
    }
    ```

    将 `sk-your-foxapi-api-key` 替换为你的实际 AihubMax API Key。

    <Warning>
      URL 必须是完整的 chat completions 端点地址：`https://api.aihubmax.com/v1/chat/completions`，不要只填写 Base URL。
    </Warning>
  </Step>

  <Step title="添加更多模型（可选）">
    你可以在 `models` 数组中定义多个模型，每个条目都会作为可选模型出现在扩展的模型列表中：

    ```json theme={null}
    {
      "models": [
        {
          "id": "gpt-5.4",
          "name": "AihubMax Auto (智能路由)",
          "vendor": "AihubMax",
          "apiKey": "sk-your-foxapi-api-key",
          "url": "https://api.aihubmax.com/v1/chat/completions",
          "supportsToolCall": true,
          "supportsImages": true
        },
        {
          "id": "claude-sonnet-4-20250514",
          "name": "Claude Sonnet 4",
          "vendor": "AihubMax",
          "apiKey": "sk-your-foxapi-api-key",
          "url": "https://api.aihubmax.com/v1/chat/completions",
          "supportsToolCall": true,
          "supportsImages": true
        },
        {
          "id": "gpt-4o",
          "name": "GPT-4o",
          "vendor": "AihubMax",
          "apiKey": "sk-your-foxapi-api-key",
          "url": "https://api.aihubmax.com/v1/chat/completions",
          "supportsToolCall": true,
          "supportsImages": true
        },
        {
          "id": "deepseek-chat",
          "name": "DeepSeek V3",
          "vendor": "AihubMax",
          "apiKey": "sk-your-foxapi-api-key",
          "url": "https://api.aihubmax.com/v1/chat/completions",
          "supportsToolCall": true,
          "supportsImages": false
        }
      ]
    }
    ```

    可参阅 [AihubMax 模型列表](/models) 查看所有可用的模型 ID。
  </Step>

  <Step title="在 IDE 中选择模型">
    保存 `models.json` 文件后，扩展会自动检测配置变更，无需重启。在 IDE 中打开 CodeBuddy 或 WorkBuddy，从模型下拉菜单中选择你配置的 AihubMax 模型即可。
  </Step>
</Steps>

## 配置字段说明

`models.json` 中每个模型条目支持以下字段：

| 字段                 | 类型      | 必填 | 说明                                                     |
| ------------------ | ------- | -- | ------------------------------------------------------ |
| `id`               | string  | 是  | 发送到 API 的模型标识符（如 `gpt-4o`、`claude-sonnet-4-20250514`）。 |
| `name`             | string  | 是  | 在模型选择器中显示的名称。                                          |
| `vendor`           | string  | 是  | 供应商标签（如 `AihubMax`）。                                   |
| `apiKey`           | string  | 是  | 你的 AihubMax API Key。                                   |
| `url`              | string  | 是  | 完整的 chat completions 端点 URL。                           |
| `supportsToolCall` | boolean | 否  | 模型是否支持函数/工具调用，支持则设为 `true`。                            |
| `supportsImages`   | boolean | 否  | 模型是否支持图片输入，支持则设为 `true`。                               |

## 验证连接

配置完成后：

1. 在 IDE 中打开任意代码文件。
2. 从模型下拉菜单中选择一个 AihubMax 模型。
3. 触发 AI 助手（例如选中代码并请求解释，或启动内联对话）。
4. 如果成功生成回复，说明连接正常。

## 常见问题

<AccordionGroup>
  <Accordion title="AI 助手没有响应">
    * 确认 API Key 正确且账户余额充足。
    * 检查 `url` 字段是否为 `https://api.aihubmax.com/v1/chat/completions`。
    * 确认 `id` 字段对应的模型在 AihubMax 上可用。
    * 验证 `models.json` 文件的 JSON 语法是否正确（无多余逗号、引号配对等）。
  </Accordion>

  <Accordion title="模型未出现在下拉菜单中">
    * 确认 `models.json` 文件位于正确的目录下（参见[确认配置文件路径](#确认配置文件路径)）。
    * 扩展会自动检测文件变更，但如果模型仍未出现，可尝试重启扩展或 IDE。
    * 确保 JSON 文件格式有效，可以通过以下命令检查：
      ```bash theme={null}
      cat ~/.codebuddy/models.json | python3 -m json.tool
      ```
  </Accordion>

  <Accordion title="响应速度慢">
    * 尝试切换到更快的模型（如使用 `claude-sonnet-4-20250514` 代替 `claude-opus-4-20250514`）。
    * 检查网络连接状况。
  </Accordion>

  <Accordion title="工具调用或图片功能无法使用">
    * 确认对应模型条目中的 `supportsToolCall` 和/或 `supportsImages` 已设为 `true`。
    * 并非所有模型都支持这些功能，请在 AihubMax 模型列表中查看模型的具体能力。
  </Accordion>
</AccordionGroup>

## 安全建议

<Note>
  * **切勿将包含 API Key 的 `models.json` 提交到版本控制系统。** 请将 `.codebuddy/` 和 `.workbuddy/` 添加到 `.gitignore` 文件中。
  * **谨慎使用项目级配置。** 如果在共享仓库中工作，建议优先使用用户级配置，避免意外暴露 API Key。
  * **在 AihubMax 控制台监控用量**，及时发现异常消耗。
</Note>