# 大模型配置

Device Agent 使用大模型生成设备规格、理解对话并调用设备命令。开始快速体验前，至少需要配置一个可用的大模型。

## 控制台配置

设备智能体启动后，打开控制台 `http://127.0.0.1:3000`，进入 **设置 → 模型**，在 **智能体模型** 区域配置：

| 字段 | 说明 |
| --- | --- |
| 提供商 | 选择大模型服务商。常见入口包括 `openai`、`anthropic`、`qwen`、`kimi`、`ollama`、`openai-compatible` 等。 |
| 模型 | 选择或填写模型 ID。下拉选项来自所选服务商的可用模型列表；`openai-compatible` 这类自定义入口可以手动填写模型 ID。 |
| 接口密钥 | 填写所选服务商的 API Key。 |
| 基础地址 | 自定义 OpenAI 兼容接口或本地模型服务时填写。`openai-compatible` 通常需要填写；`ollama` 未填写时默认使用 `http://localhost:11434/v1`。 |
| 最大迭代次数 | 单次请求中智能体可执行的最大推理和工具调用轮次，通常保持默认值即可。 |

保存后，如果页面提示大模型配置需要重启，请重启 Agent Gateway 后继续。

## 大模型服务商

不同版本、部署方式下可选服务商和模型可能不同，以控制台 **设置 → 模型** 中显示的列表为准。

常见入口包括：

- OpenAI（`openai`）
- Anthropic（`anthropic`）
- Qwen / DashScope（`qwen`）
- Kimi（`kimi`）
- Ollama（`ollama`）
- OpenAI 兼容接口（`openai-compatible`）
- Google / Google Vertex（`google`、`google-vertex`）
- DeepSeek（`deepseek`）
- OpenRouter（`openrouter`）
- xAI（`xai`）
- Groq（`groq`）
- Mistral（`mistral`）
- Amazon Bedrock（`amazon-bedrock`）
- Azure OpenAI Responses（`azure-openai-responses`）
- Vercel AI Gateway（`vercel-ai-gateway`）
- GitHub Copilot（`github-copilot`）
- OpenCode（`opencode`、`opencode-go`）
- Codex（`openai-codex`）

常见配置方式如下：

| 类型 | 示例 `LLM_PROVIDER` | 配置方式 |
| --- | --- | --- |
| OpenAI | `openai` | 设置 `OPENAI_API_KEY`。只有使用代理或自定义兼容地址时才填写 **基础地址**。 |
| Anthropic | `anthropic` | 设置 `ANTHROPIC_API_KEY`。 |
| 其他服务商 | `google`、`deepseek`、`openrouter`、`xai`、`groq`、`mistral` 等 | 在控制台选择服务商和模型，填写 **接口密钥**。启动前配置时可用 `LLM_API_KEY`。 |
| OpenAI 兼容接口 | `openai-compatible` | 填写自定义模型 ID、`LLM_BASE_URL` 和 `LLM_API_KEY`。也可以用 `OPENAI_API_KEY` 提供密钥。 |
| Qwen / DashScope | `qwen` | 设置 `QWEN_API_KEY`。默认使用 `https://dashscope.aliyuncs.com/compatible-mode/v1`。 |
| Kimi | `kimi` | 设置 `KIMI_API_KEY`。也可以用 `OPENAI_API_KEY` 作为兼容密钥。默认使用 `https://api.moonshot.cn/v1`。 |
| Kimi Coding | `kimi-coding` | 设置 `KIMI_API_KEY`。 |
| Ollama | `ollama` | 本地模型服务，默认地址为 `http://localhost:11434/v1`，通常不需要 API Key。 |
| Codex | `openai-codex` | 认证方式特殊，见下方 Codex 说明。 |

常用示例：`openai` / `gpt-5.5`、`anthropic` / `claude-sonnet-4-6`、`qwen` / `qwen-plus`、`ollama` / `llama3.2`。

### Codex 认证

`openai-codex` 不按普通 OpenAI API Key 方式配置。推荐先在运行 Device Agent 的机器上完成 Codex CLI 登录，
让系统读取默认的 `~/.codex/auth.json`。也可以使用下面任一方式覆盖：

```bash
LLM_PROVIDER=openai-codex
LLM_MODEL=<codex-model-id>
OPENAI_CODEX_AUTH_FILE=/path/to/auth.json
```

或直接提供访问令牌：

```bash
LLM_PROVIDER=openai-codex
LLM_MODEL=<codex-model-id>
OPENAI_CODEX_ACCESS_TOKEN=...
```

在控制台中选择 `openai-codex` 时，普通 **接口密钥** 字段会作为 Codex 访问令牌覆盖；**Codex 认证文件**
字段用于指定 `auth.json` 路径。未填写时会尝试使用 Codex CLI 的默认认证文件。

## `.env` 配置

首次启动、容器部署或无 UI 环境可以用 `.env` 配置大模型。下面是常用示例。

OpenAI：

```bash
LLM_PROVIDER=openai
LLM_MODEL=gpt-5.5
OPENAI_API_KEY=sk-...
```

Qwen：

```bash
LLM_PROVIDER=qwen
LLM_MODEL=qwen-plus
QWEN_API_KEY=sk-...
```

OpenAI 兼容接口：

```bash
LLM_PROVIDER=openai-compatible
LLM_MODEL=your-model-id
LLM_BASE_URL=https://llm.example.com/v1
LLM_API_KEY=sk-...
```

Ollama：

```bash
LLM_PROVIDER=ollama
LLM_MODEL=llama3.2
LLM_BASE_URL=http://localhost:11434/v1
```

Codex：

```bash
LLM_PROVIDER=openai-codex
LLM_MODEL=<codex-model-id>
OPENAI_CODEX_AUTH_FILE=~/.codex/auth.json
```

`.env` 中的值会在启动时写入或覆盖 `.device_agent/config.json`。如果后续想长期使用控制台保存的值，请移除 `.env` 中同名变量，或保持两边一致。

## 大模型要求

快速体验需要模型能够稳定完成结构化生成和工具调用。建议选择支持工具调用、上下文窗口不低于 8K 的模型；设备描述较长或会话中包含较多设备状态时，建议使用 32K 或更大的上下文窗口。

## 视觉模型

视觉模型用于摄像头图像、截图和多模态输入分析。快速体验普通设备控制时可以先不配置。

| 模式 | 配置 | 说明 |
| --- | --- | --- |
| 自动 | `VISION_PROVIDER=auto` | 默认模式。复用主智能体模型；只有主模型支持图像输入时可用，不需要单独 API Key。 |
| DashScope | `VISION_PROVIDER=dashscope`、`VISION_MODEL=qwen-vl-plus` 或 `qwen-vl-max`、`VISION_API_KEY=...` | 使用独立 Qwen VL 模型，适合主智能体模型不支持图像输入，或希望视觉能力单独配置的场景。 |

控制台中对应 **视觉模型** 区域，可以设置是否启用、服务商、模型、API Key 和超时时间。

更多配置入口和生效规则见 [配置](../configuration.md)。