zclaw_openfang/docs/knowledge-base/openfang-configuration.md

OpenFang 配置指南

记录 OpenFang 配置文件位置、格式和最佳实践。

---

1. 配置文件位置

~/.openfang/
├── config.toml      # 主配置文件（启动时读取）
├── .env             # API Key 环境变量
├── secrets.env      # 敏感信息（可选）
├── daemon.json      # 守护进程状态
└── data/
    └── openfang.db  # SQLite 数据库（持久化配置）

---

2. 主配置文件 (config.toml)

智谱 (Zhipu) 配置

[default_model]
provider = "zhipu"
model = "glm-4-flash"
api_key_env = "ZHIPU_API_KEY"

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

[memory]
decay_rate = 0.05

百炼 (Bailian) 配置

[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 提供商	zhipu, bailian, gemini
default_model.model	默认模型名称	glm-4-flash, qwen3.5-plus
default_model.api_key_env	API Key 环境变量名	ZHIPU_API_KEY
kernel.data_dir	数据目录	~/.openfang/data
memory.decay_rate	记忆衰减率	0.05

---

3. API Key 配置

方式 1: .env 文件（推荐）

# ~/.openfang/.env
ZHIPU_API_KEY=sk-sp-xxxxx
BAILIAN_API_KEY=sk-sp-xxxxx
GEMINI_API_KEY=your_gemini_key
DEEPSEEK_API_KEY=your_deepseek_key
OPENAI_API_KEY=your_openai_key
GROQ_API_KEY=your_groq_key

方式 2: secrets.env 文件

# ~/.openfang/secrets.env
ZHIPU_API_KEY=sk-sp-xxxxx
BAILIAN_API_KEY=sk-sp-xxxxx

方式 3: 通过 API 设置

# 设置智谱密钥
curl -X POST http://127.0.0.1:50051/api/providers/zhipu/key \
  -H "Content-Type: application/json" \
  -d '{"key":"your-zhipu-api-key"}'

# 设置百炼密钥
curl -X POST http://127.0.0.1:50051/api/providers/bailian/key \
  -H "Content-Type: application/json" \
  -d '{"key":"your-bailian-api-key"}'

方式 4: 启动时指定环境变量

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

# Linux/macOS
ZHIPU_API_KEY=sk-sp-xxx ./openfang start

---

4. 支持的 Provider

4.1 国内 Provider

Provider	环境变量	Base URL	说明
zhipu	ZHIPU_API_KEY	https://open.bigmodel.cn/api/paas/v4	智谱 GLM
zhipu_coding	ZHIPU_API_KEY	https://open.bigmodel.cn/api/coding/paas/v4	智谱 CodeGeeX
bailian	BAILIAN_API_KEY	https://coding.dashscope.aliyuncs.com/v1	百炼 Coding Plan
qwen	DASHSCOPE_API_KEY	https://dashscope.aliyuncs.com/compatible-mode/v1	通义千问
volcengine	VOLCENGINE_API_KEY	https://ark.cn-beijing.volces.com/api/v3	火山引擎 Doubao
moonshot	MOONSHOT_API_KEY	https://api.moonshot.ai/v1	Moonshot Kimi
deepseek	DEEPSEEK_API_KEY	https://api.deepseek.com/v1	DeepSeek

4.2 国际 Provider

Provider	环境变量	Base URL	说明
openai	OPENAI_API_KEY	https://api.openai.com/v1	OpenAI GPT
anthropic	ANTHROPIC_API_KEY	https://api.anthropic.com	Anthropic Claude
gemini	GEMINI_API_KEY	https://generativelanguage.googleapis.com	Google Gemini
groq	GROQ_API_KEY	https://api.groq.com/openai/v1	Groq
mistral	MISTRAL_API_KEY	https://api.mistral.ai/v1	Mistral AI
xai	XAI_API_KEY	https://api.x.ai/v1	xAI Grok

4.3 本地 Provider

Provider	环境变量	Base URL	说明
ollama	-	http://localhost:11434/v1	Ollama 本地
vllm	-	http://localhost:8000/v1	vLLM 本地
lmstudio	-	http://localhost:1234/v1	LM Studio 本地

---

5. 可用模型

智谱 (Zhipu)

模型 ID	说明	适用场景
glm-4-flash	快速模型	日常对话、快速响应
glm-4-plus	高级模型	复杂推理、深度分析
glm-4	标准模型	通用场景
glm-4-air	轻量模型	简单任务

百炼 (Bailian)

模型 ID	说明	适用场景
qwen3.5-plus	通用对话	日常对话
qwen3-coder-next	编码专家	代码生成
glm-5-bailian	GLM-5	通用场景
minimax-m2.5-bailian	支持视觉	多模态任务
kimi-k2.5-bailian	Kimi K2.5	长文本处理

其他推荐模型

Provider	模型 ID	适用场景
gemini	gemini-2.5-flash	开发任务
deepseek	deepseek-chat	快速响应
groq	llama-3.1-70b	开源模型

---

6. 快速切换 Provider

方法 A: 修改 config.toml

# 切换到智谱
[default_model]
provider = "zhipu"
model = "glm-4-flash"
api_key_env = "ZHIPU_API_KEY"

# 切换到百炼
[default_model]
provider = "bailian"
model = "qwen3.5-plus"
api_key_env = "BAILIAN_API_KEY"

重要: 修改后必须完全重启 OpenFang！

方法 B: 创建不同配置的 Agent

# 创建使用智谱的 Agent
curl -X POST http://127.0.0.1:50051/api/agents \
  -H "Content-Type: application/json" \
  -d '{"manifest_toml": "name = \"Zhipu Agent\"\nmodel_provider = \"zhipu\"\nmodel_name = \"glm-4-flash\""}'

# 创建使用百炼的 Agent
curl -X POST http://127.0.0.1:50051/api/agents \
  -H "Content-Type: application/json" \
  -d '{"manifest_toml": "name = \"Bailian Agent\"\nmodel_provider = \"bailian\"\nmodel_name = \"qwen3.5-plus\""}'

---

7. 配置验证

检查当前配置

# 检查 API 返回的配置
curl -s http://127.0.0.1:50051/api/config

# 检查状态
curl -s http://127.0.0.1:50051/api/status | grep -E "default_provider|default_model"

# 检查所有 Provider 状态
curl -s http://127.0.0.1:50051/api/providers | grep -E "id|auth_status"

检查 Agent 配置

# 列出所有 Agent 及其 Provider
curl -s http://127.0.0.1:50051/api/agents | grep -E "name|model_provider|ready"

测试聊天

# 测试 Agent 是否能正常响应
curl -X POST "http://127.0.0.1:50051/api/agents/{agentId}/message" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}'

---

8. 重要注意事项

8.1 配置热重载限制

关键: OpenFang 将配置持久化在 SQLite 数据库中，config.toml 只在启动时读取。

• /api/config/reload 不会更新已持久化的默认模型配置
• 修改 config.toml 后必须完全重启 OpenFang

# 正确的重启方式
curl -X POST http://127.0.0.1:50051/api/shutdown
# 然后手动启动
./openfang.exe start

8.2 Agent 创建时的 Provider

如果创建 Agent 时没有指定 Provider，OpenFang 会使用数据库中存储的默认配置，而不是 config.toml 中的配置。

8.3 API Key 验证

确保 API Key 格式正确：

• 智谱: sk-sp-xxxxx 或 xxxxx.xxxxx.xxxxx
• 百炼: sk-xxxxx

---

9. 常见问题

Q: 修改 config.toml 后配置没有生效？

A: 必须完全重启 OpenFang，热重载不会更新持久化配置。

Q: Agent 显示 ready: false？

A: 检查 Agent 使用的 Provider 是否配置了 API Key：

curl -s http://127.0.0.1:50051/api/agents | grep -E "auth_status|ready"

Q: 如何查看所有可用的 Provider？

A:

curl -s http://127.0.0.1:50051/api/providers

Q: 如何在不重启的情况下切换 Agent？

A: 前端可以通过选择不同 Provider 的 Agent 来切换，无需重启。

---

更新历史

日期	变更
2026-03-17	初始版本，记录配置热重载限制