feat(hands): restructure Hands UI with Chinese localization
Major changes: - Add HandList.tsx component for left sidebar - Add HandTaskPanel.tsx for middle content area - Restructure Sidebar tabs: 分身/HANDS/Workflow - Remove Hands tab from RightPanel - Localize all UI text to Chinese - Archive legacy OpenClaw documentation - Add Hands integration lessons document - Update feature checklist with new components UI improvements: - Left sidebar now shows Hands list with status icons - Middle area shows selected Hand's tasks and results - Consistent styling with Tailwind CSS - Chinese status labels and buttons Documentation: - Create docs/archive/openclaw-legacy/ for old docs - Add docs/knowledge-base/hands-integration-lessons.md - Update docs/knowledge-base/feature-checklist.md - Update docs/knowledge-base/README.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
iven
296
docs/knowledge-base/agent-provider-config.md
Normal file
296
docs/knowledge-base/agent-provider-config.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# Agent 和 LLM 提供商配置
|
||||
|
||||
> 记录 OpenFang Agent 配置和 LLM 提供商设置。
|
||||
|
||||
---
|
||||
|
||||
## 1. 配置文件位置
|
||||
|
||||
```
|
||||
~/.openfang/
|
||||
├── 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\\.openfang\\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` | 数据目录 | `~/.openfang/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
|
||||
# ~/.openfang/.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"
|
||||
./openfang.exe start
|
||||
|
||||
# Linux/macOS
|
||||
export ZHIPU_API_KEY=your_key
|
||||
./openfang 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" >> ~/.openfang/.env
|
||||
```
|
||||
|
||||
3. 重启 OpenFang：
|
||||
```bash
|
||||
./openfang.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
|
||||
# ~/.openfang/.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 | 初始版本 |
|
||||
Reference in New Issue
Block a user