LibreFang 配置参考

LibreFang 配置文件完整参考。


概述

LibreFang 从 TOML 配置文件中读取配置:

~/.librefang/config.toml

关键特性:

  • 所有字段都是可选的,使用 #[serde(default)]
  • 通道配置缺失时表示禁用
  • 密钥存储在环境变量中,不直接存储在配置文件中

目录


最小配置

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

完整配置示例

# ── 顶层字段 ──────────────────────────────────────────────────────────────
api_key          = "your-bearer-token"
dashboard_user   = "admin"
dashboard_pass_hash = "$argon2id$v=19$m=19456,t=2,p=1$<salt>$<hash>"
api_listen       = "127.0.0.1:4545"
cors_origin      = ["https://dash.example.com"]
mode             = "default"          # stable | default | dev
language         = "zh"
stable_prefix_mode = false
prompt_caching   = true
usage_footer     = "full"             # off | tokens | cost | full
workspaces_dir   = "~/.librefang/workspaces"
max_cron_jobs    = 500
include          = ["secrets.toml"]

[provider_urls]
openai = "https://my-openai-proxy.example.com/v1"

[provider_api_keys]
openai = "MY_CUSTOM_OPENAI_KEY"

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

# ── 记忆 ──────────────────────────────────────────────────────────────────
[memory]
decay_rate                   = 0.1
sqlite_path                  = "~/.librefang/data/librefang.db"
embedding_provider           = "openai"
embedding_api_key_env        = "OPENAI_API_KEY"
consolidation_interval_hours = 24

# ── OFP 网络 ──────────────────────────────────────────────────────────────
[network]
listen_addresses = ["/ip4/0.0.0.0/tcp/0"]
shared_secret    = "your-secret"
mdns_enabled     = true
max_peers        = 50

# ── 通道 ──────────────────────────────────────────────────────────────────
[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
allowed_users = ["123456"]

[channels.discord]
bot_token_env = "DISCORD_BOT_TOKEN"
allowed_guilds = ["987654321"]

[channels.slack]
bot_token_env = "SLACK_BOT_TOKEN"
app_token_env = "SLACK_APP_TOKEN"

[channels.whatsapp]
gateway_url_env = "WHATSAPP_WEB_GATEWAY_URL"
allowed_users   = ["+8613800000000"]
owner_numbers   = ["+8613900000000"]

[channels.qq]
app_id         = "123456789"
app_secret_env = "QQ_BOT_APP_SECRET"

[channels.wecom]
corp_id      = "ww1234567890abcdef"
agent_id     = "1000002"
secret_env   = "WECOM_SECRET"
webhook_port = 8454

# ── 媒体理解 ──────────────────────────────────────────────────────────────
[media]
image_description   = true
audio_transcription = true
video_description   = false
max_concurrency     = 2

# ── 链接理解 ──────────────────────────────────────────────────────────────
[links]
enabled  = false
max_links = 3

# ── MCP 服务器 ────────────────────────────────────────────────────────────
[[mcp_servers]]
name = "filesystem"
timeout_secs = 30

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

[[mcp_servers]]
name = "my-api"

[mcp_servers.transport]
type     = "http_compat"
base_url = "https://api.example.com"

[[mcp_servers.transport.tools]]
name   = "search"
path   = "/search"
method = "get"

# ── A2A ───────────────────────────────────────────────────────────────────
[a2a]
enabled     = true
name        = "My LibreFang"
description = "An AI agent"
listen_path = "/a2a"

[[a2a.external_agents]]
name = "remote-agent"
url  = "https://agent.example.com/a2a"

# ── 后备提供商 ────────────────────────────────────────────────────────────
[[fallback_providers]]
provider    = "groq"
model       = "llama-3.1-70b-versatile"
api_key_env = "GROQ_API_KEY"

# ── 用户 ──────────────────────────────────────────────────────────────────
[[users]]
name = "alice"
role = "admin"

[[users]]
name = "bob"
role = "user"

# ── 预算 ──────────────────────────────────────────────────────────────────
[budget]
max_hourly_usd  = 1.0
max_daily_usd   = 10.0
max_monthly_usd = 100.0
alert_threshold = 0.8

# ── 执行审批 ──────────────────────────────────────────────────────────────
[approval]
require_approval        = ["shell_exec"]
timeout_secs            = 60
auto_approve_autonomous = false
auto_approve            = false

# ── 执行策略 ──────────────────────────────────────────────────────────────
[exec_policy]
mode             = "allowlist"
timeout_secs     = 30
max_output_bytes = 102400

# ── Docker 沙箱 ───────────────────────────────────────────────────────────
[docker]
enabled      = false
image        = "python:3.12-slim"
memory_limit = "512m"
timeout_secs = 60

# ── 文字转语音 ────────────────────────────────────────────────────────────
[tts]
enabled  = false
provider = "openai"

[tts.openai]
voice = "alloy"
model = "tts-1"

# ── 扩展思考 ──────────────────────────────────────────────────────────────
[thinking]
budget_tokens   = 10000
stream_thinking = false

# ── 配置热重载 ────────────────────────────────────────────────────────────
[reload]
mode        = "hybrid"
debounce_ms = 500

# ── 代理 ──────────────────────────────────────────────────────────────────
[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]
retention_days          = 30
max_sessions_per_agent  = 100
cleanup_interval_hours  = 24

# ── 工具策略 ──────────────────────────────────────────────────────────────
[tool_policy]
subagent_max_depth      = 10
subagent_max_concurrent = 5

[[tool_policy.global_rules]]
pattern = "shell_*"
effect  = "deny"

[[tool_policy.agent_rules]]
pattern = "web_*"
effect  = "allow"

[[tool_policy.groups]]
name  = "web_tools"
tools = ["web_search", "web_fetch"]

# ── 主动记忆 ──────────────────────────────────────────────────────────────
[proactive_memory]
enabled                = true
auto_memorize          = true
auto_retrieve          = true
max_retrieve           = 10
extraction_threshold   = 0.7
session_ttl_hours      = 24
duplicate_threshold    = 0.5
confidence_decay_rate  = 0.01
max_memories_per_agent = 1000

# ── 审计日志 ──────────────────────────────────────────────────────────────
[audit]
retention_days = 90

# ── 健康检查 ──────────────────────────────────────────────────────────────
[health_check]
health_check_interval_secs = 60

配置项参考

顶层字段

字段类型默认值说明
api_keyString""Bearer 认证令牌,空时 API 不需要认证(仅限本地开发)
dashboard_userString""Dashboard 登录用户名,与 dashboard_passdashboard_pass_hash 任一同时设置时启用登录页
dashboard_passString""Dashboard 登录密码,支持 vault:KEY、环境变量 LIBREFANG_DASHBOARD_PASS、明文
dashboard_pass_hashString""Dashboard 密码的 Argon2id 哈希(PHC 格式,可选)。设置后优先于 dashboard_pass 进行验证。不支持 vault: 和环境变量,需直接写入哈希字符串
api_listenString"127.0.0.1:4545"API 监听地址,也接受别名 listen_addr
cors_originArray<String>[]允许的 CORS 来源(追加到 localhost 之外)
modeEnum"default"运行模式:stable / default / dev
languageString"en"CLI 和消息语言/地区
usage_footerEnum"full"响应尾部用量信息:off / tokens / cost / full
stable_prefix_modeboolfalse启用后避免每轮动态追加内容,提升提示缓存命中率
prompt_cachingbooltrue启用 LLM 提供商提示缓存(Anthropic / OpenAI)
workspaces_dirPath~/.librefang/workspacesAgent 工作区根目录
max_cron_jobsInteger500所有 Agent 的最大 Cron 任务总数
includeArray<String>[]在主配置前合并的子配置文件路径(相对路径,禁止 ..
provider_urlsMap{}Provider 基础 URL 覆盖(provider_id → 自定义 URL),如 openai = "https://my-proxy.com/v1"
provider_api_keysMap{}Provider API Key 环境变量覆盖(provider_id → 环境变量名),如 openai = "MY_OPENAI_KEY"
network_enabledboolfalse是否启用 OFP 网络层
log_levelString"info"日志级别:trace / debug / info / warn / error

Dashboard 密码安全加固(可选)

Dashboard 支持使用 Argon2id 哈希替代明文密码存储。这是可选的安全加固措施,dashboard_pass 仍然完全支持

如果希望在配置文件中避免存储明文密码,可以:

方式一:使用 Vault(推荐)

将密码存入 Vault,配置文件中只引用密钥名:

dashboard_user = "admin"
dashboard_pass = "vault:dashboard_password"

方式二:使用 Argon2id 哈希

使用 CLI 生成哈希:

librefang hash-password
# Enter password: ********
# Confirm password: ********
# $argon2id$v=19$m=19456,t=2,p=1$<salt>$<hash>

将输出的哈希写入 config.toml

dashboard_user      = "admin"
dashboard_pass_hash = "$argon2id$v=19$m=19456,t=2,p=1$<salt>$<hash>"

注意: 迁移到 dashboard_pass_hash 后,已登录的会话需要重新登录。


[default_model]

默认 LLM 提供商配置。不含 max_tokenstemperature(这两个字段由 Agent 配置控制)。

字段类型默认值说明
providerString"anthropic"LLM 提供商(如 anthropicopenaigroq
modelString"claude-sonnet-4-20250514"模型标识符
api_key_envString"ANTHROPIC_API_KEY"持有 API 密钥的环境变量名
base_urlString?nullAPI 基础 URL 覆盖(使用提供商默认值时留空)

[memory]

记忆底层存储配置。

字段类型默认值说明
sqlite_pathPath?nullSQLite 数据库文件路径(默认 ~/.librefang/data/librefang.db
embedding_modelString"all-MiniLM-L6-v2"语义搜索嵌入模型
consolidation_thresholdInteger10000触发整合的记忆数量阈值
decay_rateFloat0.1记忆置信度衰减率(0.0 = 无衰减,1.0 = 激进衰减)
embedding_providerString?null嵌入提供商(如 openaiollama),null 则自动检测
embedding_api_key_envString?null嵌入 API 密钥环境变量名
consolidation_interval_hoursInteger24记忆整合运行间隔(小时,0 = 禁用)

[network]

OFP P2P 网络层配置(仅在 network_enabled = true 时生效)。

注意: API 监听地址在顶层 api_listen 字段中设置,而非此处。

字段类型默认值说明
listen_addressesArray<String>["/ip4/0.0.0.0/tcp/0"]libp2p 监听地址
bootstrap_peersArray<String>[]DHT 引导节点
mdns_enabledbooltrue是否启用 mDNS 本地发现
max_peersInteger50最大已连接节点数
shared_secretString""OFP HMAC 认证共享密钥(启用网络时必填)

通道配置

通道支持单实例([channels.telegram])和多实例([[channels.telegram]])两种写法,实现多 Bot 路由。

[channels.telegram]

字段类型默认值说明
bot_token_envString"TELEGRAM_BOT_TOKEN"持有 Bot Token 的环境变量名
allowed_usersArray<String>[]允许交互的 Telegram 用户 ID(空 = 允许所有)
account_idString?nullBot 实例唯一标识(用于多 Bot 路由)
default_agentString?null默认路由到的 Agent 名称
poll_interval_secsInteger1轮询间隔(秒)
api_urlString?null自定义 Telegram Bot API 基础 URL(代理/镜像)
overridesChannelOverrides通道行为覆盖

[channels.discord]

字段类型默认值说明
bot_token_envString"DISCORD_BOT_TOKEN"持有 Bot Token 的环境变量名
allowed_guildsArray<String>[]允许交互的服务器 ID(空 = 允许所有)
allowed_usersArray<String>[]允许交互的用户 ID(空 = 允许所有)
account_idString?nullBot 实例唯一标识
default_agentString?null默认路由到的 Agent 名称
intentsInteger37376Gateway intents 位掩码
ignore_botsbooltrue是否忽略其他 Bot 的消息
overridesChannelOverrides通道行为覆盖

[channels.slack]

字段类型默认值说明
app_token_envString"SLACK_APP_TOKEN"持有 App 级 Token(xapp-)的环境变量名
bot_token_envString"SLACK_BOT_TOKEN"持有 Bot Token(xoxb-)的环境变量名
allowed_channelsArray<String>[]允许交互的频道 ID(空 = 允许所有)
account_idString?nullBot 实例唯一标识
default_agentString?null默认路由到的 Agent 名称
overridesChannelOverrides通道行为覆盖

[channels.whatsapp]

通过 WhatsApp Web 网关接入(需要自托管网关服务)。

字段类型默认值说明
gateway_url_envString"WHATSAPP_WEB_GATEWAY_URL"持有网关 URL 的环境变量名
allowed_usersArray<String>[]允许交互的 WhatsApp 号码(E.164 格式,空 = 允许所有)
account_idString?nullBot 实例唯一标识(用于多 Bot 路由)
default_agentString?null默认路由到的 Agent 名称
owner_numbersArray<String>[]机器人所有者号码(E.164 格式,授予管理员权限)
overridesChannelOverrides通道行为覆盖

[channels.qq]

QQ 频道机器人(官方 QQ Bot API)。

字段类型默认值说明
app_idString必填QQ Bot 应用 ID
app_secret_envString"QQ_BOT_APP_SECRET"持有应用密钥的环境变量名
allowed_usersArray<String>[]允许交互的 QQ 用户 ID(空 = 允许所有)
account_idString?nullBot 实例唯一标识(用于多 Bot 路由)
default_agentString?null默认路由到的 Agent 名称
overridesChannelOverrides通道行为覆盖
[channels.qq]
app_id         = "123456789"
app_secret_env = "QQ_BOT_APP_SECRET"
allowed_users  = ["10001", "10002"]

[channels.wecom]

企业微信(WeCom / 微信工作)机器人。

字段类型默认值说明
corp_idString必填企业 ID(CorpID)
agent_idString必填应用 AgentID
secret_envString"WECOM_SECRET"持有应用密钥的环境变量名
webhook_portInteger8454接收企业微信回调的端口
token_envString?null持有回调验证 Token 的环境变量名
encoding_aes_key_envString?null持有消息加解密 AES Key 的环境变量名
account_idString?nullBot 实例唯一标识(用于多 Bot 路由)
default_agentString?null默认路由到的 Agent 名称
overridesChannelOverrides通道行为覆盖
[channels.wecom]
corp_id              = "ww1234567890abcdef"
agent_id             = "1000002"
secret_env           = "WECOM_SECRET"
webhook_port         = 8454
token_env            = "WECOM_TOKEN"
encoding_aes_key_env = "WECOM_AES_KEY"

通用说明: 所有通道均支持 account_id(多 Bot 路由标识)、default_agent(默认 Agent 名称)和 overrides(行为覆盖)字段。

通道行为覆盖(ChannelOverrides)

每个通道配置均支持 [channels.<name>.overrides] 覆盖块:

字段类型默认值说明
modelString?null模型覆盖(为空则使用 Agent 默认模型)
system_promptString?null系统提示覆盖
dm_policyEnum"respond"私信策略:respond / allowed_only / ignore
group_policyEnum"mention_only"群消息策略:all / mention_only / commands_only / ignore
rate_limit_per_minuteInteger0通道全局频率限制(每分钟消息数,0 = 无限制)
rate_limit_per_userInteger0每用户频率限制(每分钟,0 = 无限制)
typing_modeEnum?null打字状态模式:instant / message / thinking / never
threadingboolfalse是否启用线程回复
output_formatEnum?null输出格式:markdown / telegram_html / slack_mrkdwn / plain_text
usage_footerEnum?null用量尾部模式覆盖

[[mcp_servers]]

MCP(Model Context Protocol)服务器配置。commandargs 位于 [mcp_servers.transport] 下,而非顶层。

字段类型默认值说明
nameString必填服务器显示名称
timeout_secsInteger30请求超时(秒)
envArray<String>[]传递给服务器的环境变量名列表

传输类型通过 [mcp_servers.transport] 配置,type 字段指定:

stdio — 子进程 JSON-RPC(stdin/stdout):

[[mcp_servers]]
name = "filesystem"

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

sse — HTTP Server-Sent Events:

[[mcp_servers]]
name = "remote"

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

http_compat — 内置 HTTP/JSON 兼容适配器:

[[mcp_servers]]
name = "my-api"

[mcp_servers.transport]
type     = "http_compat"
base_url = "https://api.example.com"

[[mcp_servers.transport.headers]]
name      = "Authorization"
value_env = "MY_API_KEY"

[[mcp_servers.transport.tools]]
name         = "search"
description  = "Search the API"
path         = "/search"
method       = "get"    # get | post | put | patch | delete
request_mode = "query"  # json_body | query | none

[a2a]

A2A(Agent-to-Agent)协议配置。

字段类型默认值说明
enabledboolfalse是否启用 A2A 协议
nameString"LibreFang Agent OS"well-known Agent 卡片的服务名称
descriptionString""well-known Agent 卡片的服务描述
listen_pathString"/a2a"A2A 端点服务路径

外部 Agent([[a2a.external_agents]]):

字段类型说明
nameString显示名称
urlStringAgent 端点 URL

[[fallback_providers]]

主提供商失败时按顺序尝试的后备提供商链。

字段类型默认值说明
providerString""提供商名称(如 ollamagroq
modelString""使用该提供商的模型
api_key_envString""API 密钥环境变量(本地提供商可留空)
base_urlString?null基础 URL 覆盖

[[users]]

RBAC 多用户支持配置。

字段类型默认值说明
nameString必填用户显示名称
roleString"user"用户角色:owner / admin / user / viewer
channel_bindingsMap{}通道平台 ID 映射,如 {telegram = "123456"}
api_key_hashString?nullAPI 认证密钥哈希(可选)

[web]

网络工具配置(搜索 + 抓取)。

字段类型默认值说明
search_providerEnum"auto"搜索提供商:brave / tavily / perplexity / duck_duck_go / auto
cache_ttl_minutesInteger15缓存 TTL(分钟,0 = 禁用)

[web.brave]:

字段类型默认值说明
api_key_envString"BRAVE_API_KEY"API 密钥环境变量
max_resultsInteger5最大返回结果数
countryString""搜索地区代码(如 US
search_langString""搜索语言(如 en
freshnessString""新鲜度过滤(如 pd = 过去一天,pw = 过去一周)

[web.tavily]:

字段类型默认值说明
api_key_envString"TAVILY_API_KEY"API 密钥环境变量
search_depthString"basic"搜索深度:basic / advanced
max_resultsInteger5最大返回结果数
include_answerbooltrue是否包含 AI 生成的摘要答案

[web.perplexity]:

字段类型默认值说明
api_key_envString"PERPLEXITY_API_KEY"API 密钥环境变量
modelString"sonar"搜索使用的模型

[web.fetch]:

字段类型默认值说明
max_charsInteger50000返回内容的最大字符数
max_response_bytesInteger10485760最大响应体大小(10 MB)
timeout_secsInteger30HTTP 请求超时(秒)
readabilitybooltrue是否启用 HTML→Markdown 可读性提取

[browser]

浏览器自动化配置。

字段类型默认值说明
headlessbooltrue是否以无头模式运行浏览器
viewport_widthInteger1280视口宽度(像素)
viewport_heightInteger720视口高度(像素)
timeout_secsInteger30每次操作超时(秒)
idle_timeout_secsInteger300空闲超时,超时后自动关闭会话(秒)
max_sessionsInteger5最大并发浏览器会话数
chromium_pathString?nullChromium/Chrome 二进制路径(null = 自动检测)

[reload]

配置文件热重载设置。

字段类型默认值说明
modeEnum"hybrid"重载模式:off / restart / hot / hybrid
debounce_msInteger500文件变更防抖窗口(毫秒)

[exec_policy]

Shell/命令执行安全策略。

字段类型默认值说明
modeEnum"allowlist"安全模式:deny(禁止所有)/ allowlist(仅白名单)/ full(允许所有,危险)
safe_binsArray<String>见下绕过白名单的安全二进制文件(仅 stdin 工具)
allowed_commandsArray<String>[]全局命令白名单(mode = allowlist 时生效)
timeout_secsInteger30最大执行超时(秒)
max_output_bytesInteger102400最大输出大小(字节,默认 100 KB)
no_output_timeout_secsInteger30无输出超时,超过后杀死进程(0 = 禁用)

默认 safe_binssleep, true, false, cat, sort, uniq, cut, tr, head, tail, wc, date, echo, printf, basename, dirname, pwd, env


[approval]

工具执行审批策略。

字段类型默认值说明
require_approvalArray<String> 或 bool["shell_exec"]需要审批的工具列表;false = 无;true = 默认集
timeout_secsInteger60审批超时(秒,范围 10–300)
auto_approve_autonomousboolfalse自主模式下自动批准
auto_approveboolfalse启动时清空审批列表(快捷方式)

[budget]

全局消费预算配置。设为 0.0 表示不限制。

字段类型默认值说明
max_hourly_usdFloat0.0每小时最大消费(美元,0 = 不限制)
max_daily_usdFloat0.0每天最大消费(美元)
max_monthly_usdFloat0.0每月最大消费(美元)
alert_thresholdFloat0.8告警阈值(0.0–1.0,达到限额的百分比时触发警告)
default_max_llm_tokens_per_hourInteger0所有 Agent 的默认每小时 Token 限制(0 = 使用各 Agent 自身设置)

[thinking]

扩展思考(Extended Thinking)配置,仅部分提供商支持(如 Anthropic Claude)。

字段类型默认值说明
budget_tokensInteger10000思考 Token 预算上限
stream_thinkingboolfalse是否将思考 Token 流式传输给客户端

[tts]

文字转语音(TTS)配置。

字段类型默认值说明
enabledboolfalse是否启用 TTS
providerString?null默认提供商:openaielevenlabs
max_text_lengthInteger4096TTS 最大文本长度(字符)
timeout_secsInteger30每次 TTS 请求超时(秒)

[tts.openai]:

字段类型默认值说明
voiceString"alloy"语音:alloy / echo / fable / onyx / nova / shimmer
modelString"tts-1"模型:tts-1 / tts-1-hd
formatString"mp3"输出格式:mp3 / opus / aac / flac
speedFloat1.0速度(0.25–4.0)

[tts.elevenlabs]:

字段类型默认值说明
voice_idString"21m00Tcm4TlvDq8ikWAM"语音 ID(默认 Rachel)
model_idString"eleven_monolingual_v1"模型 ID
stabilityFloat0.5稳定性(0.0–1.0)
similarity_boostFloat0.75相似度增强(0.0–1.0)

[docker]

Docker 容器沙箱配置。

字段类型默认值说明
enabledboolfalse是否启用 Docker 沙箱
modeEnum"off"沙箱模式:off / non_main / all
imageString"python:3.12-slim"执行沙箱的 Docker 镜像
container_prefixString"librefang-sandbox"容器名称前缀
workdirString"/workspace"容器内工作目录
networkString"none"网络模式:none / bridge / 自定义
memory_limitString"512m"内存限制(如 256m1g
cpu_limitFloat1.0CPU 限制(如 0.52.0
timeout_secsInteger60最大执行时间(秒)
read_only_rootbooltrue根文件系统只读
pids_limitInteger100PID 限制
tmpfsArray<String>["/tmp:size=64m"]tmpfs 挂载点
cap_addArray<String>[]额外添加的 Linux capabilities
scopeEnum"session"容器生命周期:session / agent / shared
reuse_cool_secsInteger300容器释放后再使用的冷却时间(秒)
idle_timeout_secsInteger86400容器空闲超时,超时后销毁(秒,默认 24 小时)
max_age_secsInteger604800容器最大生存时间(秒,默认 7 天)
blocked_mountsArray<String>[]禁止绑定挂载的路径

[canvas]

Canvas(Agent→UI)配置。

字段类型默认值说明
enabledboolfalse是否启用 canvas 工具
max_html_bytesInteger524288最大 HTML 大小(字节,默认 512 KB)
allowed_tagsArray<String>[]允许的 HTML 标签(空 = 所有安全标签)

[auto_reply]

自动回复引擎配置。

字段类型默认值说明
enabledboolfalse是否启用自动回复引擎
max_concurrentInteger3最大并发自动回复任务数
timeout_secsInteger120每次回复默认超时(秒)
suppress_patternsArray<String>["/stop", "/pause"]触发后抑制自动回复的消息模式

[broadcast]

广播路由配置——向多个 Agent 发送同一条消息。

字段类型默认值说明
strategyEnum"parallel"广播策略:parallel(并行)/ sequential(顺序)
routesMap{}peer_id → Agent 名称列表的映射

[inbox]

文件收件箱——将文本文件投入监听目录,自动作为消息分发给 Agent。处理后的文件会移至 processed/ 子目录,避免重复投递。

[inbox]
enabled = true
directory = "~/.librefang/inbox/"
poll_interval_secs = 5
default_agent = "assistant"
字段类型默认值说明
enabledboolfalse启用收件箱目录监听
directoryString?null监听目录路径,默认 $HOME_DIR/inbox/,支持 ~ 展开
poll_interval_secsu645扫描目录的间隔(秒),最小为 1
default_agentString?null文件中无 agent: 指令时的默认目标 Agent

文件格式: 纯文本文件(.txt.md.json.py 等)。首行可写 agent:<名称> 指定目标 Agent,其余内容作为消息体发送。无指令时使用 default_agent

安全限制: 超过 1 MB 的文件会被跳过;二进制文件(非文本扩展名)会被跳过;空文件直接移至 processed/,不发送。

使用示例:

指定 Agent 处理:

cat > ~/.librefang/inbox/task.txt << 'EOF'
agent:code-reviewer
请审查以下代码的安全性:

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

使用默认 Agent:

echo "帮我总结今天的系统日志" > ~/.librefang/inbox/summarize.txt

Cron 定时任务:

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

CI/CD 构建失败时自动分析:

# Jenkinsfile / GitHub Actions post-build step
echo "agent:devops
构建失败,请分析日志:
$(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,...}

使用场景:

  • Cron / 脚本自动化 — 定时任务输出结果丢入目录,Agent 自动分析
  • CI/CD 联动 — 构建失败时将日志写入 inbox,Agent 做根因分析
  • 监控告警 — Prometheus / Alertmanager 告警落盘后由 Agent 处理
  • 批量处理 — 一次性拷入多个文件,Agent 逐个处理
  • 低代码集成 — 不会写代码的用户直接往文件夹拖文件即可与 Agent 交互
  • 离线 / 隔离环境 — 无需网络,通过文件传输即可驱动 Agent

[[bindings]]

Agent 绑定——将特定通道/账户/节点模式路由到指定 Agent。

字段类型说明
agentString目标 Agent 名称或 ID
match_rule.channelString?通道类型(如 discordtelegram
match_rule.account_idString?通道内的特定账户/Bot ID
match_rule.peer_idString?用于私信路由的节点/用户 ID
match_rule.guild_idString?服务器/空间 ID(Discord/Slack)
match_rule.rolesArray<String>基于角色的路由(用户至少拥有其中一个)

[pairing]

设备配对配置。

字段类型默认值说明
enabledboolfalse是否启用设备配对
max_devicesInteger10最大配对设备数
token_expiry_secsInteger300配对 Token 有效期(秒,默认 5 分钟)
push_providerString"none"推送通知提供商:none / ntfy / gotify
ntfy_urlString?nullNtfy 服务器 URL
ntfy_topicString?nullNtfy 主题

[extensions]

扩展和集成配置(主要影响 MCP 重连行为)。

字段类型默认值说明
auto_reconnectbooltrue是否自动重连 MCP 集成
reconnect_max_attemptsInteger10最大重连次数
reconnect_max_backoff_secsInteger300最大回退时长(秒)
health_check_interval_secsInteger60健康检查间隔(秒)

[vault]

凭证保险库配置。

字段类型默认值说明
enabledbooltrue是否启用 vault(存在 vault.enc 时自动启用)
pathPath?null自定义 vault 文件路径(默认 ~/.librefang/vault.enc

[webhook_triggers]

Webhook 触发器配置,用于外部系统触发 Agent 动作(/hooks/wake/hooks/agent 端点)。

字段类型默认值说明
enabledboolfalse是否启用 webhook 触发端点
token_envString"LIBREFANG_WEBHOOK_TOKEN"持有 Bearer Token 的环境变量名(长度 ≥ 32 字符)
max_payload_bytesInteger65536最大 payload 大小(字节)
rate_limit_per_minuteInteger30每 IP 每分钟最大请求数

[proxy]

所有出站连接的 HTTP 代理配置。支持 HTTP_PROXY / HTTPS_PROXY / NO_PROXY 环境变量作为回退。

字段类型默认值说明
http_proxyString?nullHTTP 代理 URL(如 http://proxy:8080
https_proxyString?nullHTTPS 代理 URL
no_proxyString?null绕过代理的主机/域名列表(逗号分隔)

[[sidecar_channels]]

Sidecar 通道适配器——外部进程(任意语言)通过 stdin/stdout 的换行分隔 JSON 与内核通信。

字段类型默认值说明
nameString必填适配器显示名称
commandString必填执行命令(如 python3
argsArray<String>[]命令参数
envMap{}传递给子进程的额外环境变量
channel_typeString?null通道类型标识符(默认 Custom(name)

[session]

会话保留策略配置,控制旧会话的自动清理。

字段类型默认值说明
retention_daysInteger0空闲会话最大保留天数(0 = 不限制)
max_sessions_per_agentInteger0每个 Agent 最大会话数,超出后删除最旧的(0 = 不限制)
cleanup_interval_hoursInteger24清理任务运行间隔(小时)

[queue]

消息队列配置,控制队列深度限制、任务 TTL 和并发数。

字段类型默认值说明
max_depth_per_agentInteger0每 Agent 最大队列深度(0 = 不限制)
max_depth_globalInteger0全局最大队列深度(0 = 不限制)
task_ttl_secsInteger3600任务 TTL(秒,未处理的任务过期,0 = 不限制)

[queue.concurrency] — 各通道并发限制:

字段类型默认值说明
main_laneInteger3主通道并发数(用户消息)
cron_laneInteger2Cron 通道并发数(定时任务)
subagent_laneInteger3子 Agent 通道并发数

[external_auth]

外部身份认证提供商配置(OAuth2/OIDC)。

字段类型默认值说明
enabledboolfalse是否启用外部认证
issuer_urlString""OIDC 颁发者 URL(如 https://accounts.google.com
client_idString""OAuth2 客户端 ID
client_secret_envString"LIBREFANG_OAUTH_CLIENT_SECRET"持有客户端密钥的环境变量名
redirect_urlString"http://127.0.0.1:4545/api/auth/callback"OAuth2 回调 URL
scopesArray<String>["openid","profile","email"]请求的 OAuth2 权限范围
allowed_domainsArray<String>[]允许的邮件域名(空 = 允许所有)
audienceString""JWT audience claim(默认使用 client_id
session_ttl_secsInteger86400会话 Token 有效期(秒,默认 24 小时)
providersArray[]多 OIDC/OAuth2 提供商配置(优先于顶层字段)

[vertex_ai]

Vertex AI 提供商配置(Google Cloud)。

字段类型默认值说明
project_idString?nullGCP 项目 ID
regionString?nullGCP 区域(如 us-central1
credentials_pathString?null服务账号 JSON 文件路径或 JSON 字符串内容

凭证解析顺序:

  1. 配置中的 credentials_path
  2. VERTEX_AI_SERVICE_ACCOUNT_JSON 环境变量
  3. GOOGLE_APPLICATION_CREDENTIALS 环境变量(文件路径)
  4. gcloud auth print-access-token CLI 回退

[oauth]

PKCE 流程的 OAuth 客户端 ID 覆盖。

字段类型默认值说明
google_client_idString?nullGoogle OAuth2 客户端 ID
github_client_idString?nullGitHub OAuth 客户端 ID
microsoft_client_idString?nullMicrosoft (Entra ID) OAuth 客户端 ID
slack_client_idString?nullSlack OAuth 客户端 ID

[auth_profiles]

每个提供商的多密钥轮换配置,当某个密钥被限速或账单异常时自动切换。

[auth_profiles]
anthropic = [
  { name = "primary",   api_key_env = "ANTHROPIC_API_KEY",   priority = 0 },
  { name = "secondary", api_key_env = "ANTHROPIC_API_KEY_2", priority = 1 },
]
字段类型默认值说明
nameString必填配置名称(如 primarysecondary
api_key_envString必填持有 API 密钥的环境变量名
priorityInteger0优先级(值越小越优先)

[tool_policy]

全局工具策略配置,支持 glob 模式匹配、工具分组和子 Agent 深度限制。

字段类型默认值说明
global_rulesArray[]全局规则(在 agent_rules 之后检查)
agent_rulesArray[]Agent 级规则(最高优先级)
groupsArray[]命名工具分组
subagent_max_depthInteger10子 Agent 最大嵌套深度
subagent_max_concurrentInteger5最大并发子 Agent 数

规则格式:

[[tool_policy.global_rules]]
pattern = "shell_*"
effect  = "deny"    # allow | deny

[[tool_policy.groups]]
name  = "web_tools"
tools = ["web_search", "web_fetch"]

[proactive_memory]

主动记忆(mem0 风格)配置。

字段类型默认值说明
enabledbooltrue总开关(false 时禁用整个主动记忆子系统)
auto_memorizebooltrueAgent 执行后自动记忆
auto_retrievebooltrueAgent 执行前自动检索
max_retrieveInteger10每次查询最大检索记忆数
extraction_thresholdFloat0.7近似重复检测置信度阈值(0.0–1.0)
extraction_modelString?nullLLM 提取模型(null = 基于规则的提取)
extract_categoriesArray<String>见下从对话中提取的类别
session_ttl_hoursInteger24会话记忆 TTL(小时)
duplicate_thresholdFloat0.5重复检测相似度阈值(0.0–1.0)
confidence_decay_rateFloat0.01每天置信度衰减率(指数衰减)
max_memories_per_agentInteger1000每个 Agent 最大记忆数(0 = 不限制)

默认 extract_categoriesuser_preferenceimportant_facttask_contextrelationship


[context_engine]

可插拔上下文引擎配置。

字段类型默认值说明
engineString"default"内置引擎名称
pluginString?null插件名称(解析到 ~/.librefang/plugins/<name>/plugin.toml

[context_engine.hooks] — Python 脚本钩子:

字段类型默认值说明
ingestString?null新用户消息时调用的 Python 脚本路径
after_turnString?null每轮结束后调用的 Python 脚本路径

[[context_engine.plugin_registries]] — 插件注册表:

字段类型说明
nameString注册表显示名称
github_repoStringGitHub owner/repo(如 librefang/librefang-registry

[audit]

审计日志配置。

字段类型默认值说明
retention_daysInteger90审计日志条目保留天数(0 = 永久保留)

[health_check]

健康检查配置。

字段类型默认值说明
health_check_interval_secsInteger60LLM 提供商定期健康检查间隔(秒)

[plugins]

插件注册表配置。

字段类型默认值说明
plugin_registriesArray<String>[]额外的 GitHub owner/repo 插件注册表,与 context_engine.plugin_registries 合并

[media]

多媒体理解配置——控制图片描述、音频转录和视频理解功能。

字段类型默认值说明
image_descriptionbooltrue是否启用图片自动描述
audio_transcriptionbooltrue是否启用音频自动转录
video_descriptionboolfalse是否启用视频自动描述(开销较大,默认关闭)
max_concurrencyInteger2最大并发媒体处理任务数
image_providerString?null图片描述首选提供商(null = 自动检测)
audio_providerString?null音频转录首选提供商(null = 自动检测)
[media]
image_description   = true
audio_transcription = true
video_description   = false
max_concurrency     = 2
image_provider      = "openai"   # 可选:显式指定提供商
audio_provider      = "openai"   # 可选:显式指定提供商

链接内容理解配置——控制消息中 URL 链接的自动抓取与分析。

字段类型默认值说明
enabledboolfalse是否启用自动链接理解
max_linksInteger3每条消息最多处理的链接数
max_content_bytesInteger102400每个链接最大抓取内容大小(字节,默认 100 KB)
timeout_secsInteger10每个链接抓取超时(秒)
[links]
enabled           = true
max_links         = 3
max_content_bytes = 102400
timeout_secs      = 10

环境变量

LibreFang 使用以下环境变量:

变量说明
ANTHROPIC_API_KEYAnthropic Claude API 密钥
OPENAI_API_KEYOpenAI API 密钥
GROQ_API_KEYGroq API 密钥
GEMINI_API_KEYGoogle Gemini API 密钥
DEEPSEEK_API_KEYDeepSeek API 密钥
BRAVE_API_KEYBrave Search API 密钥
TAVILY_API_KEYTavily Search API 密钥
PERPLEXITY_API_KEYPerplexity Search API 密钥
TELEGRAM_BOT_TOKENTelegram Bot Token
DISCORD_BOT_TOKENDiscord Bot Token
SLACK_BOT_TOKENSlack Bot Token
SLACK_APP_TOKENSlack App Token
LIBREFANG_DASHBOARD_USERDashboard 登录用户名覆盖
LIBREFANG_DASHBOARD_PASSDashboard 登录密码覆盖
LIBREFANG_HOMELibreFang 主目录覆盖(默认 ~/.librefang
LIBREFANG_WEBHOOK_TOKENWebhook 触发端点 Bearer Token
LIBREFANG_OAUTH_CLIENT_SECRETOAuth2 客户端密钥
VERTEX_AI_SERVICE_ACCOUNT_JSONVertex AI 服务账号 JSON
GOOGLE_APPLICATION_CREDENTIALSGCP 服务账号文件路径
HTTP_PROXY / HTTPS_PROXY / NO_PROXYHTTP 代理设置
RUST_LOG日志级别(info / debug / trace

验证

运行诊断命令检查配置:

librefang doctor

这将检查:

  • 配置文件存在性
  • API 密钥配置
  • 网络连接
  • 依赖项可用性