功能配置

MCP 服务器、A2A 集成、备用提供商、用户管理、浏览器自动化、热重载、执行策略、审批流程、预算控制、思考模式、文本转语音、Docker 沙箱、画布、自动回复、广播、收件箱、绑定、配对、扩展、密钥库、Webhook 触发器、代理、会话管理和队列管理的配置。

[[mcp_servers]]

MCP（模型上下文协议）服务器连接提供外部工具集成。每个条目是 [[mcp_servers]] 数组中的一个独立元素。

[[mcp_servers]]
name = "filesystem"
timeout_secs = 30
env = []

[mcp_servers.transport]
type = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]

[[mcp_servers]]
name = "remote-api"
timeout_secs = 60
env = ["GITHUB_PERSONAL_ACCESS_TOKEN"]

[mcp_servers.transport]
type = "sse"
url = "https://mcp.example.com/sse"

[[mcp_servers]]
name = "my-http-backend"
timeout_secs = 30

[mcp_servers.transport]
type = "http_compat"
base_url = "https://tools.example.com"
headers = [{name = "Authorization", value_env = "MY_API_KEY"}]

[[mcp_servers.transport.tools]]
name = "search"
description = "Search documents"
path = "/search"
method = "post"

Streamable HTTP

[[mcp_servers]]
name = "remote-tools"

[mcp_servers.transport.Http]
url = "https://mcp.example.com/v1"

使用 Streamable HTTP 传输方式（MCP 规范 2025-03-26+）。与 SSE 不同，这是基于标准 HTTP POST 的更简单的请求/响应模式。

传输方式变体（基于 type 的标记联合体）：

http_compat header 配置：

http_compat 工具配置：

[a2a]

Agent 间协议（A2A）配置，实现跨 LibreFang 实例的 Agent 间通信。

[a2a]
enabled = true
name = "LibreFang Agent OS"
description = "My production agent OS"
listen_path = "/a2a"

[[a2a.external_agents]]
name = "research-agent"
url = "https://agent.example.com/.well-known/agent.json"

[[a2a.external_agents]]
name = "code-reviewer"
url = "https://reviewer.example.com/.well-known/agent.json"

external_agents 条目：

[[fallback_providers]]

后备提供商链。当主 LLM 提供商（[default_model]）失败时，按顺序尝试这些后备提供商。

[[fallback_providers]]
provider = "ollama"
model = "llama3.2:latest"
api_key_env = ""
# base_url = "http://localhost:11434"

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

[[users]]

RBAC 多用户配置。用户可以被分配角色，并绑定到各通道平台的身份标识。

[[users]]
name = "Alice"
role = "owner"
api_key_hash = "sha256_hash_of_api_key"

[users.channel_bindings]
telegram = "123456"
discord = "987654321"
slack = "U0ABCDEFG"

角色层级（从最高到最低权限）：

[browser]

配置 Agent 工具 browser_* 使用的无头浏览器自动化引擎。

[browser]
enabled = true
headless = true
viewport_width = 1280
viewport_height = 720
timeout_secs = 30
idle_timeout_secs = 300
max_sessions = 5
# chromium_path = "/usr/bin/chromium"

[reload]

控制配置文件的自动监控和热重载。

[reload]
mode = "hybrid"
debounce_ms = 500

mode 值说明：

可热重载的配置段（无需重启）：

以下配置段在 daemon 运行时修改 config.toml 后会自动生效（每 30 秒轮询检测）：

• [channels] — 添加、删除或重新配置渠道适配器
• [[skills]] — 技能注册表
• [proxy] — HTTP/HTTPS/SOCKS5 代理设置
• [browser] — 浏览器自动化设置
• [web] — 网页搜索/抓取配置
• [approval] — 审批策略
• [cron] — 定时任务设置
• [webhook_triggers] — Webhook 触发器
• [extensions] — 扩展配置
• [[mcp_servers]] — MCP 服务器连接
• [a2a] — Agent-to-Agent 协议配置
• [fallback_providers] — 备用提供商链
• provider_urls — 提供商 URL 覆盖
• default_model — 默认模型选择
• tool_policy — 工具过滤规则
• proactive_memory — 主动记忆阈值
• provider_api_keys — 提供商 API key（会刷新驱动缓存）
• usage_footer — 使用量页脚模式
• sanitize — 输入清理规则

需要重启的配置段： home_dir、data_dir、api_listen、tls、telemetry。这些字段的变更会记录警告日志，但只在重启后生效。

[exec_policy]

控制 Agent 通过 exec 和 shell 工具允许执行的 Shell 命令。

[exec_policy]
mode = "allowlist"
allowed_commands = ["git", "python3", "node"]
timeout_secs = 30
max_output_bytes = 102400
no_output_timeout_secs = 30

mode 值说明：

[approval]

配置哪些工具在执行前需要明确的人工批准。引用 ApprovalPolicy 类型。

[approval]
require_approval = ["shell_exec"]
timeout_secs = 60
auto_approve_autonomous = false
auto_approve = false
second_factor = "none"
totp_issuer = "LibreFang"
totp_grace_period_secs = 300

TOTP 设置

当 second_factor = "totp" 时，需要先注册验证器应用：

1. 生成密钥： POST /api/approvals/totp/setup — 返回 base32 密钥、otpauth:// URI、二维码（base64 PNG）和 8 个恢复码。
2. 添加到验证器： 扫描二维码或在 Google Authenticator、1Password、Authy 等应用中手动输入密钥。
3. 保存恢复码： 妥善保存 8 个恢复码——丢失验证器设备时可用恢复码代替 TOTP 码，每个恢复码只能使用一次。
4. 确认注册： POST /api/approvals/totp/confirm，body 为 {"code": "123456"} — 验证应用生成的一次性密码。
5. 启用强制验证： 在配置中设置 second_factor = "totp"（支持热重载）。

也可以在 Dashboard 的 设置 > 安全 中完成 TOTP 设置。

启用后，审批流程变更：

• Dashboard： 点击"批准"时会弹出 6 位验证码输入框。
• 频道（Telegram/Slack）： 使用 /approve <id> <6位验证码> 代替 /approve <id>。
• API： 在 POST /api/approvals/{id}/approve 的 body 中发送 {"totp_code": "123456"}。
• 恢复码： 可用恢复码（格式：xxxx-xxxx）代替 TOTP 码。每个恢复码使用后即失效。

撤销 TOTP：使用 DELETE /api/approvals/totp（body: {"code": "..."}）或在 Dashboard 中操作。重置需要验证当前 TOTP 或恢复码。

频率限制： 连续 5 次 TOTP 验证失败后锁定 5 分钟。

TOTP 密钥存储在加密保管库（~/.librefang/vault.enc）中，使用 AES-256-GCM 加密。

[budget]

设置 LLM API 费用的全局支出限制。所有限制默认为 0.0（无限制）。

[budget]
max_hourly_usd = 1.00
max_daily_usd = 10.00
max_monthly_usd = 50.00
alert_threshold = 0.8
default_max_llm_tokens_per_hour = 0

按提供商限额 ([budget.providers.<id>])

当你同时使用免费的本地提供商（如 litellm、ollama）与付费提供商（如 moonshot、openai）时，可以只给付费方设置花销上限，而不影响免费方。提供商 ID 必须与 Agent [model] 中的 provider 字段一致。字段缺省或为 0 表示无限制。

[budget.providers.moonshot]
max_cost_per_day_usd = 2.0
max_tokens_per_hour = 500000

[budget.providers.openai]
max_cost_per_hour_usd = 1.0
max_cost_per_month_usd = 50.0

[budget.providers.litellm]
# 省略或全部为 0 = 无限制

命中按提供商的上限时，调用将以 QuotaExceeded 错误返回，错误信息中包含提供商名；其他提供商的用量不受影响。

[thinking]

配置支持扩展思维（思维链推理）的模型（例如启用了 thinking 模式的 Claude 3.7 Sonnet）。

[thinking]
budget_tokens = 10000
stream_thinking = false

[tts]

配置语音合成（Text-to-Speech）功能。

[tts]
enabled = false
provider = "openai"          # openai | elevenlabs | google_tts
max_text_length = 4096
timeout_secs = 30

[tts.openai]
voice = "alloy"
model = "tts-1"
format = "mp3"
speed = 1.0

[tts.elevenlabs]
voice_id = "21m00Tcm4TlvDq8ikWAM"
model_id = "eleven_monolingual_v1"
stability = 0.5
similarity_boost = 0.75

[tts.google]
voice = "en-US-Standard-F"
language_code = "en-US"
speaking_rate = 1.0
pitch = 0.0
format = "mp3"

[tts] 字段：

[tts.openai] 字段：

[tts.elevenlabs] 字段：

[tts.google] 字段：

需要设置 GOOGLE_API_KEY 或 GOOGLE_CLOUD_API_KEY 环境变量。

[docker]

配置用于隔离代码执行的 Docker 容器沙箱。

[docker]
enabled = false
image = "python:3.12-slim"
container_prefix = "librefang-sandbox"
workdir = "/workspace"
network = "none"
memory_limit = "512m"
cpu_limit = 1.0
timeout_secs = 60
read_only_root = true
mode = "off"
scope = "session"
reuse_cool_secs = 300
idle_timeout_secs = 86400
max_age_secs = 604800
blocked_mounts = []

mode 值说明：

scope 值说明：

[canvas]

配置 Canvas（Agent 到 UI）工具，允许 Agent 在仪表盘中渲染 HTML。

[canvas]
enabled = false
max_html_bytes = 524288
allowed_tags = []

[auto_reply]

配置后台自动回复引擎，可以在无需人工交互的情况下自动回复传入消息。

[auto_reply]
enabled = false
max_concurrent = 3
timeout_secs = 120
suppress_patterns = ["/stop", "/pause"]

[broadcast]

配置消息广播，将单条传入消息同时路由到多个 Agent。

[broadcast]
strategy = "parallel"
routes = { "announcement-channel" = ["agent-a", "agent-b", "agent-c"] }

[inbox]

基于文件的异步外部命令输入收件箱。将文本文件放入监控目录后，文件内容会作为消息分发给 Agent。已处理的文件会被移动到 processed/ 子目录以避免重复投递。

[inbox]
enabled = true
directory = "~/.librefang/inbox/"
poll_interval_secs = 5
default_agent = "assistant"

文件格式： 纯文本文件（.txt、.md、.json、.py 等）。第一行可以包含 agent:<name> 指令以指定目标 Agent；其余部分作为消息正文发送。没有指令的文件使用 default_agent。

安全限制： 大于 1 MB 的文件会被跳过。二进制文件（非文本扩展名）会被跳过。空文件会被移动到 processed/ 但不发送。

使用示例：

指定目标 Agent：

cat > ~/.librefang/inbox/task.txt << 'EOF'
agent:code-reviewer
Please review this code for security issues:

def login(user, password):
    query = f"SELECT * FROM users WHERE name='{user}' AND pass='{password}'"
    return db.execute(query)
EOF

发送到默认 Agent：

echo "Summarize today's system logs" > ~/.librefang/inbox/summarize.txt

定时任务：

# crontab -e
0 9 * * * grep ERROR /var/log/app.log > ~/.librefang/inbox/daily_errors.txt

CI/CD 构建后处理：

echo "agent:devops
Build failed, please analyze:
$(tail -100 build.log)" > ~/.librefang/inbox/build_$(date +%s).txt

批量处理：

for doc in ~/reports/*.md; do
  cp "$doc" ~/.librefang/inbox/
done

检查收件箱状态：

curl -s http://127.0.0.1:4545/api/inbox/status
# {"enabled":true,"pending_count":3,"processed_count":12,...}

[[bindings]]

Agent 绑定将特定的通道/账号/对等方组合路由到特定的 Agent。更具体的绑定（非空字段越多）优先级越高。

[[bindings]]
agent = "support-agent"
[bindings.match_rule]
channel = "telegram"
guild_id = "123456"

[[bindings]]
agent = "vip-agent"
[bindings.match_rule]
channel = "discord"
peer_id = "987654321"
roles = ["premium"]

顶层字段：

match_rule 字段：

具体度评分（分值越高越先匹配）：peer_id（+8）> guild_id（+4）> roles（+2）= account_id（+2）> channel（+1）。

[pairing]

配置 LibreFang 移动端伴侣应用的设备配对和推送通知。

[pairing]
enabled = false
max_devices = 10
token_expiry_secs = 300
push_provider = "ntfy"
ntfy_url = "https://ntfy.sh"
ntfy_topic = "my-librefang-notifications"

[extensions]

配置 MCP 服务器的重连行为和健康监控。

[extensions]
auto_reconnect = true
reconnect_max_attempts = 10
reconnect_max_backoff_secs = 300
health_check_interval_secs = 60

[vault]

配置用于存储敏感密钥的加密凭据库。

[vault]
enabled = true
# path = "~/.librefang/vault.enc"

[webhook_triggers]

允许外部系统通过经过认证的 HTTP Webhook 在 /hooks/wake 和 /hooks/agent 端点触发 Agent 操作。

[webhook_triggers]
enabled = true
token_env = "LIBREFANG_WEBHOOK_TOKEN"
max_payload_bytes = 65536
rate_limit_per_minute = 30

[proxy]

配置所有出站连接（LLM API、网页搜索、MCP 服务器等）使用的 HTTP 代理。环境变量 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 也作为后备选项被识别。

[proxy]
http_proxy = "http://proxy.corp.example:8080"
https_proxy = "http://proxy.corp.example:8080"
no_proxy = "localhost,127.0.0.1,.internal.corp"

[session]

配置空闲或多余会话的自动清理。

[session]
retention_days = 30
max_sessions_per_agent = 100
cleanup_interval_hours = 24

[queue]

配置 Agent 命令队列，包括深度限制、TTL 和分通道并发度。

[queue]
max_depth_per_agent = 100
max_depth_global = 1000
task_ttl_secs = 3600

[queue.concurrency]
main_lane = 3
cron_lane = 2
subagent_lane = 3

[queue] 字段：

[queue.concurrency] 字段：

[tool_budget]

源码： librefang-runtime/src/tool_budget.rs

工具预算执行器限制单次 agent 轮次中工具调用返回的数据大小，防止意外的大体积工具输出填满上下文窗口并推高 token 成本。

工作原理

每个工具结果在放入上下文之前都要经过三层大小检查：

溢出文件命名

溢出文件命名为 <agent_id>_<tool_call_id>_<timestamp>.txt，写入 /tmp/librefang-results/。轮次之间不自动清理；守护进程重启时清除该目录。

Agent 可在后续轮次中读取溢出文件——注入上下文的摘要中包含完整路径。

配置

当前版本不支持按 agent 配置工具预算。50 KB 和 200 KB 阈值在编译时固定。

为什么是这两个限制？

50 KB 内联文本约合 12 500 个 token——已是大多数模型上下文窗口的相当大一部分。超过此限制后，结果对 agent 的边际价值递减，而提示词成本线性增加。200 KB 硬上限防止单次失控工具调用耗尽整个上下文窗口。

[context_compression]

上下文压缩可在 Agent 上下文窗口的 token 用量增长过大时自动缩减，防止达到硬性上下文限制而出错，无需手动管理会话。

工作原理

在即将发送 LLM 调用时，ContextEngine 会估算已组装上下文（系统提示 + 会话历史 + 工具 schema）的 token 数。若用量超过模型上下文窗口的 80%，引擎会在发送请求前触发一次压缩。

压缩自动发生——无需任何配置即可启用。[context_compression] 章节为未来可调参数预留；当前所有阈值均在内部固定。

三层保护

摘要保留与迭代精炼

摘要消息以带有内部特殊标签的普通 assistant 轮次存入会话历史。后续压缩时，现有摘要会被纳入待重新摘要的内容，而非原样保留。这意味着长时间运行的会话会经历迭代精炼——较旧的摘要会被折叠进更新、更紧凑的摘要中。

压缩器 system prompt 现在指示 LLM 用对话中用户在用的语言写摘要。中文对话产出中文摘要；阿拉伯语对话产出阿语摘要。这条指令同时作用于单次的 summarize_messages 路径和 summarize_in_chunks 的合并步骤，分块压缩也覆盖到 — 长的非英文 session 不再夹带意外的英文摘要。

可插拔 ContextEngine

压缩算法实现于 ContextEngine trait 之后。当前实现使用基于 LLM 的摘要器。LibreFang 未来版本将支持配置替代压缩算法——包括基于 DAG 的压缩和 LCM（Latent Context Modeling）——等实现稳定后开放配置。

无需配置

上下文压缩对所有 Agent 始终启用，当前在 config.toml 中没有任何开关或可调参数。80% 阈值、强制截断回退和上下文守护上限均由运行时自动执行。

Cron 调度器

按 agent 的定时任务（interval、一次性、或 5 字段 cron 表达式）触发 agent 回合、system event 或 workflow 运行。调度器支持多目标分发带失败隔离、pre-script 把数据注入 LLM prompt，以及 silent marker 在运行时抑制分发。

完整 schema、扇出目标变体（channel / webhook / local file / email）、Webhook URL 的 SSRF 防护、pre-script 的 <home_dir>/scripts/ 路径白名单、以及 wake-gate vs pre-script 的取舍，见 Cron 调度器。

可观测性 — Tempo + 业务 span

LibreFang 自带可选的可观测性栈，一条 docker compose 起栈。捕获 HTTP 请求和 LibreFang 自己的工作 — agent 回合、tool 调用、channel 发送、cron 触发 — 作为可搜索的 Tempo trace。

栈组件（全部捆绑进二进制，不需要外部下载）：

• librefang-otel-collector — :4317 上的 OTLP/gRPC 收集器。daemon 把 span 导出到这。
• librefang-tempo — 单二进制 Grafana Tempo，本地文件系统存储，24 小时保留。内部 :4317 接收，查询 API 在 :3200。
• librefang-grafana — 预配置的 Grafana，Tempo 数据源已接好。

自动启动是 opt-in 的。 可观测性栈不会跟着 librefang start 自动起 —— 想让 daemon 帮你管理生命周期就在 config.toml 设 [telemetry] auto_start = true。否则用 librefang observability up / down 显式管理。捆绑的容器按 home_dir 加 Docker label，同一台机器上多个 LibreFang 安装不会抢同名容器；拆栈用 RAII 风格清理，daemon 异常退出时也能回收。

起栈：

librefang observability up      # 起捆绑的 compose 栈
librefang observability status  # 各容器健康检查
librefang observability down    # 拆栈

配置 daemon 导出到那里：

[telemetry]
otlp_endpoint = "http://localhost:4317"
service_name = "librefang"
sample_rate = 1.0           # 0.0–1.0；高量生产环境降低
prometheus_enabled = true   # 同时暴露 /api/metrics

Trace 搜索： 在 http://localhost:3000 打开 Grafana，把 Explore tab 切到 Tempo 数据源，按 trace ID、span 名、或属性搜。业务级 span 包括 agent.turn、tool.call、channel.send、cron.fire、provider.request，每个带 agent id、channel 名、model、结果作为可搜索属性。

cache_hit_ratio 指标： runtime 给每个 agent.turn span 计算

cache_hit_ratio = cache_read / (cache_read + cache_creation)   # 取值 [0.0, 1.0]

Some(1.0) 是完美前缀缓存命中；Some(0.0) 是 cold start，缓存激活但没命中；None 是 run 完全没启用缓存。出现在 trajectory 导出（metadata.cache_hit_ratio）和 Grafana per-agent 面板。