zclaw_openfang/docs/knowledge-base/agent-provider-config.md

# Agent 和 LLM 提供商配置

> 记录 ZCLAW Agent 配置和 LLM 提供商设置。

---

## 1. 配置文件位置

```
~/.zclaw/
├── config.toml      # 主配置文件
├── .env             # 环境变量 (API Keys)
├── secrets.env      # 敏感信息
└── data/            # Agent 数据
```

---

## 2. 主配置文件

### config.toml 示例

```toml
[default_model]
provider = "bailian"
model = "qwen3.5-plus"
api_key_env = "BAILIAN_API_KEY"

[kernel]
data_dir = "C:\\Users\\szend\\.zclaw\\data"

[memory]
decay_rate = 0.05
```

### 配置项说明

| 配置项 | 说明 | 示例值 |
|--------|------|--------|
| `default_model.provider` | 默认 LLM 提供商 | `bailian`, `zhipu`, `gemini` |
| `default_model.model` | 默认模型名称 | `qwen3.5-plus`, `glm-4-flash` |
| `default_model.api_key_env` | API Key 环境变量名 | `BAILIAN_API_KEY` |
| `kernel.data_dir` | 数据目录 | `~/.zclaw/data` |
| `memory.decay_rate` | 记忆衰减率 | `0.05` |

---

## 3. LLM 提供商配置

### 3.1 支持的提供商

| 提供商 | 环境变量 | 模型示例 |
|--------|----------|----------|
| zhipu | `ZHIPU_API_KEY` | glm-4-flash, glm-4-plus |
| bailian | `BAILIAN_API_KEY` | qwen3.5-plus, qwen-max |
| gemini | `GEMINI_API_KEY` | gemini-2.5-flash |
| deepseek | `DEEPSEEK_API_KEY` | deepseek-chat |
| openai | `OPENAI_API_KEY` | gpt-4, gpt-3.5-turbo |
| groq | `GROQ_API_KEY` | llama-3.1-70b |

### 3.2 配置 API Key

**方式 1: .env 文件**

```bash
# ~/.zclaw/.env
ZHIPU_API_KEY=your_zhipu_key_here
BAILIAN_API_KEY=your_bailian_key_here
GEMINI_API_KEY=your_gemini_key_here
DEEPSEEK_API_KEY=your_deepseek_key_here
```

**方式 2: 环境变量**

```bash
# Windows PowerShell
$env:ZHIPU_API_KEY = "your_key"
./zclaw.exe start

# Linux/macOS
export ZHIPU_API_KEY=your_key
./zclaw start
```

### 3.3 验证配置

```bash
# 检查 Agent 状态
curl -s http://127.0.0.1:50051/api/status | jq '.agents[] | {name, model_provider, model_name, state}'

# 测试聊天
curl -X POST "http://127.0.0.1:50051/api/agents/{agentId}/message" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}'
```

---

## 4. Agent 管理

### 4.1 查看所有 Agent

```bash
curl -s http://127.0.0.1:50051/api/agents | jq
```

返回示例：
```json
[
  {
    "id": "f77004c8-418f-4132-b7d4-7ecb9d66f44c",
    "name": "General Assistant",
    "model_provider": "zhipu",
    "model_name": "glm-4-flash",
    "state": "Running"
  },
  {
    "id": "ad95a98b-459e-4eac-b1b4-c7130fe5519a",
    "name": "sales-assistant",
    "model_provider": "bailian",
    "model_name": "qwen3.5-plus",
    "state": "Running"
  }
]
```

### 4.2 Agent 状态

| 状态 | 说明 |
|------|------|
| `Running` | 正常运行 |
| `Stopped` | 已停止 |
| `Error` | 错误状态 |

### 4.3 默认 Agent 选择

前端代码应动态选择可用的 Agent：

```typescript
// gatewayStore.ts
loadClones: async () => {
  const client = get().client;
  const clones = await client.getClones();

  // 自动设置第一个可用 Agent 为默认
  if (clones.length > 0 && clones[0].id) {
    const currentDefault = client.getDefaultAgentId();
    const defaultExists = clones.some(c => c.id === currentDefault);

    if (!defaultExists) {
      client.setDefaultAgentId(clones[0].id);
    }
  }

  set({ clones });
}
```

---

## 5. 常见问题

### 5.1 "Missing API key" 错误

**症状**:
```
Missing API key: No LLM provider configured.
Set an API key (e.g. GROQ_API_KEY) and restart
```

**解决方案**:

1. 检查 Agent 使用的提供商：
```bash
curl -s http://127.0.0.1:50051/api/agents | jq '.[] | select(.name=="AgentName") | .model_provider'
```

2. 配置对应的 API Key：
```bash
echo "PROVIDER_API_KEY=your_key" >> ~/.zclaw/.env
```

3. 重启 ZCLAW：
```bash
./zclaw.exe restart
```

### 5.2 找到可用的 Agent

当某个 Agent 的提供商未配置时，切换到其他 Agent：

| 推荐顺序 | Agent | 提供商 | 说明 |
|---------|-------|--------|------|
| 1 | General Assistant | zhipu | 通常已配置 |
| 2 | coder | gemini | 开发任务 |
| 3 | researcher | gemini | 研究任务 |

### 5.3 API Key 验证失败

**症状**: `Request failed: Invalid API key`

**检查**:
1. API Key 格式是否正确
2. API Key 是否过期
3. 提供商服务是否可用

---

## 6. 前端集成

### 6.1 显示 Agent 信息

```typescript
function AgentSelector() {
  const clones = useGatewayStore((state) => state.clones);
  const currentAgent = useChatStore((state) => state.currentAgent);

  return (
    <select value={currentAgent?.id} onChange={handleAgentChange}>
      {clones.map((agent) => (
        <option key={agent.id} value={agent.id}>
          {agent.name} ({agent.model_provider})
        </option>
      ))}
    </select>
  );
}
```

### 6.2 处理提供商错误

```typescript
onError: (error: string) => {
  if (error.includes('Missing API key')) {
    // 提示用户配置 API Key 或切换 Agent
    showNotification({
      type: 'warning',
      message: '当前 Agent 的 LLM 提供商未配置，请切换到其他 Agent',
    });
  }
}
```

---

## 7. 配置最佳实践

### 7.1 多提供商配置

配置多个提供商作为备用：

```bash
# ~/.zclaw/.env
ZHIPU_API_KEY=your_primary_key
BAILIAN_API_KEY=your_backup_key
GEMINI_API_KEY=your_gemini_key
```

### 7.2 模型选择策略

| 用途 | 推荐模型 | 提供商 |
|------|----------|--------|
| 日常对话 | glm-4-flash | zhipu |
| 开发任务 | gemini-2.5-flash | gemini |
| 深度推理 | qwen3.5-plus | bailian |
| 快速响应 | deepseek-chat | deepseek |

### 7.3 错误恢复

```typescript
async function sendMessageWithFallback(content: string) {
  const agents = useGatewayStore.getState().clones;

  for (const agent of agents) {
    try {
      return await client.chatStream(content, callbacks, { agentId: agent.id });
    } catch (err) {
      if (err.message.includes('Missing API key')) {
        console.warn(`Agent ${agent.name} not configured, trying next...`);
        continue;
      }
      throw err;
    }
  }

  throw new Error('No configured agents available');
}
```

---

## 更新历史

| 日期 | 变更 |
|------|------|
| 2026-03-14 | 初始版本 |