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

# Aider

> 通过 Aider 兼容 OpenAI 的 API 设置，将 Aider 配置为在终端中与 Venice 模型进行结对编程。

[Aider](https://aider.chat/) 是一款 AI 结对编程工具，可从终端编辑您的本地 git 仓库。Venice 通过 Aider 的[兼容 OpenAI 的 API](https://aider.chat/docs/llms/openai-compat.html) 支持工作 —— 设置 Venice 的 base URL 和 API 密钥，然后为模型 ID 加上 `openai/` 前缀即可。

<CardGroup cols={3}>
  <Card title="终端结对编程" icon="terminal">
    在 CLI 中使用 Venice 模型编辑您的 git 仓库
  </Card>

  <Card title="OpenAI 兼容" icon="plug">
    使用 Venice 的 `/chat/completions` 端点
  </Card>

  <Card title="任意文本模型" icon="microchip">
    可替换为任意 Venice 文本模型 ID
  </Card>
</CardGroup>

***

## 前置条件

* 来自 [venice.ai/settings/api](https://venice.ai/settings/api) 的 Venice API 密钥
* 您的机器上已安装 Python 3.9+
* 一个可供工作的 git 仓库

***

## 设置

<Steps>
  <Step title="安装 Aider">
    使用官方安装器安装 Aider：

    ```bash theme={"system"}
    python -m pip install aider-install
    aider-install
    ```

    如果您偏好其他安装方式，请参阅 [Aider 安装文档](https://aider.chat/docs/install.html)。
  </Step>

  <Step title="将 Venice 配置为 OpenAI 端点">
    通过设置 OpenAI 兼容的 base URL 和您的 Venice API 密钥，将 Aider 指向 Venice。

    **Mac / Linux：**

    ```bash theme={"system"}
    export OPENAI_API_BASE=https://api.venice.ai/api/v1
    export OPENAI_API_KEY=your-venice-api-key
    ```

    **Windows (PowerShell)：**

    ```powershell theme={"system"}
    $env:OPENAI_API_BASE = "https://api.venice.ai/api/v1"
    $env:OPENAI_API_KEY = "your-venice-api-key"
    ```

    **Windows（命令提示符，持久化）：**

    ```bat theme={"system"}
    setx OPENAI_API_BASE https://api.venice.ai/api/v1
    setx OPENAI_API_KEY your-venice-api-key
    ```

    在使用 `setx` 后请重启终端，以便新的环境变量生效。
  </Step>

  <Step title="使用 Venice 模型启动 Aider">
    在您的项目目录中，为 Venice 模型 ID 加上 `openai/` 前缀：

    ```bash theme={"system"}
    cd /to/your/project

    aider --model openai/zai-org-glm-5-1
    ```

    其他不错的入门模型：

    ```bash theme={"system"}
    aider --model openai/kimi-k2-5
    aider --model openai/minimax-m25
    aider --model openai/venice-uncensored
    ```

    在[模型目录](/models/text)中浏览所有文本模型 ID。
  </Step>
</Steps>

***

## 使用 `.env` 持久化配置

对于项目级设置，在 git 仓库根目录创建一个 `.env` 文件：

```bash theme={"system"}
OPENAI_API_BASE=https://api.venice.ai/api/v1
OPENAI_API_KEY=your-venice-api-key
AIDER_MODEL=openai/zai-org-glm-5-1
```

然后正常启动 Aider：

```bash theme={"system"}
aider
```

Aider 也会读取您主目录下的 `.env`。仓库根目录中的值优先于主目录中的值。请将该文件排除在 git 之外 —— 如果尚未被忽略，请把 `.env` 添加到 `.gitignore`。

<Info>
  您也可以设置 `AIDER_OPENAI_API_BASE` 和 `AIDER_OPENAI_API_KEY`。官方 Aider 文档在介绍兼容 OpenAI 的提供商时仍使用 `OPENAI_API_BASE` 和 `OPENAI_API_KEY`。
</Info>

***

## 使用 YAML 持久化配置

您可以将相同的设置存储在仓库根目录或主目录下的 `.aider.conf.yml` 中：

```yaml theme={"system"}
openai-api-base: https://api.venice.ai/api/v1
openai-api-key: your-venice-api-key
model: openai/zai-org-glm-5-1
```

然后运行：

```bash theme={"system"}
aider
```

***

## 验证设置

Aider 启动后，向它问一些简短的问题以确认模型可达：

```txt theme={"system"}
Reply with one sentence confirming you are running through Venice.
```

如果端点和密钥正确，Aider 将从所选的 Venice 模型流式返回响应。

您也可以在 Aider 之外验证 API 密钥：

```bash theme={"system"}
curl https://api.venice.ai/api/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

***

## 选择模型

| 使用场景      | 示例模型 ID             | Aider 参数                           |
| --------- | ------------------- | ---------------------------------- |
| 强力编码 / 重构 | `zai-org-glm-5-1`   | `--model openai/zai-org-glm-5-1`   |
| 快速迭代      | `minimax-m25`       | `--model openai/minimax-m25`       |
| 长上下文编码    | `kimi-k2-5`         | `--model openai/kimi-k2-5`         |
| 无审查聊天     | `venice-uncensored` | `--model openai/venice-uncensored` |

启动 Aider 时请始终为 Venice 模型 ID 加上 `openai/` 前缀。不加该前缀，Aider 就不会通过兼容 OpenAI 的提供商路径路由请求。

在运行时发现当前可用的模型 ID：

```bash theme={"system"}
curl https://api.venice.ai/api/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

或查看 [GET /models/traits](/api-reference/endpoint/models/traits) 以了解如 `text:default` 的默认值。

***

## 配置注意事项

* 请将 `OPENAI_API_BASE` 保持为 `https://api.venice.ai/api/v1`。不要追加 `/chat/completions`；Aider 会自行添加聊天路径。
* 请在 `OPENAI_API_KEY` 中使用 Venice API 密钥。不要将 OpenAI 的密钥搭配 Venice base URL 使用。
* Aider 可能会警告模型的上下文窗口或成本未知。对于许多 Venice 模型 ID，这种警告是预期的，通常可以安全忽略。参阅 [Aider 模型警告](https://aider.chat/docs/llms/warnings.html)。
* 对于多文件编辑，请优先选择有能力的编码 / 推理模型。较小的或非编码模型可能难以处理 Aider 的编辑格式。

<Warning>
  在 shell 中设置 `OPENAI_API_BASE` 和 `OPENAI_API_KEY` 也会影响其他读取这些变量的工具。如果您在同一环境中还使用 OpenAI，建议改用项目级的 `.env` 或 `.aider.conf.yml`。
</Warning>

***

## 疑难排查

<AccordionGroup>
  <Accordion title="401 或身份验证错误">
    确认 `OPENAI_API_KEY` 是来自 [venice.ai/settings/api](https://venice.ai/settings/api) 的 Venice 密钥，且没有多余的空白字符。在 Windows 上使用 `setx` 后，请重启终端。
  </Accordion>

  <Accordion title="找不到模型或响应为空">
    确认该模型 ID 存在于[文本模型目录](/models/text)中，并且您启动 Aider 时使用了 `openai/` 前缀，例如 `openai/zai-org-glm-5-1`。
  </Accordion>

  <Accordion title="请求仍然发送到了 OpenAI">
    检查 `OPENAI_API_BASE` 在同一 shell 会话中是否恰好为 `https://api.venice.ai/api/v1`。可用 `echo $OPENAI_API_BASE` 打印（在 PowerShell 中使用 `$env:OPENAI_API_BASE`）。
  </Accordion>

  <Accordion title="上下文窗口 / 成本未知的警告">
    对于许多 Venice 模型来说这是预期的。Aider 会回退到合理的默认值。若要屏蔽该警告，请按 [Aider 高级模型设置](https://aider.chat/docs/config/adv-model-settings.html) 中的说明添加模型元数据。
  </Accordion>
</AccordionGroup>

***

## 资源

<CardGroup cols={2}>
  <Card title="Venice 文本模型" icon="list" href="/models/text">
    浏览可用的 Venice 模型 ID
  </Card>

  <Card title="Aider 兼容 OpenAI 文档" icon="book" href="https://aider.chat/docs/llms/openai-compat.html">
    Aider 官方提供商设置
  </Card>

  <Card title="使用 .env 配置 Aider" icon="gear" href="https://aider.chat/docs/config/dotenv.html">
    持久化 API 密钥和模型设置
  </Card>

  <Card title="Venice API 参考" icon="code" href="/api-reference/api-spec">
    完整端点和参数文档
  </Card>
</CardGroup>