# 故障排除与常见问题

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

## 目录

- [快速诊断](#快速诊断)
- [安装问题](#安装问题)
- [配置问题](#配置问题)
- [LLM 提供商问题](#llm-提供商问题)
- [通道问题](#通道问题)
- [Agent 问题](#agent-问题)
- [插件问题](#插件问题)
- [API 问题](#api-问题)
- [桌面应用问题](#桌面应用问题)
- [性能](#性能)
- [常见问题解答](#常见问题解答)

---

## 快速诊断

运行内置诊断工具：

```bash
librefang doctor
```

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

#### 审计检查（Audit checks）

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

| 检查 | 断言什么 |
|---|---|
| `VaultKeyCheck` | 设了 `LIBREFANG_VAULT_KEY` 时，base64 解码后**正好 32 字节**。经典的 32 个 ASCII 字符的错误产生的是 32 字符串而不解码成 32 字节 key。 |
| `ApiListenAddrCheck` | `api_listen` 从配置的 `LIBREFANG_PORT` 可达，且非 loopback 绑定时 `api_key` 已设，避免 daemon 意外暴露给无认证访问。 |
| `ConfigTomlSchemaCheck` | `config.toml` 能干净地按当前 `KernelConfig` schema 解析；未知 key、类型不符、范围越界都在 daemon 启动前被标出来。 |

新增检查：在 `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 把日志滚出去就丢了。

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

### 检查守护进程状态

```bash
librefang status
```

### 通过 API 检查健康状态

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

### 查看日志

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

```bash
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 工具链版本过旧或缺少系统依赖。

**解决方案**：
```bash
rustup update stable
rustup default stable
rustc --version  # Need 1.75+
```

在 Linux 上，可能还需要安装以下依赖：
```bash
# Debian/Ubuntu
sudo apt install pkg-config libssl-dev libsqlite3-dev

# Fedora
sudo dnf install openssl-devel sqlite-devel
```

### 安装后找不到 `librefang` 命令

**解决方案**：确保 `~/.cargo/bin` 在 PATH 中：
```bash
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` 创建默认配置：
```bash
librefang init
```

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

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

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

**解决方案**：至少设置一个提供商密钥：
```bash
export GROQ_API_KEY="gsk_..."     # Groq (free tier available)
# OR
export ANTHROPIC_API_KEY="sk-ant-..."
# OR
export OPENAI_API_KEY="sk-..."
```

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

### 配置验证错误

手动运行验证：
```bash
librefang config show
```

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

### "Port already in use"

**解决方案**：在配置中更改端口或终止占用端口的进程：
```bash
# 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 密钥已过期或被撤销
- 环境变量名称错误

**解决方案**：验证密钥是否正确：
```bash
# 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 分配更快的模型：
```toml
[model]
provider = "groq"
model = "llama-3.1-8b-instant"  # Fast, small model
```

### "Model not found"

**解决方案**：检查可用模型列表：
```bash
curl http://127.0.0.1:4545/api/models
```

或使用别名：
```toml
[model]
model = "llama"  # Alias for llama-3.3-70b-versatile
```

查看完整的别名列表：
```bash
curl http://127.0.0.1:4545/api/models/aliases
```

### Ollama / 本地模型无法连接

**解决方案**：确保本地服务器正在运行：
```bash
# 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 等）

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

### "Channel adapter failed to start"

**常见原因**：
- 令牌缺失或无效
- 端口已被占用（针对基于 Webhook 的通道）
- 网络连接问题

检查日志获取具体错误信息：
```bash
RUST_LOG=librefang_channels=debug librefang start
```

---

## Agent 问题

### Agent 陷入循环

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

**自动保护机制**：LibreFang 内置了循环守卫：
- 相同工具调用达 3 次时**警告**
- 相同工具调用达 5 次时**阻止**
- 总阻止次数达 30 次时触发**熔断器**（停止 Agent）

**手动修复**：取消 Agent 的当前运行：
```bash
curl -X POST http://127.0.0.1:4545/api/agents/{id}/stop
```

或通过聊天命令：`/stop`

### Agent 上下文耗尽

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

**解决方案**：压缩会话：
```bash
curl -X POST http://127.0.0.1:4545/api/agents/{id}/session/compact
```

或通过聊天命令：`/compact`

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

### Agent 不使用工具

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

**解决方案**：检查 Agent 的清单文件：
```toml
[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 端点。

```bash
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](./configuration#context_engine) 里的 `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` 字段。

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

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

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

改完配置重启 LibreFang。

---

## API 问题

### 401 Unauthorized

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

**解决方案**：在请求中包含 Bearer 令牌：
```bash
curl -H "Authorization: Bearer your-api-key" http://127.0.0.1:4545/api/agents
```

### 429 Too Many Requests

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

**解决方案**：等待 `Retry-After` 指定的时间，或在配置中提高速率限制：
```toml
[api]
rate_limit_per_second = 20  # Increase if needed
```

### 浏览器中出现 CORS 错误

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

**解决方案**：在 CORS 配置中添加你的源：
```toml
[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`：
```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？

```bash
# 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/`（已安装的技能）

### 如何重置所有内容？

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

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

可以，前提是使用本地 LLM 提供商：
- **Ollama**：`ollama serve` + `ollama pull llama3.2`
- **vLLM**：自托管模型服务器
- **LM Studio**：基于 GUI 的本地模型运行器

在配置中设置提供商：
```toml
[default_model]
provider = "ollama"
model = "llama3.2"
```

### LibreFang 和 OpenClaw 有什么区别？

| 维度 | LibreFang | OpenClaw |
|--------|----------|----------|
| 编程语言 | Rust | Python |
| 通道数 | 40 | 38 |
| 技能数 | 60 | 57 |
| 提供商数 | 20 | 3 |
| 安全体系 | 16 套系统 | 基于配置 |
| 二进制大小 | ~30 MB | ~200 MB |
| 启动时间 | `<200 ms` | `~3 s` |

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

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

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

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

### 系统要求是什么？

| 资源 | 最低要求 | 推荐配置 |
|----------|---------|-------------|
| 内存 | 128 MB | 512 MB |
| 磁盘 | 50 MB（二进制文件） | 500 MB（含数据） |
| CPU | 任意 x86_64/ARM64 | 2 核以上 |
| 操作系统 | Linux、macOS、Windows | 均可 |
| Rust | 1.75+（仅编译时需要） | 最新稳定版 |

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

```bash
RUST_LOG=librefang_runtime=debug,librefang_channels=info librefang start
```

### 可以将 LibreFang 作为库使用吗？

可以。每个 crate 都可以独立使用：
```toml
[dependencies]
librefang-runtime = { path = "crates/librefang-runtime" }
librefang-memory = { path = "crates/librefang-memory" }
```

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