核心配置参考

LibreFang 核心配置节：顶层字段、默认模型、内存、网络、网页搜索、媒体处理和链接理解。

顶层字段

以下字段位于 config.toml 的根层级（不在任何 [section] 内部）。

mode 值说明：

usage_footer 值说明：

[default_model]

配置 Agent 未指定自有模型时使用的主 LLM 提供商。

[default_model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
api_key_env = "ANTHROPIC_API_KEY"
# base_url = "https://api.anthropic.com"

[memory]

配置基于 SQLite 的记忆基础设施，包括向量嵌入和记忆衰减。

[memory]
# sqlite_path = "/custom/path/librefang.db"
embedding_model = "all-MiniLM-L6-v2"
consolidation_threshold = 10000
decay_rate = 0.1

[auto_dream]

后台记忆整固（"梦境"）—— 让选择开启的 agent 通过 4 阶段提示词（定位 / 收集 / 整固 / 修剪）反思并整理自己的记忆。梦境触发是 事件驱动 的：agent 每完成一次 turn，kernel 立刻检查闸门是否放行；同时保留一个稀疏的兜底调度器（默认每天一次），用于那些开启了 auto-dream 却长期不活动的 agent。默认关闭；每个 agent 还需在 manifest 中通过 auto_dream_enabled = true 单独开启。

[auto_dream]
enabled = false
min_hours = 24
min_sessions = 5
check_interval_secs = 86400
timeout_secs = 600
# lock_dir = ""   # 默认为 <data_dir>/auto_dream/

当所有闸门同时满足时才会触发：enabled = true、agent manifest 中 auto_dream_enabled = true、距离上次梦境至少 min_hours 小时、至少触及 min_sessions 个会话、以及能获取到该 agent 的文件锁。

每个 Agent 的加入状态 可以无需重启在运行时切换：

• Web Dashboard：设置页 → 梦境模式卡片 → 每个 agent 旁的勾选框。
• API：PUT /api/auto-dream/agents/{id}/enabled，请求体 {"enabled": true | false}。新状态在下一次 turn 结束（事件驱动）或下一次兜底 tick 时生效，以先到者为准。
• Manifest：在 agent 的 .toml 里设置 auto_dream_enabled = true，获得重启后仍生效的持久加入状态。

每个 Agent 的阈值覆盖（可选）允许异构调度。在 agent manifest 里任一字段不填（None）就继承全局默认：

auto_dream_enabled = true
auto_dream_min_hours = 168    # 每周一次，适合不活跃的 agent
auto_dream_min_sessions = 1   # 每次会话后触发，适合高频 agent

status 接口会返回每个 agent 的 effective_min_hours / effective_min_sessions，Dashboard 可以据此展示实际生效值。

运行时工具限制：dream 运行时，无论 agent manifest 原本允许什么，kernel 会把可调用工具列表收窄到仅 memory_store / memory_recall / memory_list。这是针对 prompt 注入攻击的纵深防御层（即便模型被诱骗，shell 和网络类工具也不在其 schema 里）。

手动控制：POST /api/auto-dream/agents/{id}/trigger 绕过时间和会话闸门，但仍须获取锁并尊重 opt-in 开关。POST /api/auto-dream/agents/{id}/abort 取消手动触发的进行中梦境，回滚锁 mtime 使时间门重新打开。GET /api/auto-dream/status 返回实时进度，完成后的梦境会包含 token 用量和成本字段。

审计记录：每次梦境生命周期转换（start / complete / fail / abort）都以 DreamConsolidation 审计事件记录。completion 条目附带 input/output/cache token 数和 cost_usd，便于从 /api/audit 回答"这周 auto-dream 花了多少钱"。

[network]

配置 OFP（LibreFang 协议）点对点网络层，使用 HMAC-SHA256 双向认证。

[network]
listen_addresses = ["/ip4/0.0.0.0/tcp/0"]
bootstrap_peers = []
mdns_enabled = true
max_peers = 50
shared_secret = "my-cluster-secret"

[web]

配置 Agent 工具使用的网页搜索和网页抓取能力。

[web]
search_provider = "auto"
cache_ttl_minutes = 15
timeout_secs = 15

search_provider 值说明：

[web.brave]

[web.brave]
api_key_env = "BRAVE_API_KEY"
max_results = 5
country = ""
search_lang = ""
freshness = ""

[web.tavily]

[web.tavily]
api_key_env = "TAVILY_API_KEY"
search_depth = "basic"
max_results = 5
include_answer = true

[web.jina]

[web.jina]
api_key_env = "JINA_API_KEY"
max_results = 5

[web.perplexity]

[web.perplexity]
api_key_env = "PERPLEXITY_API_KEY"
model = "sonar"

[web.searxng]

[web.searxng]
url = "https://searxng.example.com"

运行时行为：

• LibreFang 启动时拉取 /config 一次，缓存可用的 categories；查询时如果传了未知 category 会返回 400 而不是把无效请求发到上游。
• 分页是 1 起算的；pageno=0 在客户端被拒。
• 单次查询返回的结果按 [web].max_results 裁剪。客户端裁剪后会标注 truncation，agent 看到的就是这截短的列表。
• 输出过滤继承 [web] 的全局规则（content size cap、blocked domain 等）。

[web.fetch]

[web.fetch]
max_chars = 50000
max_response_bytes = 10485760
timeout_secs = 30
readability = true

[media]

配置媒体理解能力（图片描述、音频转录、视频描述），用于处理包含附件的消息。

[media]
image_description = true
audio_transcription = true
video_description = false
max_concurrency = 2
# image_provider = "openai"   # 省略则自动检测
# audio_provider = "openai"   # 省略则自动检测

[links]

配置自动链接理解功能——自动抓取并总结传入消息中的 URL。

[links]
enabled = false
max_links = 3
max_content_bytes = 102400
timeout_secs = 10

[parallel_tools]

控制 agent loop 的批量工具分派器：当一次 assistant 回合发出多个 tool call 时，分派器按 parallel-safety 分类，决定哪些可以并发哪些必须串行。

[parallel_tools]
enabled = false
max_concurrent = 4
mcp_default_safety = "write_shared"
mcp_readonly_allowlist = ["mcp__github__list_issues", "mcp__notion__query_database"]

ParallelSafety 类。 每个 tool call 被归到其中一类（来自内置启发式、tool 输入 schema 注解，或上面那两个 MCP 旋钮）：

Tool 作者可以钉死分类：在 tool 输入 schema 顶层加 "x-parallel-safety": "<snake_case>"，或者 "metadata": { "parallel_safety": "<snake_case>" }。无效值 fall through 到启发式，所以拼错字不会污染结果。

什么时候调哪个旋钮：

• 保持 enabled = false 如果想要跟历史顺序分派完全一致的行为——验证新 agent 队列时或调试 tool 顺序问题时有用。
• 降低 max_concurrent 如果你的环境对 rate limit 敏感（小型 MCP server、低 API 配额）。4 是均衡默认值；读多的工作负载对接快后端可以加大。
• 把 mcp_default_safety 提到 "read_only" 仅当你接的每个 MCP server 都确实是只读的或带正确注解。默认 "write_shared" 是安全选择——未标注却悄悄改状态的 MCP server 不会被并发触发。
• 用 mcp_readonly_allowlist 来 whitelist 某 server 中安全的特定 tool，而该 server 其他 tool 会修改状态。这是比翻 mcp_default_safety 更精准的手术刀做法。
• 关掉批量分派（enabled = false）如果你在某个自定义 MCP server 上看到 race condition 症状——错误的缓存命中、写冲突、读到部分状态。先发个补丁或把 offending tool 调到更严的分类，再重新打开。

max_history_messages

LibreFang 在每个回合都会修剪 agent 的历史消息，防止无限增长。这个上限控制每次修剪后保留多少条消息。机制只在安全的回合边界裁切（绝不会切在 tool_use/tool_result 配对中间），所以保留下来的切片对 Gemini 等严格 provider 也是良构的。

上限可以在两个层级配置——config.toml 顶层字段（运维级全局覆盖）+ agent.toml 顶层字段（按 agent 覆盖）。两者都是可选的。

解析顺序（先匹配先生效）：

1. per-agent 覆盖 — agent.toml 顶层的 max_history_messages（不在任何 section 里）。
2. 全局覆盖 — config.toml 顶层的 max_history_messages。
3. 编译时默认 — DEFAULT_MAX_HISTORY_MESSAGES = 40。

低于 MIN_HISTORY_MESSAGES = 4 的值会在运行时静默上调到 4，并打 warn! 日志带 agent / requested / applied 字段。理由：一次 tool-use round trip 是 4 条消息（user → assistant tool_use → tool_result → assistant text）；上限低于 4 会破坏安全裁切启发式。

全局覆盖 写在 ~/.librefang/config.toml：

# 给所有没自己覆盖的 agent 降低默认值。
max_history_messages = 20

per-agent 覆盖 写在任意 agent.toml（顶层字段——跟 name、module 等同级，不在 [model] 或 [autonomous] 里）：

name = "fast-loop"
module = "builtin:chat"
max_history_messages = 12

什么时候调：

• 降低上限（如 20 或 12）：cron ping 驱动或短消息 channel 的话痨 agent——每个回合带的历史更少，token 成本下降。
• 抬高上限（如 80 或 120）：跑长上下文模型的长视野自主 agent，更多历史能改善 grounding。
• 保持不设（null / 省略）：大多数 agent 用默认 40 即可，针对典型 chat 工作负载调过。

与 token 上限的相互作用。 这是消息数上限。还有一个独立的token 数上限（DEFAULT_CONTEXT_WINDOW = 200000）——哪个先触发哪个生效。短消息多 → 消息数上限先触发；长消息少（大 tool 输出）→ token 上限先触发。

更深入的细节（被裁切的具体内容、安全裁切算法、值如何在运行时流转），见架构笔记 docs/architecture/message-history-trimming.md。

[provider_request_timeout_secs]

按 provider 的 LLM driver HTTP 请求 timeout。没设条目就用 driver 内置默认（OpenAI 兼容驱动通常 60 秒，Ollama 更长）。

[provider_request_timeout_secs]
ollama = 300        # 本地模型加载 + 首 token 冷启动
anthropic = 120
openai = 90

按模型粒度的覆盖也可以在 agent 层 agent.toml: model.request_timeout_secs 实现，给慢的长上下文模型做精细调优。

[browser]

浏览器工具配置。LibreFang 默认按会话启动一个本地 Chromium 实例。设 cdp_endpoint 改为附加到已运行的浏览器（Browserless、带 --remote-debugging-port 的 headful Chrome 等）。

[browser]
# 默认：每个 session 启动本地无头 Chromium
# 设了 cdp_endpoint 改为 attach 到已存在 / 远程的浏览器
cdp_endpoint = "http://browser-host:9222"
cdp_auth_token_env = "LIBREFANG_CDP_TOKEN"   # 可选 bearer token 环境变量

attach 模式下，本地启动路径被完全绕过；Drop 不会终止外部浏览器。

Cron 会话大小上限

当 cron 任务共用持久 session 时（默认 session_mode = "persistent"），那个 session 的历史每次触发都增长。两个可选上限会在每次触发前从最早消息开始裁掉，避免膨胀。

[kernel]
cron_session_max_tokens = 50000
cron_session_max_messages = 100

session_mode = "new" 时跳过裁切——那种触发本身就拿全新 session，不会带旧状态。两个上限同时生效（哪个先触发哪个裁更多）。

[rate_limit]

API 与 WebSocket 限流配置。HTTP 路径用每 IP GCRA 令牌桶,WS 路径还加 idle 超时和按消息 debounce,避免流式 UI 把下游连接打爆。

[rate_limit]
api_requests_per_minute = 500
retry_after_secs = 60
max_ws_per_ip = 5
ws_messages_per_minute = 10
ws_terminal_messages_per_minute = 3600
ws_idle_timeout_secs = 1800
ws_debounce_ms = 100
ws_debounce_chars = 200

终端额度比 chat 高两个数量级是有原因的: 用 chat 的 ws_messages_per_minute = 10 时,在 vim 里敲 :wq 就把额度耗光了。除非你刻意要节流 PTY,否则别把 ws_terminal_messages_per_minute 调到 600 以下。

[sanitize]

入站消息清洗 / prompt-injection 检测。默认关。开启后,超长或匹配规则的入站文本在到达 LLM 前被阻断或告警。

[sanitize]
mode = "off"            # "off" | "warn" | "block"
max_message_length = 32768
custom_block_patterns = [
  "(?i)ignore previous instructions",
]

block 模式下,channel 适配器返回清洗器拒绝提示, 不消耗任何 LLM token。配合 [privacy] 做防御纵深。

[privacy]

LLM prompt 上的 PII 脱敏或假名化。默认关。脱敏器跑在每次出站 prompt 上,包括历史 replay。

[privacy]
mode = "off"            # "off" | "redact" | "pseudonymize"
redact_patterns = [
  "\\b[A-Z]{2}\\d{6,8}\\b",   # 在内置规则之上追加
]

pseudonymize 的替换映射只存在内存中 —— 重启 daemon 后映射表清零。

[telemetry]

OpenTelemetry tracing + Prometheus 指标。自带 Tempo/Grafana 栈从这里读;外部 collector 也行 —— 把 otlp_endpoint 指向它。

[telemetry]
enabled = true
otlp_endpoint = "http://localhost:4317"
service_name = "librefang"
sample_rate = 1.0
prometheus_enabled = true
auto_start_observability_stack = false

[heartbeat]

常驻(autonomous)agent 的心跳监测器。Agent 在 default_timeout_secs 内没心跳,监测器把它标记为无响应。

[heartbeat]
check_interval_secs = 30
default_timeout_secs = 60
keep_recent = 10

心跳路径还兼任崩溃环防护 —— 连续 N 次同样错误的 agent 会被暂停为 auth_status: "crashed",而不是无限重试。

[compaction]

基于 LLM 的历史摘要。session 越过消息数门槛或 token 比例门槛后,daemon 启一个后台轮把前半部分历史按用户对话语言摘要,替换为摘要 + 最近 N 轮。

[compaction]
threshold_messages = 30
keep_recent = 10
max_summary_tokens = 1024
token_threshold_ratio = 0.7
max_chunk_chars = 80000
max_retries = 3

Per-agent 覆盖:agent.toml 里 max_history_messages 锁该 agent 的 trim 上限。配置低于全局默认时,compaction 提前触发。

[tool_invoke]

直接工具调用 REST 端点的允许列表(POST /api/tools/{name}/invoke)。默认锁死 —— 两个字段都填了才解锁,否则一切请求 403。

[tool_invoke]
enabled = true
allowlist = ["web_search", "web_fetch", "file_read"]

Glob 语义同 agent capability 授权 —— * 是通配。这个配置是给窄场景用的(CI worker 直调 web_fetch),不是给一般客户端 API 访问用。

[parallel_tools](扩展)

Agent 循环的并行工具分发器(catchup wave 引入)。默认关 —— runtime 仍序列化跑工具调用,直到分发器全量上线。

write_shared 让没标注的 MCP 工具严格序列化, 是安全默认值。审核过单个 server 后再把它们调成 read_only。

资源限制与边界(顶层字段)

全局安全网,封顶入站 payload 大小和 agent 间递归深度。所有字段都有内置默认值 —— 知道自己在干什么再覆盖。

[kernel]
max_upload_size_bytes      = 10485760     # 10 MiB
max_request_body_bytes     = 16777216     # 16 MiB
max_concurrent_bg_llm      = 8
max_agent_call_depth       = 5
local_probe_interval_secs  = 60
strict_config              = false
update_channel             = "stable"     # "stable" | "beta" | "rc"
trusted_hosts              = []
trusted_manifest_signers   = []

后台自治循环执行器

控速断路器(issue #5168):当 LLM provider 限速/配额耗尽时,阻止 continuous/periodic 后台循环无限自我重发。任意一次非限速 tick 重置计数器,所以瞬时抖动不会永久封死健康 agent。

[background]
max_consecutive_rate_limits = 5

Dashboard 鉴权(顶层字段)

从非 loopback 地址访问 dashboard?设用户名密码,首次启动时 LibreFang 自动把密码哈希成 Argon2id。

[kernel]
dashboard_user = "admin"
dashboard_pass = "vault:DASHBOARD_PASS"   # 也可以 plain string 或 env var
# dashboard_pass_hash 自动填入,不要手动改
require_auth_for_reads = true

[skills]

用户安装的 skill 加载与禁用列表。Bundled skill(daemon 自带的约 60 个)总是加载;[skills] 只控制用户放在 ~/.librefang/skills/ 和额外路径下的那些。

[skills]
load_user = true
extra_dirs = ["/srv/librefang/team-skills"]
disabled = ["legacy-research"]

[notification]

approval 请求和任务状态告警发到哪。默认空 = approval 只显示在 dashboard 收件箱 —— 设了 channel 才会同时推送 Telegram / Slack / email 等。

[notification]
# 所有 approval 同时扇出到 Telegram 和 Slack
approval_channels = [
  { kind = "telegram", target = "123456789" },
  { kind = "slack", target = "C0123456" },
]
# 失败告警只到 email
alert_channels = [
  { kind = "email", target = "ops@example.com" },
]

# Per-agent 覆盖 — research-bot 的 approval 改发研究负责人
[[notification.agent_rules]]
agent = "research-bot"
targets = [{ kind = "telegram", target = "987654321" }]

按工具路由(如"shell_exec approval 给 oncall,file_write approval 给开发组")用 [approval] routing,不是 [notification]。

[triggers]

事件驱动 trigger 系统的安全闸门。封顶 trigger 触发频率、单事件最多触发数,以及 trigger 调 trigger 的链深度。

[triggers]
cooldown_secs = 5
max_per_event = 10
max_depth = 5
max_workflow_secs = 3600

cron 和 agent manifest 上的 [[trigger]] 共享这些上限。生产环境不希望 trigger 链就把 max_depth 调成 1。

[task_board]

共享任务队列的安全闸门。Task board 是 agent 拉 pending 工作的持久化队列;worker 认领任务后崩溃没完成的话,sweeper 在 claim_ttl_secs 后把它重置为 pending,让别的 worker 接手。

[task_board]
claim_ttl_secs = 600        # 10 分钟
sweep_interval_secs = 30
max_retries = 0             # 0 = 无限重试

claim_ttl_secs 调到约 2× 最慢任务的预期时长。调太低,健康长任务会被从 worker 手里抢走;太高,崩溃恢复慢。

[registry]

Skill / plugin / 模板注册表同步。注册表镜像在本地 ~/.librefang/registry-cache/,缓存过期后重新下载。

[registry]
cache_ttl_secs = 86400            # 24 小时
registry_mirror = "https://ghproxy.cn"

常见 mirror 值:https://ghproxy.cn、https://gh-proxy.com、内部企业代理。留空直连 GitHub。

[azure_openai]

Azure OpenAI 部署的 provider 专属配置块。Azure 用的 URL 格式和鉴权头都跟标准 OpenAI 不同,所以 platform 驱动有自己的 config 段。三个字段都退到环境变量 —— 看哪种密钥管理风格更顺手。

[azure_openai]
endpoint = "https://my-resource.openai.azure.com"
deployment = "gpt-4o"
api_version = "2024-02-01"

鉴权用 AZURE_OPENAI_API_KEY(头是 api-key,不是 Authorization: Bearer)。完整设置见 Azure OpenAI provider 条目。

顶层字段(运维路径与 per-provider HTTP)

5 个额外的顶层字段,影响 daemon I/O 和 per-provider 网络。所有可选,默认 None 除非另注。

[kernel]
config_version = 1
log_dir = "/var/log/librefang"
qwen_code_path = "/home/user/.local/bin/qwen"

# Per-provider HTTP knob(不在子段下)
[provider_proxy_urls]
openai = "http://corp-proxy.local:8080"
anthropic = "http://corp-proxy.local:8080"
ollama = ""    # 显式"不走代理"覆盖

其他配置段(附录)

这些段在代码里有 schema,但通常保持默认即可。这里的设置只在高级运维场景需要动 —— 列出来,知道字段名时能找到。

# 工具超时 —— 全局默认 + 按工具覆盖
tool_timeout_secs = 60
[tool_timeouts]
"shell_exec" = 300
"web_*"      = 30

# Fallback LLM provider(主 provider 失败时按顺序尝试)
[[fallback_providers]]
provider = "groq"
model    = "llama-3.3-70b-versatile"

# 启动时加载的静态 MCP server
[[mcp_servers]]
name = "github"
url  = "https://api.example.com/mcp"

# Webhook 触发 —— 外部系统把事件推进 LibreFang
[webhook_triggers]
enabled = true
secret_env = "WEBHOOK_TRIGGERS_SECRET"

# Extensions / MCP 集成 —— 自动重连旋钮
[extensions]
auto_reconnect = true
reconnect_max_attempts = 10
reconnect_max_backoff_secs = 300
health_check_interval_secs = 60

# 配置热加载(文件 watcher)
[reload]
enabled = true
debounce_ms = 500

# 入站消息的 auto-reply 后台引擎
[auto_reply]
enabled = false
# (provider 专属调优 —— 见 librefang-runtime::auto_reply)

# 广播路由(多收件人投递)
[broadcast]
enabled = false
max_fanout = 100

# A2UI canvas 工具
[canvas]
enabled = false
max_html_bytes = 524288
allowed_tags = []   # 空 = 所有安全标签

# A2A 协议配置(跨实例 agent-to-agent)
[a2a]
listen_path = "/a2a"
trust_anchors = []

# 设备配对
[pairing]
enabled = true
ttl_secs = 600

# 全局 exec policy(可被 per-agent 或 per-tool 覆盖)
[exec_policy]
allow_shell = true
shell_allowlist = ["git", "cargo", "npm"]