---
title: 自带智能体（BYOA）
description: "在你自己的智能体运行时（例如 Codex 或 Claude Code）上运行 Manager 的 Worker 任务"
---

## 什么是 BYOA？

BYOA（自带智能体）让你可以选择由哪个智能体运行时来驱动 Manager 的 Worker。除了使用 Verdent 默认的智能体之外，Manager 派发的 Worker 任务还可以运行在你已经使用或已获得授权的智能体上。

<Note>
想改用自己的服务商 API 密钥配合 Verdent 内置的智能体？请参阅 [BYOK](/docs/verdent-manager/configuration/byok)。
</Note>

## 支持的智能体类型

| 智能体 | 说明 | 前置条件 |
| --- | --- | --- |
| 内置智能体 | Verdent 提供的默认智能体 | 无 |
| Claude Code | Anthropic 的 Claude Code CLI | 已安装 Node.js（用于 `npx`） |
| Codex | OpenAI Codex CLI | 已安装 Codex CLI 并配置好 OpenAI 环境 |

## 使用场景

- **访问特定模型** —— 通过模型选择器使用 Verdent 默认集合中未包含的模型版本。
- **团队标准化** —— 使用共享的企业许可证，将团队用量集中计费。
- **熟悉的工作流** —— 保留你现有的 Claude Code 或 Codex 体验，同时让 Manager 把 Worker 任务派发给它。

## 快速入口

- BYOA 设置：**Settings → Models → CLI Agents**
- 在 Manager 聊天中选择模型：关闭输入框中的 **Auto** 模式以选择 Task Model
- 在 BYOA 中配置的 API 密钥仅存储在本地，绝不会上传到 Verdent 服务器

## Codex

Codex 是 OpenAI 的编码智能体 CLI。与 Claude Code 不同，Codex 在 Verdent 内不需要 API 密钥 —— 它使用你本地 Codex 环境中已设置好的身份验证。

### 前置条件

- 已安装 Codex CLI（`codex` 必须在你的 `PATH` 中可用）
- Codex CLI 已完成身份验证并可在终端中使用

### 设置步骤

<Steps>
  <Step title="打开 CLI Agents 设置">
    前往 **Settings → Models → CLI Agents**。
  </Step>
  <Step title="如缺失则添加 Codex">
    如果看不到 Codex 卡片，点击 **Add CLI Agent**。Verdent 会扫描你的系统 `PATH` 以查找 `codex` 命令。
  </Step>
  <Step title="启用 Codex">
    打开 **Codex** 开关。
  </Step>
  <Step title="选择模型">
    Verdent 会自动检测可用模型。选择你想使用的那些。
  </Step>
</Steps>

### 模型发现

Codex 模型是动态发现的。启动 Codex 后，Verdent 会通过其 `/models` API 获取可用模型。如果 Codex 侧新增了模型，点击 **Refresh Models** 即可更新列表。

### 身份验证

Verdent 不管理 Codex 的身份验证。Codex 依赖你本地的 shell 环境（通常是 `OPENAI_API_KEY` 或其内置的登录流程）。只要 `codex` 能在你的终端中正常工作，该集成就能工作。

## Claude Code

Claude Code 是 BYOA 中功能最丰富的智能体，并支持多家服务商。你可以连接 Anthropic、OpenRouter、智谱 GLM 等，并在模型选择器中切换。

### 前置条件

- 已安装 Node.js（只需 `npx`）

Verdent 通过以下方式启动 Claude Code：

```bash
npx -y @agentclientprotocol/claude-agent-acp
```

无需全局安装。

### 设置步骤

<Steps>
  <Step title="打开 CLI Agents 设置">
    前往 **Settings → Models → CLI Agents**。
  </Step>
  <Step title="如缺失则添加 Claude Code">
    如果看不到 Claude Code 卡片，点击 **Add CLI Agent**。Verdent 会检测 `npx`。
  </Step>
  <Step title="启用 Claude Code">
    打开 **Claude Code** 开关。
  </Step>
  <Step title="添加服务商">
    点击 **Add provider** 并选择一家服务商（例如 Anthropic）。
  </Step>
  <Step title="输入凭据">
    输入 API 密钥。默认值会自动填充。
  </Step>
  <Step title="测试并保存">
    可选地点击 **Test Connection**，然后点击 **Save**。
  </Step>
</Steps>

保存后，该服务商下的模型会出现在模型列表中。已启用的模型默认被选中，但可以手动切换。

### 支持的服务商

Claude Code 支持多家服务商。你可以同时配置多家，所有模型都会出现在选择器中。

#### Anthropic

用于 Claude 模型的官方 Anthropic API。

- **身份验证：** API Key
- **Base URL：** `https://api.anthropic.com`
- **模型：** Opus / Sonnet / Haiku
- **密钥：** [platform.claude.com/settings/keys](https://platform.claude.com/settings/keys)

#### OpenRouter

统一访问多家模型服务商的 API。

- **身份验证：** Token
- **Base URL：** `https://openrouter.ai/api`
- **模型：** Opus / Sonnet / Haiku
- **密钥：** [openrouter.ai/workspaces/default/keys](https://openrouter.ai/workspaces/default/keys)

你可以覆盖 Role Models，将其路由到其他 OpenRouter 模型（例如 `google/gemini-2.5-pro`）。

#### 智谱 GLM（中国）

- **Base URL：** `https://open.bigmodel.cn/api/anthropic`
- **模型：** GLM-5
- **密钥：** [bigmodel.cn/usercenter/proj-mgmt/apikeys](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
- **文档：** [docs.bigmodel.cn](https://docs.bigmodel.cn)

#### 智谱 GLM（全球）

- **Base URL：** `https://api.z.ai/api/anthropic`
- **模型：** GLM-5
- **密钥：** [z.ai/manage-apikey/apikey-list](https://z.ai/manage-apikey/apikey-list)
- **文档：** [docs.z.ai](https://docs.z.ai)

#### Kimi

- **Base URL：** `https://api.kimi.com/coding/`
- **模型：** Kimi K2.5
- **密钥：** [kimi.com/code/console](https://kimi.com/code/console)
- **文档：** [kimi.com/code/docs](https://kimi.com/code/docs)

#### Moonshot

- **Base URL：** `https://api.moonshot.cn/anthropic`
- **模型：** Kimi K2.5
- **密钥：** [platform.moonshot.cn/console/api-keys](https://platform.moonshot.cn/console/api-keys)
- **文档：** [platform.moonshot.cn/docs](https://platform.moonshot.cn/docs)

<Note>
Kimi 和 Moonshot 都提供 Kimi K2.5，但使用不同的端点和身份验证。请根据你的密钥来源进行选择。
</Note>

#### MiniMax（中国）

- **Base URL：** `https://api.minimaxi.com/anthropic`
- **模型：** MiniMax-M2.7
- **密钥：** [platform.minimaxi.com](https://platform.minimaxi.com)
- **文档：** [platform.minimaxi.com/docs](https://platform.minimaxi.com/docs)

#### MiniMax（全球）

- **Base URL：** `https://api.minimax.io/anthropic`
- **模型：** MiniMax-M2.7
- **密钥：** [platform.minimax.io](https://platform.minimax.io)
- **文档：** [platform.minimax.io/docs](https://platform.minimax.io/docs)

#### 小米 MiMo

- **Base URL：** `https://api.xiaomimimo.com/anthropic`
- **模型：** MiMo V2 Pro
- **密钥：** [platform.xiaomimimo.com](https://platform.xiaomimimo.com)
- **文档：** [platform.xiaomimimo.com/docs](https://platform.xiaomimimo.com/docs)

#### 小米 MiMo（Token Plan）

- **Base URL：** `https://token-plan-cn.xiaomimimo.com/anthropic`
- **模型：** MiMo V2 Pro
- **密钥：** [platform.xiaomimimo.com](https://platform.xiaomimimo.com)
- **文档：** [platform.xiaomimimo.com/docs](https://platform.xiaomimimo.com/docs)

#### Anthropic 兼容（自定义端点）

适用于任何兼容 Anthropic API 格式的服务。

- **身份验证：** API Key 或 Token（可切换）
- **Base URL：** 手动配置
- **模型：** 手动指定

如果你的服务商不在列表中但支持 Anthropic 兼容的 API，请使用此项。

### 高级选项

在服务商配置面板中，展开 **Advanced Options** 以访问 JSON 编辑器：

- **Role Models 映射：**
  - `ANTHROPIC_DEFAULT_OPUS_MODEL`
  - `ANTHROPIC_DEFAULT_SONNET_MODEL`
  - `ANTHROPIC_DEFAULT_HAIKU_MODEL`
  - `CLAUDE_CODE_SUBAGENT_MODEL`
- **自定义环境变量**（例如 `API_TIMEOUT_MS`）

大多数用户无需修改这些 —— 默认值开箱即用，效果良好。

## 在 Manager 中使用 BYOA 模型

配置完成后：

<Steps>
  <Step title="禁用 Auto 模式">
    关闭聊天输入框中的 **Auto** 模式。
  </Step>
  <Step title="打开 Task Model">
    打开 **Task Model** 下拉菜单。
  </Step>
  <Step title="选择 BYOA 模型">
    选择任意已启用的 BYOA 模型。Worker 任务将使用该模型运行。
  </Step>
</Steps>

模型会显示为：

- `GPT-5.4 Codex-CLI`（来自 Codex）
- `Claude-Opus-4.7 ClaudeCode-CLI`（来自 Claude Code）

悬停可查看 CLI 来源、模型名称和服务商等详细信息。

## 安全与隐私

- **仅本地存储：** API 密钥存储在本地，绝不上传。
- **Claude Code 密钥：** 安全存储，不会写入明文配置文件。
- **Codex 身份验证：** 完全由你的本地环境管理；Verdent 不访问 OpenAI 密钥。

## 常见问题

### 未检测到 CLI 智能体？

确保命令在 `PATH` 中可用：

- Claude Code 需要 `npx`（已安装 Node.js）
- Codex 需要已安装 `codex` CLI

运行：

```bash
which npx
which codex
```

### Test Connection 失败？

- 核对 API 密钥
- 检查 base URL
- 确保可以访问 API 端点的网络
- 如使用代理，检查代理配置

### 已添加服务商但看不到模型？

- 确保已启用 Claude Code
- 确保服务商模型已开启
- 必要时重启 Verdent