故障排除与常见问题

LibreFang 常见问题、诊断方法及常见问题解答。

目录

• 快速诊断
• 安装问题
• 配置问题
• LLM 提供商问题
• 通道问题
• Agent 问题
• 插件问题
• API 问题
• 桌面应用问题
• 性能
• 常见问题解答

快速诊断

运行内置诊断工具：

librefang doctor

该命令会检查以下内容：

• 配置文件是否存在且为有效的 TOML 格式
• 环境变量中是否设置了 API 密钥
• 数据库是否可访问
• 守护进程状态（是否正在运行）
• 端口可用性
• 工具依赖项（Python、signal-cli 等）

审计检查（Audit checks）

librefang doctor 还会跑一组注册的 AuditCheck — 针对实际中最常见误配置的有主见 lint。每个检查返回 pass / warn / fail 之一；--json 输出机器可读 bundle。

新增检查：在 crates/librefang-cli/src/doctor.rs 里实现 AuditCheck trait，在 registered_checks() 里注册即可。

前台守护进程日志文件

librefang start --foreground（just dev 和很多 supervisor 用的模式）现在把 stdout 同时输出到终端和按日轮转的日志文件 ~/.librefang/logs/daemon-YYYY-MM-DD.log。当天重启追加进同一文件；新一天起一个新文件。daemon 下次启动时会清掉 7 天以上的旧文件。

之前前台路径只写终端，supervisor 把日志滚出去就丢了。

tail -f ~/.librefang/logs/daemon-$(date +%F).log

检查守护进程状态

librefang status

通过 API 检查健康状态

curl http://127.0.0.1:4545/api/health
curl http://127.0.0.1:4545/api/health/detail  # Requires auth

查看日志

LibreFang 使用 tracing 进行结构化日志记录。通过环境变量设置日志级别：

RUST_LOG=info librefang start          # Default
RUST_LOG=debug librefang start         # Verbose
RUST_LOG=librefang=debug librefang start  # Only LibreFang debug, deps at info

安装问题

cargo install 编译失败

原因：Rust 工具链版本过旧或缺少系统依赖。

解决方案：

rustup update stable
rustup default stable
rustc --version  # Need 1.75+

在 Linux 上，可能还需要安装以下依赖：

# Debian/Ubuntu
sudo apt install pkg-config libssl-dev libsqlite3-dev

# Fedora
sudo dnf install openssl-devel sqlite-devel

安装后找不到 librefang 命令

解决方案：确保 ~/.cargo/bin 在 PATH 中：

export PATH="$HOME/.cargo/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc to persist

Docker 容器无法启动

常见原因：

• 未提供 API 密钥：docker run -e GROQ_API_KEY=... ghcr.io/librefang/librefang
• 端口已被占用：更换端口映射 -p 3001:4545
• 卷挂载权限不足：检查目录权限

配置问题

"Config file not found"

解决方案：运行 librefang init 创建默认配置：

librefang init

这会在 ~/.librefang/config.toml 创建包含合理默认值的配置文件。

启动时出现 "Missing API key" 警告

原因：环境变量中未找到 LLM 提供商的 API 密钥。

解决方案：至少设置一个提供商密钥：

export GROQ_API_KEY="gsk_..."     # Groq (free tier available)
# OR
export ANTHROPIC_API_KEY="sk-ant-..."
# OR
export OPENAI_API_KEY="sk-..."

将上述配置添加到 shell 配置文件中以便跨会话持久化。

配置验证错误

手动运行验证：

librefang config show

常见问题：

• TOML 语法格式错误（可使用 TOML 验证工具）
• 无效的端口号（必须在 1-65535 范围内）
• 通道配置中缺少必填字段

"Port already in use"

解决方案：在配置中更改端口或终止占用端口的进程：

# Change API port
# In config.toml:
# [api]
# listen_addr = "127.0.0.1:3001"

# Or find and kill the process using the port
# Linux/macOS:
lsof -i :4545
# Windows:
netstat -aon | findstr :4545

LLM 提供商问题

"Authentication failed" / 401 错误

原因：

• API 密钥未设置或不正确
• API 密钥已过期或被撤销
• 环境变量名称错误

解决方案：验证密钥是否正确：

# Check if the env var is set
echo $GROQ_API_KEY

# Test the provider
curl http://127.0.0.1:4545/api/providers/groq/test -X POST

"Rate limited" / 429 错误

原因：对 LLM 提供商的请求过于频繁。

解决方案：

• 驱动层会自动以指数退避策略进行重试
• 降低 Agent 能力配置中的 max_llm_tokens_per_hour
• 切换到速率限制更高的提供商
• 使用多个提供商配合模型路由

响应缓慢

可能原因：

• 提供商 API 延迟（可尝试 Groq 获得更快的推理速度）
• 上下文窗口过大（使用 /compact 压缩会话）
• 工具链调用复杂（检查响应中的迭代次数）

解决方案：使用 Agent 级别的模型覆盖配置，为简单 Agent 分配更快的模型：

[model]
provider = "groq"
model = "llama-3.1-8b-instant"  # Fast, small model

"Model not found"

解决方案：检查可用模型列表：

curl http://127.0.0.1:4545/api/models

或使用别名：

[model]
model = "llama"  # Alias for llama-3.3-70b-versatile

查看完整的别名列表：

curl http://127.0.0.1:4545/api/models/aliases

Ollama / 本地模型无法连接

解决方案：确保本地服务器正在运行：

# Ollama
ollama serve  # Default: http://localhost:11434

# vLLM
python -m vllm.entrypoints.openai.api_server --model ...

# LM Studio
# Start from the LM Studio UI, enable API server

通道问题

Telegram 机器人无响应

检查清单：

1. 机器人令牌是否正确：echo $TELEGRAM_BOT_TOKEN
2. 机器人是否已启动（在 Telegram 中发送 /start）
3. 如果设置了 allowed_users，确认你的 Telegram 用户 ID 在列表中
4. 检查日志中的 "Telegram adapter" 相关消息

Discord 机器人离线

检查清单：

1. 机器人令牌是否正确
2. 在 Discord 开发者门户中是否启用了 Message Content Intent
3. 机器人是否已被邀请到服务器且拥有正确的权限
4. 检查日志中的 Gateway 连接信息

Slack 机器人收不到消息

检查清单：

1. 已设置 SLACK_BOT_TOKEN（xoxb-）和 SLACK_APP_TOKEN（xapp-）
2. 在 Slack 应用设置中已启用 Socket Mode
3. 机器人已被添加到需要监听的频道
4. 所需权限范围：chat:write、app_mentions:read、im:history、im:read、im:write

基于 Webhook 的通道（WhatsApp、LINE、Viber 等）

检查清单：

1. 服务器可被公网访问（或使用 ngrok 等隧道工具）
2. 在平台控制台中正确配置了 Webhook URL
3. Webhook 端口已开放且未被防火墙阻止
4. 配置中的验证令牌与平台控制台中的一致

"Channel adapter failed to start"

常见原因：

• 令牌缺失或无效
• 端口已被占用（针对基于 Webhook 的通道）
• 网络连接问题

检查日志获取具体错误信息：

RUST_LOG=librefang_channels=debug librefang start

Agent 问题

Agent 陷入循环

原因：Agent 使用相同参数反复调用同一工具。

自动保护机制：LibreFang 内置了循环守卫：

• 相同工具调用达 3 次时警告
• 相同工具调用达 5 次时阻止
• 总阻止次数达 30 次时触发熔断器（停止 Agent）

手动修复：取消 Agent 的当前运行：

curl -X POST http://127.0.0.1:4545/api/agents/{id}/stop

或通过聊天命令：/stop

Agent 上下文耗尽

原因：对话历史超出模型的上下文窗口大小。

解决方案：压缩会话：

curl -X POST http://127.0.0.1:4545/api/agents/{id}/session/compact

或通过聊天命令：/compact

当会话达到阈值时会自动触发压缩（可在运行时配置；未在 config.toml 中暴露）。

Agent 不使用工具

原因：Agent 的能力配置中未授权相关工具。

解决方案：检查 Agent 的清单文件：

[capabilities]
tools = ["file_read", "web_fetch", "shell_exec"]  # Must list each tool
# OR
# tools = ["*"]  # Grant all tools (use with caution)

Agent 响应中出现 "Permission denied" 错误

原因：Agent 尝试使用的工具或访问的资源不在其能力范围内。

解决方案：在 Agent 清单中添加所需的能力。常见配置：

• tools = [...] 用于工具访问
• network = ["*"] 用于网络访问
• memory_write = ["self.*"] 用于内存写入
• shell = ["*"] 用于 shell 命令（谨慎使用）

Agent 创建失败

检查：

1. TOML 清单文件是否有效：librefang agent spawn --dry-run manifest.toml
2. LLM 提供商是否已配置且密钥有效
3. 清单中指定的模型是否存在于模型目录中

插件问题

Context engine 插件静默失效

原因：通常是插件声明的 runtime 在这台机器上没装。hook 会以 LauncherNotFound 失败，LibreFang 打一条 warning 日志，回退到默认 context engine —— 所以不会崩、表面上没变化、但召回的 memories 永远不回来。

诊断：调 doctor 端点。

curl http://127.0.0.1:4545/api/plugins/doctor

重点看：

• runtimes[].available: false → 对应 runtime 的 launcher（比如 go、deno、ruby）不在 PATH 上。按 install_hint 字段的提示装。
• plugins[].runtime_available: false → 插件声明的 runtime 缺失。
• plugins[].hooks_valid: false → plugin.toml 里声明的 hook 脚本在磁盘上不存在。

Docker 环境里大部分 runtime 没预装 —— 参考 Configuration → Plugins 里的 RUN snippet 自己 extend 镜像。

Hook 脚本卡住 / 超时

原因：hook 有 30 秒墙钟超时。常见坑：阻塞网络调用、stdin 没关闭、误读 input() / readline 但没数据。

检查：

1. 手动测 hook：echo '{"type":"ingest","agent_id":"t","message":"hi","peer_id":null}' | python3 hooks/ingest.py —— 应该打一行然后退出。
2. 如果 hang 住，脚本在读 stdin 以外的东西。
3. 看 LibreFang 日志里提到你 hook 的 Timeout 条目。

Hook 跑了但 memories 没出来

原因：输出不是合法 JSON，或者 stdout 最后一行不是 JSON 响应。

LibreFang 从 stdout 最后一行往前扫，取第一个能 parse 的 JSON 行。在 JSON 前面打的 debug log 不影响；后面打的也不影响；但如果最后一行是 done. 或者 traceback 之类的东西，响应就丢了。

检查：本地把 stdout 通过 tail -n1 过一遍，确认最后一行是合法的 {"type": "ingest_result", ...} 对象。

插件装了但没加载

原因：config.toml 里没配 plugin 或 hooks 字段。

[context_engine]
plugin = "your-plugin-name"   # 解析到 ~/.librefang/plugins/your-plugin-name/

或者手动配 hook 不装插件目录：

[context_engine.hooks]
ingest = "~/.librefang/scripts/my_ingest.py"
runtime = "python"

改完配置重启 LibreFang。

API 问题

401 Unauthorized

原因：需要 API 密钥但未提供。

解决方案：在请求中包含 Bearer 令牌：

curl -H "Authorization: Bearer your-api-key" http://127.0.0.1:4545/api/agents

429 Too Many Requests

原因：触发了 GCRA 速率限制器。

解决方案：等待 Retry-After 指定的时间，或在配置中提高速率限制：

[api]
rate_limit_per_second = 20  # Increase if needed

浏览器中出现 CORS 错误

原因：尝试从不同的源访问 API。

解决方案：在 CORS 配置中添加你的源：

[api]
cors_origins = ["http://localhost:5173", "https://your-app.com"]

WebSocket 断开连接

可能原因：

• 空闲超时（定期发送 ping）
• 网络中断（自动重连）
• Agent 崩溃（检查日志）

客户端修复方案：实现带指数退避的重连逻辑。

OpenAI 兼容 API 与我的工具不兼容

检查清单：

1. 使用 POST /v1/chat/completions（而非 /api/agents/{id}/message）
2. 将模型设置为 librefang:agent-name（例如 librefang:coder）
3. 流式传输：设置 "stream": true 以获取 SSE 响应
4. 图片：使用 image_url 并采用 data:image/png;base64,... 格式

桌面应用问题

应用无法启动

检查清单：

1. 同一时间只能运行一个实例（单实例限制）
2. 检查守护进程是否已在相同端口运行
3. 尝试删除 ~/.librefang/daemon.json 后重启

应用显示白屏/空白页

原因：内嵌的 API 服务器尚未启动完成。

解决方案：等待几秒钟。如果问题持续存在，检查日志中的服务器启动错误。

系统托盘图标缺失

平台相关说明：

• Linux：需要系统托盘支持（如 GNOME 上的 libappindicator）
• macOS：开箱即用
• Windows：检查通知区域设置，可能需要显示隐藏图标

性能

内存占用过高

建议：

• 减少并发 Agent 数量
• 对长时间运行的 Agent 使用会话压缩
• 对简单任务使用较小的模型（用 Llama 8B 代替 70B）
• 清除旧会话：DELETE /api/sessions/{id}

启动缓慢

正常启动时间：内核 <200ms，加载通道适配器后 ~1-2s。

如果更慢，请检查：

• 数据库大小（~/.librefang/data/librefang.db）
• 减少已启用的通道数量
• 检查网络连接（MCP 服务器连接在启动时建立）

CPU 占用过高

可能原因：

• WASM 沙箱执行（受燃料限制，应能自行终止）
• 多个 Agent 同时运行
• 通道适配器重连（指数退避）

常见问题解答

如何切换默认 LLM 提供商？

编辑 ~/.librefang/config.toml：

[default_model]
provider = "groq"
model = "llama-3.3-70b-versatile"
api_key_env = "GROQ_API_KEY"

可以同时使用多个提供商吗？

可以。每个 Agent 可以通过其清单文件的 [model] 部分使用不同的提供商。内核会为每个唯一的提供商配置创建专用的驱动实例。

如何添加新通道？

1. 在 ~/.librefang/config.toml 的 [channels] 下添加通道配置
2. 设置所需的环境变量（令牌、密钥等）
3. 重启守护进程

如何更新 LibreFang？

# From source
cd librefang && git pull && cargo install --path crates/librefang-cli

# Docker
docker pull ghcr.io/librefang/librefang:latest

Agent 之间可以互相通信吗？

可以。Agent 可以使用 agent_send、agent_spawn、agent_find 和 agent_list 工具进行通信。编排器（orchestrator）模板专为多 Agent 协作场景设计。

我的数据会发送到云端吗？

只有 LLM API 调用会发送到提供商的服务器。所有 Agent 数据、记忆、会话和配置均存储在本地 SQLite 数据库中（~/.librefang/data/librefang.db）。OFP 传输协议使用 HMAC-SHA256 双向认证进行 P2P 通信。

如何备份数据？

备份以下文件：

• ~/.librefang/config.toml（配置文件）
• ~/.librefang/data/librefang.db（所有 Agent 数据、记忆、会话）
• ~/.librefang/skills/（已安装的技能）

如何重置所有内容？

rm -rf ~/.librefang
librefang init  # Start fresh

可以在没有网络连接的情况下运行 LibreFang 吗？

可以，前提是使用本地 LLM 提供商：

• Ollama：ollama serve + ollama pull llama3.2
• vLLM：自托管模型服务器
• LM Studio：基于 GUI 的本地模型运行器

在配置中设置提供商：

[default_model]
provider = "ollama"
model = "llama3.2"

LibreFang 和 OpenClaw 有什么区别？

LibreFang 可以导入 OpenFang 配置：librefang migrate --from openfang

LibreFang 也可以导入 OpenClaw 配置：librefang migrate --from openclaw

如何报告 Bug 或提交功能请求？

• Bug：在 GitHub 上提交 issue
• 安全问题：参见 SECURITY.md 了解负责任的漏洞披露流程
• 功能请求：在 GitHub 上发起讨论或提交 PR

系统要求是什么？

如何为特定 crate 启用调试日志？

RUST_LOG=librefang_runtime=debug,librefang_channels=info librefang start

可以将 LibreFang 作为库使用吗？

可以。每个 crate 都可以独立使用：

[dependencies]
librefang-runtime = { path = "crates/librefang-runtime" }
librefang-memory = { path = "crates/librefang-memory" }

librefang-kernel crate 负责组装所有组件，但你也可以单独使用各个 crate 进行自定义集成。