功能配置

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]
type = "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 值说明：

mode 与审批是两个独立的决定。 历史上 full 同时意味着"跳过白名单校验"和"跳过审批提示"；full_mode_skips_approval = false 将两者解耦，使 require_approval 在 full 下与在 allowlist 下被同样对待。 默认值保持 true，因为 approval.require_approval 默认就包含 shell_exec，而声明了 shell_exec 的独立 Agent 在 spawn 时会被提升为 full，翻转默认值会让标准安装在每条命令上都弹出审批。

与 exec_policy 的其他字段一样，该字段在 Agent spawn 或恢复时被复制进该 Agent 的 manifest，因此 POST /api/config/reload 不会把它追加到已经在运行的 Agent 上——需要杀掉该 Agent 让其重新 spawn，或者重启守护进程。 少了这一步，把它设为 false 看起来就像静默失效：没有任何新的审批提示出现，而最自然的解读会是"没有命令需要审批"。

危险命令黑名单与 mode 无关，在 deny、allowlist、full 下都会扫描每条命令——full 关闭的是白名单校验，而不是这份黑名单。 其覆盖范围包括 LibreFang 守护进程生命周期命令（librefang stop / start / restart，含 gateway 别名与带路径的调用形式），它们会连带重启同一守护进程上的所有 Agent 与频道适配器；以及针对守护进程自身 librefang.db 的写入型 SQL 与输出重定向。 对该数据库的只读检查（select、.schema、.dump）以及 librefang status 被有意排除在外。

[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
reasoning_mode = "high"        # 可选：none | low | high | max

reasoning_mode（#7946）

budget_tokens 无法表达"完全不推理"——低于 1024 只是省略推理开关，而默认开启推理的模型（所有 DeepSeek V4 型号）依然会推理。 它也无法达到某些提供商的最高档，因为推导出的档位最高只到 high。 reasoning_mode 是直接的开关，各驱动会把它翻译成自己线路上真正接受的形式。

可在三处设置，解析顺序为按调用 > 按 Agent > 全局 > 编译默认值：

• 按调用——POST /api/agents/{id}/message（以及 /message/stream）请求体中的 reasoning_mode。同时传入旧的布尔 thinking 字段时，以 reasoning_mode 为准。
• 按 Agent——该 Agent 的 agent.toml 中的 [thinking] reasoning_mode。按 Agent 的设置在 config.toml 中无效。
• 全局——此处的 [thinking] reasoning_mode。

各提供商的线路映射：

请求体永远不会同时携带 reasoning_effort 和 reasoning.effort——OpenRouter 会对这种组合返回 HTTP 400。 Kimi/Moonshot 模型始终发送 thinking: disabled（这是多轮工具调用的正确性要求，而非偏好设置），DeepSeek R1 没有线路开关。 Ollama 驱动在分级档位上仍读取 budget_tokens——它的线路开关本就是 token 预算而非强度枚举——但它会遵循 none：该模式必须依附于一份实例化的 thinking 配置传递，若把这份配置当作纯预算读取，就会在明确要求不推理的回合上反而开启推理。 Anthropic 驱动按模型分流：Haiku 4.5 及更早的 Claude 模型与上述一致；而 Opus 4.6 及以后的模型已经没有 token 预算可发，模式是它们唯一的档位来源——low / high / max 直接映射到 output_config.effort；未设置模式时则省略该字段，交由 API 自身的默认值决定，而不从一个运维可能从未选择过的预算里推导档位。 Gemini 完全不读取 thinking 配置。 完整细节（包括为何 medium 不是可设置的模式）见 docs/architecture/reasoning-mode-resolution.md。

[tts]

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

[tts]
enabled = false
provider = "openai"          # openai | elevenlabs | google_tts
output_format = "mp3"        # mp3 | ogg_opus
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] 字段：

当合成的音频要发送到消息平台时，请设置 output_format = "ogg_opus"。语音消息必须是 Ogg/Opus 格式，而多数提供商返回 MP3，平台会拒收——但 text_to_speech 本身仍报告成功，因为文件确实写入了。转换通过 ffmpeg 完成；若未安装 ffmpeg，则回退为提供商自身的格式。

这与下面的 [tts.elevenlabs] output_format 不同：后者是发给 ElevenLabs 的查询参数，有自己的取值集合，且已经直接请求 Opus，因此无需转换。

[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 值说明：

只有整个键完全匹配时容器才会被重用：上表的作用域归属、决定容器形态的 [docker] 字段（image、network、memory_limit、cpu_limit、workdir、read_only_root、cap_add、tmpfs、pids_limit、blocked_mounts），以及挂载进容器的宿主机工作区路径。工作区对所有作用域（包括 shared）都是键的一部分：容器带着创建时挂载的工作区，把它交给挂载了其他路径的调用方就等于把一个 Agent 的工作区暴露给另一个 Agent。

容器由两条路径销毁：enabled = true 时每 60 秒运行一次、按 idle_timeout_secs 与 max_age_secs 回收的清理循环，以及销毁全部池中容器的守护进程关闭流程。LibreFang 没有单独的“会话结束”信号，因此 session 作用域的容器会在最后一次工具调用之后继续存在，直到上述两者之一将其回收——把 idle_timeout_secs 设成你希望的存活窗口。

没有 LibreFang 会话的调用方（POST /api/tools/{name} 桥接以及其他带外调用）无法遵循 scope = "session"，因此它会为该次调用创建容器并在调用后销毁，而不是把容器放宽到整个 Agent。

shared 不只是一种池化策略，更是一条信任边界。容器是整体交接的：上一次调用往可写路径和 /tmp tmpfs 里写下的一切都还在，它遗留的进程也还在跑。reuse_cool_secs 只是推迟两个 Agent 之间的交接，它不做任何清理，其他机制也不做。只有当挂载该工作区的所有 Agent 之间本来就彼此信任时才用 shared，否则请用 agent 或 session。

reuse_cool_secs 推迟交接，而不是把调用排队。如果一次调用只找到仍在静置的容器，它会再创建一个容器而不是等待，这个容器释放后同样进入池中。因此在 shared 下被多个 Agent 并发使用的工作区，以及任何作用域下被并发调用命中的键，都会持有不止一个容器。

除了回收循环之外没有任何东西会把容器还给宿主机，所以一个键持有的闲置容器数量会稳定在该键的并发峰值，并保持 idle_timeout_secs（默认 24 小时）那么久。启用沙箱时要按这个数量来规划容量：把 idle_timeout_secs 调小，而不是指望负载回落时容器会自己消失。

[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

何时触发重连。 有两类失败会把服务器标记为错误状态并交给健康检查循环处理。 连接或重连握手失败时会在第一次失败就立即触发——此时并不存在需要保留的活动连接。 握手成功、之后才在传输层出问题的服务器（工具调用超时、传输通道关闭、与子进程之间的 stdio 管道断开），在观察到第一次这类失败时就会被标记为错误状态，但只有在连续 三次 传输层失败且期间没有任何一次调用成功之后，才会真正被拆除并重建。 单次超时与一个确实很慢的工具无法区分，而重连会连带丢弃服务器进程及其持有的状态，因此这里有意不让单次失败触发重连。 真正卡死的服务器会让每一次调用都失败，所以这三次会随着 agent 的重试很快累积。

工具返回的普通错误——参数不正确、文件不存在，以及任何由服务器以格式正确的 JSON-RPC 错误答复的情况——都不计入其中。 这类答复是由传输通道正常送达的，因此重连只会丢弃一个健康的服务器。

两类失败都会体现在 GET /api/mcp/health 中（status、last_error、consecutive_failures），而一次成功的工具调用会重置计数并刷新 last_ok。

[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 面板。