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 示例

[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 文件

# ~/.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: 环境变量

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

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

3.3 验证配置

# 检查 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

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

返回示例：

[
  {
    "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：

// 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 使用的提供商：

curl -s http://127.0.0.1:50051/api/agents | jq '.[] | select(.name=="AgentName") | .model_provider'

2. 配置对应的 API Key：

echo "PROVIDER_API_KEY=your_key" >> ~/.zclaw/.env

3. 重启 ZCLAW：

./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 信息

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 处理提供商错误

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

---

7. 配置最佳实践

7.1 多提供商配置

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

# ~/.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 错误恢复

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	初始版本