LibreFang 配置参考
config.toml 的完整参考文档，涵盖 LibreFang Agent OS 中每一个可配置字段。
LibreFang 从以下 TOML 文件读取配置：
~ /.librefang/config.toml Copied! 在 Windows 上，~ 解析为 C:\Users\<用户名>。如果无法确定用户主目录，则会使用系统临时目录作为后备路径。
核心行为：
配置中的每个结构体都使用了 #[serde(default)]，这意味着所有字段都是可选的 。未填写的字段将使用文档中说明的默认值。
通道配置节（[channels.telegram]、[channels.discord] 等）采用 Option<T> 类型——缺少该节时，对应的通道适配器将被禁用 。即使只写了节头（内容为空），也会以默认值启用该适配器。
密钥绝不直接存储在 config.toml 中 。api_key_env 和 bot_token_env 等字段保存的是环境变量的名称 ，实际密钥从该环境变量中读取，以防止密钥被意外提交到版本控制系统。
敏感字段（api_key、shared_secret）在调试输出和日志中会被自动脱敏。
LibreFang 支持通过 include 字段将配置拆分到多个文件中。这使得可以实现模块化配置（例如将通道配置、MCP 服务器配置或特定环境的覆盖配置分开存放）。
# ~/.librefang/config.toml include = [ "channels.toml" , "mcp.toml" , "overrides/prod.toml" ] Copied! 规则：
路径相对于 根配置文件所在的目录。
绝对路径 会在启动时报错并被拒绝。包含 .. 路径穿越
最大包含嵌套深度：10 层 。
被包含的文件在根配置之前 进行深度合并。根配置中的值始终覆盖 被包含文件中的值。
被包含的文件本身也可以包含 include 数组（受深度限制约束）。
此机制适用于将密钥放在具有更严格文件系统权限的独立文件中，或在多个环境之间共享基础配置。
最简单的可用配置只需将 LLM 提供商的 API Key 设置为环境变量。如果没有配置文件，LibreFang 将以 Anthropic 作为默认提供商启动：
# ~/.librefang/config.toml # 最小配置：仅在需要非默认模型时进行覆盖。 # 在环境变量中设置 ANTHROPIC_API_KEY。 [ default_model ] provider = "anthropic" model = "claude-sonnet-4-20250514" api_key_env = "ANTHROPIC_API_KEY" Copied! 或者使用本地 Ollama 实例（无需 API Key）：
[ default_model ] provider = "ollama" model = "llama3.2:latest" base_url = "http://localhost:11434" api_key_env = "" Copied! # ============================================================ # LibreFang Agent OS -- 完整配置参考 # ============================================================ # --- 顶层字段 --- home_dir = "~/.librefang" # LibreFang 主目录 data_dir = "~/.librefang/data" # SQLite 数据库和数据文件 log_level = "info" # trace | debug | info | warn | error api_listen = "127.0.0.1:4545" # HTTP/WS API 绑定地址 network_enabled = false # 启用 OFP 点对点网络 api_key = "" # API Bearer 令牌（空值 = 无需认证） dashboard_user = "" # 仪表盘登录用户名（空值 = 无需登录） dashboard_pass = "" # 仪表盘登录密码（支持 vault:KEY 语法） mode = "default" # stable | default | dev update_channel = "stable" # stable | beta | rc — CLI 更新通道 language = "en" # CLI/消息的语言区域设置 usage_footer = "full" # off | tokens | cost | full prompt_caching = true # 启用 LLM 提示词缓存 stable_prefix_mode = false # 减少提示词缓存失效 max_cron_jobs = 500 # 全局最大定时任务数 tool_timeout_secs = 300 # 所有工具的全局超时（秒） cors_origin = [] # CORS 允许的来源 include = [] # 配置文件包含 [ provider_urls ] # ollama = "http://192.168.1.100:11434/v1" [ provider_api_keys ] # nvidia = "NVIDIA_API_KEY" [ provider_regions ] # qwen = "intl" # 使用 Qwen 国际端点 (dashscope-intl) # minimax = "china" # 使用 MiniMax 中国端点 (MINIMAX_CN_API_KEY) # --- 工具超时 --- [ tool_timeouts ] agent_send = 600 # agent_send 工具的覆盖 agent_spawn = 600 # agent_spawn 工具的覆盖 "mcp_browser_*" = 900 # 浏览器 MCP 工具的 glob 模式 shell_exec = 300 # shell_exec 工具的覆盖 # --- 默认 LLM 提供商 --- [ default_model ] provider = "anthropic" model = "claude-sonnet-4-20250514" api_key_env = "ANTHROPIC_API_KEY" # base_url = "https://api.anthropic.com" # 可选覆盖 # --- 后备提供商 --- [[ 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" # --- 记忆系统 --- [ memory ] # sqlite_path = "~/.librefang/data/librefang.db" # 省略则自动解析 embedding_model = "all-MiniLM-L6-v2" consolidation_threshold = 10000 decay_rate = 0.1 # --- 网络（OFP 线路协议） --- [ network ] listen_addresses = [ "/ip4/0.0.0.0/tcp/0" ] bootstrap_peers = [] mdns_enabled = true max_peers = 50 shared_secret = "" # network_enabled = true 时必填 # --- 网页工具 --- [ web ] search_provider = "auto" # auto | brave | jina | tavily | perplexity | duckduckgo cache_ttl_minutes = 15 timeout_secs = 15 [ web . brave ] api_key_env = "BRAVE_API_KEY" max_results = 5 country = "" search_lang = "" freshness = "" [ web . tavily ] api_key_env = "TAVILY_API_KEY" search_depth = "basic" # basic | advanced max_results = 5 include_answer = true [ web . jina ] api_key_env = "JINA_API_KEY" max_results = 5 [ web . perplexity ] api_key_env = "PERPLEXITY_API_KEY" model = "sonar" [ web . fetch ] max_chars = 50000 max_response_bytes = 10485760 # 10 MB timeout_secs = 30 readability = true # --- 媒体理解 --- [ media ] image_description = true audio_transcription = true video_description = false max_concurrency = 2 # image_provider = "openai" # audio_provider = "openai" # --- 链接理解 --- [ links ] enabled = false max_links = 3 max_content_bytes = 102400 timeout_secs = 10 # --- MCP 服务器 --- [[ mcp_servers ]] name = "filesystem" timeout_secs = 30 env = [] [ mcp_servers . transport ] type = "stdio" command = "npx" args = [ "-y" , "@modelcontextprotocol/server-filesystem" , "/tmp" ] [[ mcp_servers ]] name = "remote-tools" timeout_secs = 60 env = [ "REMOTE_API_KEY" ] [ mcp_servers . transport ] type = "sse" url = "https://mcp.example.com/events" [[ 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" # --- A2A 协议 --- [ a2a ] enabled = false name = "LibreFang Agent OS" description = "" listen_path = "/a2a" [[ a2a . external_agents ]] name = "research-agent" url = "https://agent.example.com/.well-known/agent.json" # --- RBAC 用户 --- [[ users ]] name = "Alice" role = "owner" # owner | admin | user | viewer api_key_hash = "" [ users . channel_bindings ] telegram = "123456" discord = "987654321" [[ users ]] name = "Bob" role = "user" [ users . channel_bindings ] slack = "U0123ABCDEF" # --- 通道适配器 --- # （所有 45 个适配器的详细说明见下方"通道配置"章节） [ channels . telegram ] bot_token_env = "TELEGRAM_BOT_TOKEN" allowed_users = [] # default_agent = "assistant" poll_interval_secs = 1 [ channels . discord ] bot_token_env = "DISCORD_BOT_TOKEN" allowed_guilds = [] intents = 37376 [ channels . slack ] app_token_env = "SLACK_APP_TOKEN" bot_token_env = "SLACK_BOT_TOKEN" allowed_channels = [] # [channels.qq] # app_id = "your-app-id" # app_secret_env = "QQ_BOT_APP_SECRET" # [channels.wecom] # bot_id = "YOUR_BOT_ID" # secret_env = "WECOM_BOT_SECRET" # [channels.wechat] # bot_token_env = "WECHAT_BOT_TOKEN" # 可选：重启时跳过二维码登录 # default_agent = "assistant" # allowed_users = [] # --- 浏览器自动化 --- [ browser ] headless = true viewport_width = 1280 viewport_height = 720 timeout_secs = 30 idle_timeout_secs = 300 max_sessions = 5 # --- 配置热重载 --- [ reload ] mode = "hybrid" # off | restart | hot | hybrid debounce_ms = 500 # --- Shell 执行策略 --- [ exec_policy ] mode = "allowlist" # deny | allowlist | full timeout_secs = 30 max_output_bytes = 102400 no_output_timeout_secs = 30 # --- 预算 --- [ budget ] max_hourly_usd = 0.0 max_daily_usd = 0.0 max_monthly_usd = 0.0 alert_threshold = 0.8 default_max_llm_tokens_per_hour = 0 # --- 扩展思维 --- [ thinking ] budget_tokens = 10000 stream_thinking = false # --- 语音合成 --- [ tts ] enabled = false max_text_length = 4096 timeout_secs = 30 [ tts . openai ] voice = "alloy" model = "tts-1" format = "mp3" speed = 1.0 # --- Docker 沙箱 --- [ docker ] enabled = false image = "python:3.12-slim" network = "none" memory_limit = "512m" cpu_limit = 1.0 timeout_secs = 60 read_only_root = true mode = "off" # off | non_main | all scope = "session" # session | agent | shared cap_add = [] # 例如 ["NET_ADMIN"] tmpfs = [ "/tmp:size=64m" ] pids_limit = 100 # --- 密钥库 --- [ vault ] enabled = true # path = "~/.librefang/vault.enc" # --- Webhook 触发器 --- [ webhook_triggers ] enabled = false token_env = "LIBREFANG_WEBHOOK_TOKEN" max_payload_bytes = 65536 rate_limit_per_minute = 30 # --- HTTP 代理 --- [ 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 = 0 max_sessions_per_agent = 0 cleanup_interval_hours = 24 # --- 终端 --- [ terminal ] enabled = true # allow_remote = false # allow_unauthenticated_remote = false # allowed_origins = [] # require_proxy_headers = false # tmux_enabled = true # max_windows = 16 # tmux_binary_path = "" # --- 队列 --- [ queue ] max_depth_per_agent = 0 max_depth_global = 0 task_ttl_secs = 3600 [ queue . concurrency ] main_lane = 3 cron_lane = 2 subagent_lane = 3 # --- 审计 --- [ audit ] retention_days = 90 # --- 外部认证（OAuth2/OIDC） --- [ external_auth ] enabled = false # issuer_url = "https://accounts.google.com" # client_id = "your-client-id" # client_secret_env = "LIBREFANG_OAUTH_CLIENT_SECRET" # --- Vertex AI --- [ vertex_ai ] # project_id = "my-gcp-project" # region = "us-central1" # credentials_path = "/path/to/service-account.json" # --- 上下文引擎 --- [ context_engine ] engine = "default" # plugin = "qdrant-recall" # --- 插件 --- [ plugins ] plugin_registries = [] Copied! 顶层字段
以下字段位于 config.toml 的根层级（不在任何 [section] 内部）。
字段 类型 默认值 说明 home_dirpath ~/.librefangLibreFang 主目录，存储配置、Agent、技能等。 data_dirpath ~/.librefang/dataSQLite 数据库和持久化数据的目录。 log_levelstring "info"日志级别。可选值：trace、debug、info、warn、error。 api_listenstring "127.0.0.1:4545"HTTP/WebSocket/SSE API 服务器的绑定地址。别名：listen_addr。 network_enabledbool false启用 OFP 点对点网络层。 api_keystring ""（空）API 认证密钥。设置后，除 /api/health 外的所有端点均需要 Authorization: Bearer <key> 请求头。空值表示不需要认证（仅限本地开发使用）。 cors_originlist of strings []除 localhost 外额外允许的 CORS 来源。例如 ["https://dash.example.com"]。 modestring "default"内核运行模式。见下表。 languagestring "en"CLI 输出和系统消息的语言/区域代码。 usage_footerstring "full"控制附加到回复末尾的用量信息。见下表。 prompt_cachingbool true启用 LLM 提供商的提示词缓存。会在系统提示中添加缓存提示（Anthropic 使用 cache_control，OpenAI 自动前缀缓存）。 stable_prefix_modebool false启用后，避免每轮对话都会变化的系统提示内容（如回忆记忆、标准上下文），从而提高提供商端的提示词缓存命中率。 max_cron_jobsusize 500所有 Agent 的全局最大定时任务数。 workspaces_dirpath 或 null nullAgent 工作区的根目录。默认为 ~/.librefang/workspaces。包含 Agent 工作目录和 hands/ 子目录（用于用户自定义 hands）。 includelist of strings []配置文件包含列表（相对路径）。详见配置文件包含机制 。 provider_urlsmap of string->string {}提供商基础 URL 覆盖。将提供商 ID 映射到自定义基础 URL（例如 ollama = "http://192.168.1.100:11434/v1"）。适用于自托管或代理端点。 provider_api_keysmap of string->string {}提供商 API Key 环境变量覆盖。将提供商 ID 映射到存放密钥的环境变量名称（例如 nvidia = "NVIDIA_API_KEY"）。未设置时，默认使用 {PROVIDER_UPPER}_API_KEY 的命名约定。 provider_regionsmap of string->string {}提供商区域选择。将提供商 ID 映射到提供商注册 TOML 中定义的区域名称（例如 qwen = "intl"）。覆盖提供商的基础 URL，并可选择性覆盖其 API Key 环境变量。在 provider_urls 之前生效（优先级较低）。 tool_timeout_secsu64 300所有工具执行的全局超时（秒）。可通过 [tool_timeouts] 节按工具覆盖。 tool_timeoutsmap of string->u64 {}每个工具的超时覆盖。键是精确的工具名称或 glob 模式。详见 [tool_timeouts] 节。
mode 值说明：
值 行为 stable保守模式：不自动更新，锁定模型版本，冻结技能注册表。使用 FallbackDriver。 default均衡模式：标准运行。 dev开发者模式：启用实验性功能。
usage_footer 值说明：
值 行为 off不显示用量信息。 tokens仅显示 Token 数量。 cost仅显示预估费用。 full同时显示 Token 数量和预估费用（默认）。
[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" Copied! 字段 类型 默认值 说明 providerstring "anthropic"提供商名称。支持：anthropic、gemini、openai、groq、openrouter、deepseek、together、mistral、fireworks、ollama、vllm、lmstudio、perplexity、cohere、ai21、cerebras、sambanova、huggingface、xai、replicate。 modelstring "claude-sonnet-4-20250514"模型标识符。别名（如 sonnet、haiku、gpt-4o、gemini-flash）由模型目录自动解析。 api_key_envstring "ANTHROPIC_API_KEY"存放 API Key 的环境变量名称。实际密钥在运行时从该环境变量读取，绝不存储在配置文件中。 base_urlstring 或 null null覆盖 API 基础 URL。适用于代理或自托管端点。为 null 时，使用模型目录中提供商的默认 URL。
[memory]配置基于 SQLite 的记忆基础设施，包括向量嵌入和记忆衰减。
[ memory ] # sqlite_path = "/custom/path/librefang.db" embedding_model = "all-MiniLM-L6-v2" consolidation_threshold = 10000 decay_rate = 0.1 Copied! 字段 类型 默认值 说明 sqlite_pathpath 或 null nullSQLite 数据库文件的显式路径。为 null 时，默认为 {data_dir}/librefang.db。 embedding_modelstring "all-MiniLM-L6-v2"用于生成语义记忆搜索向量嵌入的模型名称。 embedding_providerstring 或 null null嵌入提供商（例如 "openai"、"ollama"）。为 null 时自动检测。 embedding_api_key_envstring 或 null null存放嵌入提供商 API Key 的环境变量名称。 consolidation_thresholdu64 10000触发自动整合（合并和清理旧条目）的存储记忆数量阈值。 consolidation_interval_hoursu64 24记忆整合的运行间隔（小时）。0 = 禁用。 decay_ratef32 0.1记忆置信度衰减率。0.0 = 无衰减（记忆永不消退），1.0 = 快速衰减。取值范围 0.0 到 1.0。
[auto_dream]后台记忆整固（"梦境"）—— 让选择开启的 agent 通过 4 阶段提示词（定位 / 收集 / 整固 / 修剪）反思并整理自己的记忆。触发是 事件驱动 的：agent 每完成一次 turn 即检查闸门；另保留一个稀疏的兜底调度器（默认每天一次）捕获长期不活动的 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/ Copied! 字段 类型 默认值 说明 enabledbool false全局开关。为 false 时即使单个 agent 已开启也不会触发。 min_hoursf64 24.0距离该 agent 上次整固的最小小时数，满足后才会再次触发。 min_sessionsu32 5距离该 agent 上次整固之后，被触及的最少会话数，满足后才会再次触发。设为 0 则禁用该闸门。 check_interval_secsu64 86400兜底调度器的唤醒间隔（秒）。主触发路径是 AgentLoopEnd 钩子，此字段只控制从不 turn 的 agent 的兜底节奏。 timeout_secsu64 600单次梦境调用的超时时间（秒）。 lock_dirstring ""锁目录的可选覆盖路径。为空则使用 <data_dir>/auto_dream/，每个 agent 的锁存储为 <dir>/<agent_id>.lock。
当所有闸门同时满足时才会触发：enabled = true、agent manifest 中 auto_dream_enabled = true、距离上次梦境至少 min_hours 小时、至少触及 min_sessions 个会话、以及能获取到该 agent 的文件锁。
每个 agent 的 opt-in 状态可在运行时通过 PUT /api/auto-dream/agents/{id}/enabled（请求体 {"enabled": bool}）或 Web Dashboard 的设置页 → 梦境模式卡片切换 —— 新状态在下一次 turn 结束（事件驱动）或下一次兜底 tick 时生效，以先到者为准。完整参考（包含运行时工具限制、手动控制、审计事件）见 /zh/configuration/core#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" Copied! 字段 类型 默认值 说明 listen_addresseslist of strings ["/ip4/0.0.0.0/tcp/0"]监听的 libp2p 多地址。端口 0 表示自动分配。 bootstrap_peerslist of strings []用于 DHT 发现的引导节点多地址。 mdns_enabledbool true启用 mDNS 以自动发现本地网络中的对等节点。 max_peersu32 50最大同时连接的对等节点数。 shared_secretstring ""（空）OFP HMAC-SHA256 双向认证的预共享密钥。当 network_enabled = true 时必填 。通信双方必须使用相同的密钥。日志中会脱敏处理。
[web]配置 Agent 工具使用的网页搜索和网页抓取能力。
[ web ] search_provider = "auto" cache_ttl_minutes = 15 timeout_secs = 15 Copied! 字段 类型 默认值 说明 search_providerstring "auto"使用的搜索引擎。见下表。 cache_ttl_minutesu64 15搜索/抓取结果的缓存时长（分钟）。0 = 禁用缓存。 timeout_secsu64 15所有网页搜索请求的 HTTP 超时时间（秒）。建议：大多数提供商使用 15，Jina 建议使用 30 以上。
search_provider 值说明：
值 说明 auto级联回退：根据可用的 API Key，依次尝试 Tavily、Brave、Jina、Perplexity、DuckDuckGo。 braveBrave Search API。需要 BRAVE_API_KEY。 jinaJina AI 搜索与信息定位。需要 JINA_API_KEY。 tavilyTavily AI 原生搜索。需要 TAVILY_API_KEY。 perplexityPerplexity AI 搜索。需要 PERPLEXITY_API_KEY。 duckduckgoDuckDuckGo HTML 抓取。无需 API Key。
[web.brave][ web . brave ] api_key_env = "BRAVE_API_KEY" max_results = 5 country = "" search_lang = "" freshness = "" Copied! 字段 类型 默认值 说明 api_key_envstring "BRAVE_API_KEY"存放 Brave Search API Key 的环境变量名称。 max_resultsusize 5返回的最大搜索结果数。 countrystring ""用于本地化结果的国家代码（例如 "US"、"GB"）。空值 = 不过滤。 search_langstring ""语言代码（例如 "en"、"fr"）。空值 = 不过滤。 freshnessstring ""时效性过滤。"pd" = 过去一天，"pw" = 过去一周，"pm" = 过去一月。空值 = 不过滤。
[web.tavily][ web . tavily ] api_key_env = "TAVILY_API_KEY" search_depth = "basic" max_results = 5 include_answer = true Copied! 字段 类型 默认值 说明 api_key_envstring "TAVILY_API_KEY"存放 Tavily API Key 的环境变量名称。 search_depthstring "basic"搜索深度："basic" 快速返回结果，"advanced" 进行更深入的分析。 max_resultsusize 5返回的最大搜索结果数。 include_answerbool true是否在结果中包含 Tavily 的 AI 生成答案摘要。
[web.jina][ web . jina ] api_key_env = "JINA_API_KEY" max_results = 5 Copied! 字段 类型 默认值 说明 api_key_envstring "JINA_API_KEY"存放 Jina AI API Key 的环境变量名称。 max_resultsusize 5返回的最大搜索结果数。
[web.perplexity][ web . perplexity ] api_key_env = "PERPLEXITY_API_KEY" model = "sonar" Copied! 字段 类型 默认值 说明 api_key_envstring "PERPLEXITY_API_KEY"存放 Perplexity API Key 的环境变量名称。 modelstring "sonar"用于搜索查询的 Perplexity 模型。
[web.fetch][ web . fetch ] max_chars = 50000 max_response_bytes = 10485760 timeout_secs = 30 readability = true # 可选：允许 Agent 访问内部服务（自托管 / K8s 部署）。 # 云元数据端点（169.254.x.x、100.64.x.x）无论如何都会被阻止。 # ssrf_allowed_hosts = [ # "10.0.0.0/8", # CIDR — 整个私有子网 # "*.internal.example.com", # glob — 所有子域名 # "svc.cluster.local", # 字面主机名 # ] Copied! 字段 类型 默认值 说明 max_charsusize 50000抓取内容返回的最大字符数。超出部分将被截断。 max_response_bytesusize 10485760（10 MB）HTTP 响应体的最大大小（字节）。 timeout_secsu64 30HTTP 请求超时时间（秒）。 readabilitybool true启用 HTML 到 Markdown 的可读性提取。开启后，抓取的 HTML 会被转换为干净的 Markdown 格式。 ssrf_allowed_hosts字符串列表 []豁免 SSRF 拦截的主机/CIDR 列表。支持 CIDR 格式（"10.0.0.0/8"）、glob 前缀通配符（"*.internal.example.com"）以及字面 IP 或主机名。云元数据地址段（169.254.0.0/16、100.64.0.0/10）无论如何都会被拦截 ，不受此列表影响。
配置媒体理解能力（图片描述、音频转录、视频描述），用于处理包含附件的消息。
[ media ] image_description = true audio_transcription = true video_description = false max_concurrency = 2 # image_provider = "openai" # 省略则自动检测 # audio_provider = "openai" # 省略则自动检测 Copied! 字段 类型 默认值 说明 image_descriptionbool true启用对传入图片附件的自动描述。 audio_transcriptionbool true启用对传入音频附件的自动转录。 video_descriptionbool false启用视频描述。默认禁用（耗费大且速度慢）。 max_concurrencyusize 2并发媒体处理任务的最大数量。 image_providerstring 或 null null首选的图片描述提供商。为 null 时根据可用提供商自动检测。 audio_providerstring 或 null null首选的音频转录提供商。为 null 时根据可用提供商自动检测。
[links]配置自动链接理解功能——自动抓取并总结传入消息中的 URL。
[ links ] enabled = false max_links = 3 max_content_bytes = 102400 timeout_secs = 10 Copied! 字段 类型 默认值 说明 enabledbool false启用自动链接理解。开启后，消息中的 URL 会被抓取并总结其内容，然后再交给 Agent 处理。 max_linksusize 3每条消息处理的最大链接数。多余的链接会被忽略。 max_content_bytesusize 102400（100 KB）每个链接抓取的最大内容大小（字节）。超出部分将被截断。 timeout_secsu64 10每个链接的抓取超时时间（秒）。
[channels]所有 45 个通道适配器均在 [channels.<name>] 下配置。每个通道采用 Option<T> 类型——省略该节将完全禁用该适配器。即使只写了节头（内容为空），也会以默认值启用该适配器。
通用通道字段： 每个通道适配器除了自身特有的字段外，还支持以下通用字段：
字段 类型 默认值 说明 default_agentstring 或 null null默认将消息路由到的 Agent 名称。 account_idstring 或 null null当前 Bot 实例的唯一标识符。用于通过 [[bindings]] 匹配规则进行多 Bot 路由。 overridesobject （默认值） 每个通道的行为覆盖配置。详见通道行为覆盖 。
[channels.telegram][ channels . telegram ] bot_token_env = "TELEGRAM_BOT_TOKEN" allowed_users = [] # default_agent = "assistant" poll_interval_secs = 1 # api_url = "https://api.telegram.org" # 覆盖用于本地 Bot API 服务器 # account_id = "my-telegram-bot" Copied! 字段 类型 默认值 说明 bot_token_envstring "TELEGRAM_BOT_TOKEN"存放 Telegram Bot API 令牌的环境变量。 allowed_userslist of i64 []允许交互的 Telegram 用户 ID 列表。空列表 = 允许所有人。 default_agentstring 或 null null消息路由的目标 Agent 名称。 poll_interval_secsu64 1长轮询间隔（秒）。 account_idstring 或 null null用于多 Bot 路由的唯一 Bot 实例标识符。 api_urlstring 或 null null覆盖 Telegram Bot API 基础 URL。适用于本地 Bot API 服务器实例。默认为 https://api.telegram.org。 overridesobject （默认值） 每个通道的行为覆盖配置。详见通道行为覆盖 。
[channels.discord][ channels . discord ] bot_token_env = "DISCORD_BOT_TOKEN" allowed_guilds = [] # default_agent = "assistant" intents = 37376 ignore_bots = true # account_id = "my-discord-bot" Copied! 字段 类型 默认值 说明 bot_token_envstring "DISCORD_BOT_TOKEN"存放 Discord Bot 令牌的环境变量。 allowed_guildslist of u64 []允许的服务器（Guild）ID 列表。空列表 = 允许所有。 default_agentstring 或 null null消息路由的目标 Agent 名称。 allowed_userslist of strings []允许交互的 Discord 用户 ID 列表。空列表 = 允许所有。 intentsu64 37376Gateway Intents 位掩码。默认 = GUILD_MESSAGES | DIRECT_MESSAGES | MESSAGE_CONTENT（37376）。 ignore_botsbool true为 true 时，忽略来自其他 Bot 的消息。 account_idstring 或 null null用于多 Bot 路由的唯一 Bot 实例标识符。 overridesobject （默认值） 每个通道的行为覆盖配置。详见通道行为覆盖 。
[channels.slack][ channels . slack ] app_token_env = "SLACK_APP_TOKEN" bot_token_env = "SLACK_BOT_TOKEN" allowed_channels = [] # account_id = "my-slack-bot" Copied! 字段 类型 默认值 说明 app_token_envstring "SLACK_APP_TOKEN"存放 Slack 应用级令牌（xapp-）的环境变量，用于 Socket Mode。 bot_token_envstring "SLACK_BOT_TOKEN"存放 Slack Bot 令牌（xoxb-）的环境变量，用于 REST API。 allowed_channelslist of strings []允许的频道 ID 列表。空列表 = 允许所有。 default_agentstring 或 null null消息路由的目标 Agent 名称。 account_idstring 或 null null用于多 Bot 路由的唯一 Bot 实例标识符。 overridesobject （默认值） 每个通道的行为覆盖配置。详见通道行为覆盖 。
[channels.whatsapp][ channels . whatsapp ] access_token_env = "WHATSAPP_ACCESS_TOKEN" verify_token_env = "WHATSAPP_VERIFY_TOKEN" phone_number_id = "" webhook_port = 8443 allowed_users = [] # gateway_url_env = "WHATSAPP_WEB_GATEWAY_URL" # 用于 QR/Web 模式 # account_id = "my-whatsapp-bot" # owner_numbers = [] # 可选的管理员手机号 Copied! 字段 类型 默认值 说明 access_token_envstring "WHATSAPP_ACCESS_TOKEN"存放 WhatsApp Cloud API 访问令牌的环境变量。 verify_token_envstring "WHATSAPP_VERIFY_TOKEN"存放 Webhook 验证令牌的环境变量。 phone_number_idstring ""WhatsApp Business 手机号 ID。 webhook_portu16 8443监听 Webhook 回调的端口。 gateway_url_envstring "WHATSAPP_WEB_GATEWAY_URL"存放 WhatsApp Web 网关 URL 的环境变量。设置后，发送消息将通过 QR/Web 网关而非 Cloud API 路由。 allowed_userslist of strings []允许的手机号列表。空列表 = 允许所有。 default_agentstring 或 null null消息路由的目标 Agent 名称。 account_idstring 或 null null用于多 Bot 路由的唯一 Bot 实例标识符。 owner_numberslist of strings []对此 Bot 实例拥有管理权限的手机号列表。 overridesobject （默认值） 每个通道的行为覆盖配置。详见通道行为覆盖 。
[channels.signal][ channels . signal ] api_url = "http://localhost:8080" phone_number = "" allowed_users = [] Copied! 字段 类型 默认值 说明 api_urlstring "http://localhost:8080"signal-cli REST API 的 URL。 phone_numberstring ""Bot 注册的手机号。 allowed_userslist of strings []允许的手机号列表。空列表 = 允许所有。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.matrix][ channels . matrix ] homeserver_url = "https://matrix.org" user_id = "@librefang:matrix.org" access_token_env = "MATRIX_ACCESS_TOKEN" allowed_rooms = [] Copied! 字段 类型 默认值 说明 homeserver_urlstring "https://matrix.org"Matrix 家服务器 URL。 user_idstring ""Bot 用户 ID（例如 "@librefang:matrix.org"）。 access_token_envstring "MATRIX_ACCESS_TOKEN"存放 Matrix 访问令牌的环境变量。 allowed_roomslist of strings []监听的房间 ID 列表。空列表 = 所有已加入的房间。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.email][ channels . email ] imap_host = "imap.gmail.com" imap_port = 993 smtp_host = "smtp.gmail.com" smtp_port = 587 username = "bot@example.com" password_env = "EMAIL_PASSWORD" poll_interval_secs = 30 folders = [ "INBOX" ] allowed_senders = [] Copied! 字段 类型 默认值 说明 imap_hoststring ""IMAP 服务器主机名。 imap_portu16 993IMAP 服务器端口（993 用于 TLS）。 smtp_hoststring ""SMTP 服务器主机名。 smtp_portu16 587SMTP 服务器端口（587 用于 STARTTLS）。 usernamestring ""用于 IMAP 和 SMTP 的邮箱地址。 password_envstring "EMAIL_PASSWORD"存放邮箱密码或应用专用密码的环境变量。 poll_interval_secsu64 30IMAP 轮询间隔（秒）。 folderslist of strings ["INBOX"]监控的 IMAP 文件夹。 allowed_senderslist of strings []仅处理来自这些发件人的邮件。空列表 = 全部处理。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.teams][ channels . teams ] app_id = "" app_password_env = "TEAMS_APP_PASSWORD" webhook_port = 3978 allowed_tenants = [] Copied! 字段 类型 默认值 说明 app_idstring ""Azure Bot 应用 ID。 app_password_envstring "TEAMS_APP_PASSWORD"存放 Azure Bot Framework 应用密码的环境变量。 webhook_portu16 3978Bot Framework 入站 Webhook 端口。 allowed_tenantslist of strings []允许的 Azure AD 租户 ID 列表。空列表 = 允许所有。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.mattermost][ channels . mattermost ] server_url = "https://mattermost.example.com" token_env = "MATTERMOST_TOKEN" allowed_channels = [] Copied! 字段 类型 默认值 说明 server_urlstring ""Mattermost 服务器 URL。 token_envstring "MATTERMOST_TOKEN"存放 Mattermost Bot 令牌的环境变量。 allowed_channelslist of strings []监听的频道 ID 列表。空列表 = 所有频道。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.irc][ channels . irc ] server = "irc.libera.chat" port = 6667 nick = "librefang" # password_env = "IRC_PASSWORD" channels = [ "#librefang" ] use_tls = false Copied! 字段 类型 默认值 说明 serverstring "irc.libera.chat"IRC 服务器主机名。 portu16 6667IRC 服务器端口。 nickstring "librefang"Bot 昵称。 password_envstring 或 null null存放服务器密码的环境变量（可选）。 channelslist of strings []要加入的 IRC 频道（例如 ["#librefang", "#general"]）。 use_tlsbool false是否使用 TLS 连接。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.google_chat][ channels . google_chat ] service_account_env = "GOOGLE_CHAT_SERVICE_ACCOUNT" space_ids = [] webhook_port = 8444 Copied! 字段 类型 默认值 说明 service_account_envstring "GOOGLE_CHAT_SERVICE_ACCOUNT"存放服务账号 JSON 密钥的环境变量。 space_idslist of strings []监听的 Google Chat 聊天室 ID 列表。 webhook_portu16 8444入站 Webhook 端口。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.twitch][ channels . twitch ] oauth_token_env = "TWITCH_OAUTH_TOKEN" channels = [ "mychannel" ] nick = "librefang" Copied! 字段 类型 默认值 说明 oauth_token_envstring "TWITCH_OAUTH_TOKEN"存放 Twitch OAuth 令牌的环境变量。 channelslist of strings []要加入的 Twitch 频道（不带 # 前缀）。 nickstring "librefang"在 Twitch 聊天中的 Bot 昵称。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.rocketchat][ channels . rocketchat ] server_url = "https://rocketchat.example.com" token_env = "ROCKETCHAT_TOKEN" user_id = "" allowed_channels = [] Copied! 字段 类型 默认值 说明 server_urlstring ""Rocket.Chat 服务器 URL。 token_envstring "ROCKETCHAT_TOKEN"存放 Rocket.Chat 认证令牌的环境变量。 user_idstring ""Bot 用户 ID。 allowed_channelslist of strings []监听的频道 ID 列表。空列表 = 所有频道。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.zulip][ channels . zulip ] server_url = "https://zulip.example.com" bot_email = "bot@zulip.example.com" api_key_env = "ZULIP_API_KEY" streams = [] Copied! 字段 类型 默认值 说明 server_urlstring ""Zulip 服务器 URL。 bot_emailstring ""在 Zulip 中注册的 Bot 邮箱地址。 api_key_envstring "ZULIP_API_KEY"存放 Zulip API Key 的环境变量。 streamslist of strings []监听的 Stream 名称列表。空列表 = 所有 Stream。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.xmpp][ channels . xmpp ] jid = "bot@jabber.org" password_env = "XMPP_PASSWORD" server = "" port = 5222 rooms = [] Copied! 字段 类型 默认值 说明 jidstring ""XMPP JID（例如 "bot@jabber.org"）。 password_envstring "XMPP_PASSWORD"存放 XMPP 密码的环境变量。 serverstring ""XMPP 服务器主机名。为空时默认使用 JID 的域名。 portu16 5222XMPP 服务器端口。 roomslist of strings []要加入的 MUC（多人聊天）房间。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.line][ channels . line ] channel_secret_env = "LINE_CHANNEL_SECRET" access_token_env = "LINE_CHANNEL_ACCESS_TOKEN" webhook_port = 8450 Copied! 字段 类型 默认值 说明 channel_secret_envstring "LINE_CHANNEL_SECRET"存放 LINE Channel Secret 的环境变量。 access_token_envstring "LINE_CHANNEL_ACCESS_TOKEN"存放 LINE Channel Access Token 的环境变量。 webhook_portu16 8450入站 Webhook 端口。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.viber][ channels . viber ] auth_token_env = "VIBER_AUTH_TOKEN" webhook_url = "" webhook_port = 8451 Copied! 字段 类型 默认值 说明 auth_token_envstring "VIBER_AUTH_TOKEN"存放 Viber Bot 认证令牌的环境变量。 webhook_urlstring ""Viber Webhook 端点的公网 URL。 webhook_portu16 8451入站 Webhook 端口。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.messenger][ channels . messenger ] page_token_env = "MESSENGER_PAGE_TOKEN" verify_token_env = "MESSENGER_VERIFY_TOKEN" webhook_port = 8452 Copied! 字段 类型 默认值 说明 page_token_envstring "MESSENGER_PAGE_TOKEN"存放 Facebook 页面访问令牌的环境变量。 verify_token_envstring "MESSENGER_VERIFY_TOKEN"存放 Webhook 验证令牌的环境变量。 webhook_portu16 8452入站 Webhook 端口。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.reddit][ channels . reddit ] client_id = "" client_secret_env = "REDDIT_CLIENT_SECRET" username = "" password_env = "REDDIT_PASSWORD" subreddits = [] Copied! 字段 类型 默认值 说明 client_idstring ""Reddit 应用客户端 ID。 client_secret_envstring "REDDIT_CLIENT_SECRET"存放 Reddit 客户端密钥的环境变量。 usernamestring ""Reddit Bot 用户名。 password_envstring "REDDIT_PASSWORD"存放 Reddit Bot 密码的环境变量。 subredditslist of strings []要监控的子版块名称。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.mastodon][ channels . mastodon ] instance_url = "https://mastodon.social" access_token_env = "MASTODON_ACCESS_TOKEN" Copied! 字段 类型 默认值 说明 instance_urlstring ""Mastodon 实例 URL（例如 "https://mastodon.social"）。 access_token_envstring "MASTODON_ACCESS_TOKEN"存放 Mastodon 访问令牌的环境变量。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.bluesky][ channels . bluesky ] identifier = "mybot.bsky.social" app_password_env = "BLUESKY_APP_PASSWORD" service_url = "https://bsky.social" Copied! 字段 类型 默认值 说明 identifierstring ""Bluesky 用户名或 DID。 app_password_envstring "BLUESKY_APP_PASSWORD"存放 Bluesky 应用密码的环境变量。 service_urlstring "https://bsky.social"PDS（个人数据服务器）URL。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.feishu][ channels . feishu ] app_id = "" app_secret_env = "FEISHU_APP_SECRET" webhook_port = 8453 Copied! 字段 类型 默认值 说明 app_idstring ""飞书/Lark 应用 ID。 app_secret_envstring "FEISHU_APP_SECRET"存放飞书应用密钥的环境变量。 webhook_portu16 8453入站 Webhook 端口。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.revolt][ channels . revolt ] bot_token_env = "REVOLT_BOT_TOKEN" api_url = "https://api.revolt.chat" Copied! 字段 类型 默认值 说明 bot_token_envstring "REVOLT_BOT_TOKEN"存放 Revolt Bot 令牌的环境变量。 api_urlstring "https://api.revolt.chat"Revolt API 基础 URL。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.nextcloud][ channels . nextcloud ] server_url = "https://nextcloud.example.com" token_env = "NEXTCLOUD_TOKEN" allowed_rooms = [] Copied! 字段 类型 默认值 说明 server_urlstring ""Nextcloud 服务器 URL。 token_envstring "NEXTCLOUD_TOKEN"存放 Nextcloud Talk 认证令牌的环境变量。 allowed_roomslist of strings []监听的房间令牌列表。空列表 = 所有房间。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.guilded][ channels . guilded ] bot_token_env = "GUILDED_BOT_TOKEN" server_ids = [] Copied! 字段 类型 默认值 说明 bot_token_envstring "GUILDED_BOT_TOKEN"存放 Guilded Bot 令牌的环境变量。 server_idslist of strings []监听的服务器 ID 列表。空列表 = 所有服务器。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.keybase][ channels . keybase ] username = "" paperkey_env = "KEYBASE_PAPERKEY" allowed_teams = [] Copied! 字段 类型 默认值 说明 usernamestring ""Keybase 用户名。 paperkey_envstring "KEYBASE_PAPERKEY"存放 Keybase 纸钥匙的环境变量。 allowed_teamslist of strings []监听的团队名称列表。空列表 = 仅私聊。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.threema][ channels . threema ] threema_id = "" secret_env = "THREEMA_SECRET" webhook_port = 8454 Copied! 字段 类型 默认值 说明 threema_idstring ""Threema Gateway ID。 secret_envstring "THREEMA_SECRET"存放 Threema API 密钥的环境变量。 webhook_portu16 8454入站 Webhook 端口。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.nostr][ channels . nostr ] private_key_env = "NOSTR_PRIVATE_KEY" relays = [ "wss://relay.damus.io" ] Copied! 字段 类型 默认值 说明 private_key_envstring "NOSTR_PRIVATE_KEY"存放 Nostr 私钥（nsec 或十六进制格式）的环境变量。 relayslist of strings ["wss://relay.damus.io"]要连接的 Nostr 中继 WebSocket URL 列表。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.webex][ channels . webex ] bot_token_env = "WEBEX_BOT_TOKEN" allowed_rooms = [] Copied! 字段 类型 默认值 说明 bot_token_envstring "WEBEX_BOT_TOKEN"存放 Webex Bot 令牌的环境变量。 allowed_roomslist of strings []监听的房间 ID 列表。空列表 = 所有房间。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.pumble][ channels . pumble ] bot_token_env = "PUMBLE_BOT_TOKEN" webhook_port = 8455 Copied! 字段 类型 默认值 说明 bot_token_envstring "PUMBLE_BOT_TOKEN"存放 Pumble Bot 令牌的环境变量。 webhook_portu16 8455入站 Webhook 端口。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.flock][ channels . flock ] bot_token_env = "FLOCK_BOT_TOKEN" webhook_port = 8456 Copied! 字段 类型 默认值 说明 bot_token_envstring "FLOCK_BOT_TOKEN"存放 Flock Bot 令牌的环境变量。 webhook_portu16 8456入站 Webhook 端口。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.twist][ channels . twist ] token_env = "TWIST_TOKEN" workspace_id = "" allowed_channels = [] Copied! 字段 类型 默认值 说明 token_envstring "TWIST_TOKEN"存放 Twist API 令牌的环境变量。 workspace_idstring ""Twist 工作区 ID。 allowed_channelslist of strings []监听的频道 ID 列表。空列表 = 所有频道。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.mumble][ channels . mumble ] host = "mumble.example.com" port = 64738 username = "librefang" password_env = "MUMBLE_PASSWORD" channel = "" Copied! 字段 类型 默认值 说明 hoststring ""Mumble 服务器主机名。 portu16 64738Mumble 服务器端口。 usernamestring "librefang"Bot 在 Mumble 中的用户名。 password_envstring "MUMBLE_PASSWORD"存放 Mumble 服务器密码的环境变量。 channelstring ""要加入的 Mumble 频道。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.dingtalk]支持两种模式：stream （默认，推荐）和 webhook （传统）。
# Stream 模式（推荐 — 无需公网 IP） [ channels . dingtalk ] receive_mode = "stream" app_key_env = "DINGTALK_APP_KEY" app_secret_env = "DINGTALK_APP_SECRET" # Webhook 模式（传统） [ channels . dingtalk ] receive_mode = "webhook" access_token_env = "DINGTALK_ACCESS_TOKEN" secret_env = "DINGTALK_SECRET" webhook_port = 8457 Copied! 字段 类型 默认值 说明 receive_modestring "stream"连接模式："stream" 或 "webhook"。 app_key_envstring "DINGTALK_APP_KEY"存放钉钉 App Key 的环境变量（stream 模式）。 app_secret_envstring "DINGTALK_APP_SECRET"存放钉钉 App Secret 的环境变量（stream 模式）。 access_token_envstring "DINGTALK_ACCESS_TOKEN"存放钉钉 Webhook 访问令牌的环境变量（webhook 模式）。 secret_envstring "DINGTALK_SECRET"存放钉钉签名密钥的环境变量（webhook 模式）。 webhook_portu16 8457入站 Webhook 端口（仅 webhook 模式）。 robot_codestring 或 null nullStream 模式回复使用的机器人编码（默认使用 app_key）。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.discourse][ channels . discourse ] base_url = "https://forum.example.com" api_key_env = "DISCOURSE_API_KEY" api_username = "system" categories = [] Copied! 字段 类型 默认值 说明 base_urlstring ""Discourse 论坛基础 URL。 api_key_envstring "DISCOURSE_API_KEY"存放 Discourse API Key 的环境变量。 api_usernamestring "system"Discourse API 用户名。 categorieslist of strings []要监控的分类标识（slug）。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.gitter][ channels . gitter ] token_env = "GITTER_TOKEN" room_id = "" Copied! 字段 类型 默认值 说明 token_envstring "GITTER_TOKEN"存放 Gitter 认证令牌的环境变量。 room_idstring ""监听的 Gitter 房间 ID。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.ntfy][ channels . ntfy ] server_url = "https://ntfy.sh" topic = "my-agent-topic" token_env = "NTFY_TOKEN" Copied! 字段 类型 默认值 说明 server_urlstring "https://ntfy.sh"ntfy 服务器 URL。支持自托管。 topicstring ""要订阅/发布的主题。 token_envstring "NTFY_TOKEN"存放认证令牌的环境变量。公共主题可选。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.gotify][ channels . gotify ] server_url = "https://gotify.example.com" app_token_env = "GOTIFY_APP_TOKEN" client_token_env = "GOTIFY_CLIENT_TOKEN" Copied! 字段 类型 默认值 说明 server_urlstring ""Gotify 服务器 URL。 app_token_envstring "GOTIFY_APP_TOKEN"存放 Gotify 应用令牌（用于发送消息）的环境变量。 client_token_envstring "GOTIFY_CLIENT_TOKEN"存放 Gotify 客户端令牌（通过 WebSocket 接收消息）的环境变量。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.webhook][ channels . webhook ] secret_env = "WEBHOOK_SECRET" listen_port = 8460 # callback_url = "https://example.com/webhook" Copied! 字段 类型 默认值 说明 secret_envstring "WEBHOOK_SECRET"存放用于验证入站 Webhook 的 HMAC 签名密钥的环境变量。 listen_portu16 8460监听入站 Webhook 请求的端口。 callback_urlstring 或 null null发送出站消息的 POST 目标 URL。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.linkedin][ channels . linkedin ] access_token_env = "LINKEDIN_ACCESS_TOKEN" organization_id = "" Copied! 字段 类型 默认值 说明 access_token_envstring "LINKEDIN_ACCESS_TOKEN"存放 LinkedIn OAuth2 访问令牌的环境变量。 organization_idstring ""LinkedIn 组织 ID，用于消息收发。 default_agentstring 或 null null消息路由的目标 Agent 名称。
[channels.qq]使用 QQ 机器人开放平台官方 API 的 QQ Bot 通道适配器。
[ channels . qq ] app_id = "your-app-id" app_secret_env = "QQ_BOT_APP_SECRET" allowed_users = [] # default_agent = "assistant" # account_id = "my-qq-bot" Copied! 字段 类型 默认值 说明 app_idstring ""在 QQ 开放平台注册的 QQ Bot 应用 ID。 app_secret_envstring "QQ_BOT_APP_SECRET"存放 QQ Bot 应用密钥的环境变量。实际密钥绝不存储在配置中。 allowed_userslist of strings []允许交互的 QQ 用户 ID 列表。空列表 = 允许所有。 default_agentstring 或 null null消息路由的目标 Agent 名称。 account_idstring 或 null null用于多 Bot 路由的唯一 Bot 实例标识符。 overridesobject （默认值） 每个通道的行为覆盖配置。详见通道行为覆盖 。
[channels.wecom]企业微信（WeCom）智能机器人通道适配器。通过 WebSocket 连接到 wss://openws.work.weixin.qq.com。
[ channels . wecom ] bot_id = "YOUR_BOT_ID" secret_env = "WECOM_BOT_SECRET" # account_id = "my-wecom-bot" # default_agent = "assistant" Copied! 字段 类型 默认值 说明 bot_idstring ""企业微信管理后台的智能机器人 Bot ID。 secret_envstring "WECOM_BOT_SECRET"存放机器人密钥的环境变量。 account_idstring 或 null null用于多 Bot 路由的唯一 Bot 实例标识符。 default_agentstring 或 null null消息路由的目标 Agent 名称。 overridesobject （默认值） 每个通道的行为覆盖配置。详见通道行为覆盖 。
[channels.wechat]微信个人账号通道适配器，使用腾讯的 iLink Bot API。通过扫码登录连接，无需 API Key 或开发者账号。
[ channels . wechat ] # bot_token_env = "WECHAT_BOT_TOKEN" # 可选：上次会话的持久化令牌 allowed_users = [] # default_agent = "assistant" # account_id = "my-wechat-bot" Copied! 字段 类型 默认值 说明 bot_token_envstring "WECHAT_BOT_TOKEN"存放上次二维码登录会话持久化令牌的环境变量。设置后可在重启时跳过二维码登录。 allowed_userslist of strings []允许交互的微信用户 ID（格式：hash@im.wechat）。空列表 = 允许所有。 default_agentstring 或 null null消息路由的目标 Agent 名称。 account_idstring 或 null null用于多 Bot 路由的唯一 Bot 实例标识符。 overridesobject （默认值） 每个通道的行为覆盖配置。详见通道行为覆盖 。
[[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" ] Copied! [[ mcp_servers ]] name = "remote-api" timeout_secs = 60 env = [ "GITHUB_PERSONAL_ACCESS_TOKEN" ] [ mcp_servers . transport ] type = "sse" url = "https://mcp.example.com/sse" Copied! [[ 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" Copied! 字段 类型 默认值 说明 namestring 必填 MCP 服务器的显示名称。工具以 mcp_{name}_{tool} 的命名空间注册。 timeout_secsu64 30请求超时时间（秒）。 envlist of strings []传递给子进程的环境变量名称（仅 stdio 传输方式）。
传输方式变体 （基于 type 的标记联合体）：
type字段 说明 stdiocommand（string）、args（list of strings，默认 []）启动子进程，通过 stdin/stdout 上的 JSON-RPC 通信。 sseurl（string）连接到 HTTP Server-Sent Events 端点。 http_compatbase_url（string）、headers（header 配置列表）、tools（工具配置列表）内置兼容适配器，用于没有原生 MCP 服务器的纯 HTTP/JSON 工具后端。每个工具映射到一个 HTTP 端点。
http_compat header 配置：
字段 类型 说明 namestring HTTP 请求头名称（例如 "Authorization"）。 valuestring 或 null 静态请求头值。 value_envstring 或 null 用作请求头值的环境变量名称（密钥推荐使用此方式）。
http_compat 工具配置：
字段 类型 默认值 说明 namestring 必填 暴露给 LLM 的工具名称。 descriptionstring ""展示给 LLM 的工具描述。 pathstring 必填 HTTP 路径（例如 "/search"）。 methodstring "post"HTTP 方法：get、post、put、patch、delete。 request_modestring "json_body"参数发送方式：json_body、query、none。 response_modestring "json"响应解析方式：json、text。 input_schemaobject {"type":"object"}工具输入参数的 JSON Schema。
[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" Copied! 字段 类型 默认值 说明 enabledbool false是否启用 A2A 协议。 namestring "LibreFang Agent OS"在 well-known Agent 名片中展示的服务级显示名称。 descriptionstring ""在 well-known Agent 名片中展示的服务级描述。 listen_pathstring "/a2a"A2A 端点的 URL 路径前缀。 external_agentslist of objects []要发现和交互的外部 A2A Agent 列表。
external_agents 条目：
字段 类型 说明 namestring 外部 Agent 的显示名称。 urlstring Agent 名片端点 URL（通常为 /.well-known/agent.json）。
[[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" Copied! 字段 类型 默认值 说明 providerstring ""提供商名称（例如 "ollama"、"groq"、"openai"）。 modelstring ""该提供商的模型标识符。 api_key_envstring ""API Key 的环境变量名称。本地提供商（ollama、vllm、lmstudio）留空。 base_urlstring 或 null null基础 URL 覆盖。为 null 时使用模型目录默认值。
[[users]]RBAC 多用户配置。用户可以被分配角色，并绑定到各通道平台的身份标识。
[[ users ]] name = "Alice" role = "owner" api_key_hash = "sha256_hash_of_api_key" [ users . channel_bindings ] telegram = "123456" discord = "987654321" slack = "U0ABCDEFG" Copied! 字段 类型 默认值 说明 namestring 必填 用户显示名称。 rolestring "user"用户在 RBAC 层级中的角色。 channel_bindingsmap of string to string {}将通道平台名称映射到平台特定用户 ID，实现跨通道的用户身份绑定。 api_key_hashstring 或 null null用户个人 API Key 的 SHA256 哈希值，用于认证 API 访问。
角色层级 （从最高到最低权限）：
角色 说明 owner完全管理权限。可以管理所有 Agent、用户和配置。 admin可以管理 Agent 和大多数设置。无法修改 owner 账户。 user可以与 Agent 交互。管理能力有限。 viewer只读访问。可以查看 Agent 回复，但无法发送消息。
通道行为覆盖
每个通道适配器都支持 [channels.<name>.overrides] 子表，用于按通道自定义 Agent 行为。
[ channels . telegram . overrides ] model = "claude-haiku-4-5-20251001" system_prompt = "You are a concise Telegram assistant." dm_policy = "respond" group_policy = "mention_only" rate_limit_per_minute = 0 rate_limit_per_user = 10 threading = true output_format = "telegram_html" usage_footer = "tokens" typing_mode = "instant" disable_commands = false allowed_commands = [] blocked_commands = [] Copied! 字段 类型 默认值 说明 modelstring 或 null null该通道的模型覆盖。为 null 时使用 Agent 的默认模型。 system_promptstring 或 null null该通道的系统提示词覆盖。 dm_policystring "respond"Bot 处理私聊消息的方式。见下表。 group_policystring "mention_only"Bot 处理群组消息的方式。见下表。 rate_limit_per_minuteu32 0该通道的全局速率限制（每分钟消息数）。0 = 无限制。 rate_limit_per_useru32 0每个用户每分钟的最大消息数。0 = 无限制。 threadingbool false启用线程回复（在支持的平台上）。 output_formatstring 或 null null覆盖输出格式。见下表。 usage_footerstring 或 null null覆盖该通道的用量页脚模式。可选值：off、tokens、cost、full。 typing_modestring 或 null null输入状态指示器行为。见下表。默认为 instant。 disable_commandsbool false关闭该通道所有内置斜杠命令。被拦截的命令作为普通文本转发给 Agent。 allowed_commandslist of strings []命令名白名单（不带 /）。非空时仅这些命令可用，其他命令转发给 Agent。 blocked_commandslist of strings []命令名黑名单（不带 /）。仅在 allowed_commands 为空时生效。
dm_policy 值说明：
值 说明 respond回复所有私聊消息（默认）。 allowed_only仅回复允许列表中用户的私聊消息。 ignore忽略所有私聊消息。
group_policy 值说明：
值 说明 all回复群聊中的所有消息。 mention_only仅在被 @ 提及时回复（默认）。 commands_only仅回复斜杠命令。 ignore忽略所有群组消息。
output_format 值说明：
值 说明 markdown标准 Markdown（默认）。 telegram_htmlTelegram HTML 子集（<b>、<i>、<code> 等）。 slack_mrkdwnSlack mrkdwn 格式（*bold*、_italic_、`code`）。 plain_text无格式标记。
typing_mode 值说明：
值 说明 instant收到消息后立即发送输入状态指示（默认）。 message仅在 LLM 返回第一个文本增量时发送输入状态指示。 thinking仅在 LLM 推理/思考阶段发送输入状态指示。 never从不发送输入状态指示。
[browser]配置 Agent 工具 browser_* 使用的无头浏览器自动化引擎。
[ browser ] headless = true viewport_width = 1280 viewport_height = 720 timeout_secs = 30 idle_timeout_secs = 300 max_sessions = 5 # chromium_path = "/usr/bin/chromium" Copied! 字段 类型 默认值 说明 headlessbool true以无头模式运行浏览器（不显示窗口）。 viewport_widthu32 1280浏览器视口宽度（像素）。 viewport_heightu32 720浏览器视口高度（像素）。 timeout_secsu64 30每个操作的超时时间（秒）。 idle_timeout_secsu64 300浏览器会话闲置超过此秒数后自动关闭。 max_sessionsusize 5最大并发浏览器会话数。 chromium_pathstring 或 null nullChromium/Chrome 二进制文件路径。为 null 时自动检测。
[reload]控制配置文件的自动监控和热重载。
[ reload ] mode = "hybrid" debounce_ms = 500 Copied! 字段 类型 默认值 说明 modestring "hybrid"重载模式。见下表。 debounce_msu64 500检测到文件变更后，重载前的防抖窗口时长（毫秒）。
mode 值说明：
值 说明 off不自动重载。更改需手动重启。 restart任何配置变更都进行完整守护进程重启。 hot仅对安全的部分进行热重载（通道、技能、心跳）。 hybrid尽可能热重载；对需要重启的部分标记提示（默认）。
[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 Copied! 字段 类型 默认值 说明 modestring "allowlist"安全模式。见下表。 safe_binslist of strings ["sleep","true","false","cat","sort","uniq","cut","tr","head","tail","wc","date","echo","printf","basename","dirname","pwd","env"]始终绕过白名单检查的命令（仅标准输入的 POSIX 工具）。 allowed_commandslist of strings []当 mode = "allowlist" 时额外允许的命令。 timeout_secsu64 30每条命令的最大挂钟执行时间（秒）。 max_output_bytesusize 102400stdout+stderr 合并输出的最大大小（字节）。默认 100 KB。 no_output_timeout_secsu64 30进程在此秒数内无输出则被终止。0 = 禁用。
mode 值说明：
值 别名 说明 denynone、disabled阻止所有 Shell 执行。 allowlistrestricted仅允许 safe_bins 或 allowed_commands 中的命令（默认）。 fullallow、all、unrestricted允许所有命令。不安全——仅限开发使用。
[approval]配置哪些工具在执行前需要明确的人工批准。引用 ApprovalPolicy 类型。
[ approval ] require_approval = [ "shell_exec" ] timeout_secs = 60 auto_approve_autonomous = false auto_approve = false Copied! 字段 类型 默认值 说明 require_approvallist of strings ["shell_exec"]需要暂停执行并等待人工批准的工具名称列表。 timeout_secsu64 60审批请求的超时时间（秒）。 auto_approve_autonomousbool falseAgent 处于自主模式时自动批准工具执行。 auto_approvebool false自动批准所有工具执行（不安全，仅限开发使用）。
[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 Copied! 字段 类型 默认值 说明 max_hourly_usdf64 0.0所有 Agent 每小时的最大 LLM 费用（美元）。0.0 = 无限制。 max_daily_usdf64 0.0所有 Agent 每天的最大 LLM 费用（美元）。0.0 = 无限制。 max_monthly_usdf64 0.0所有 Agent 每月的最大 LLM 费用（美元）。0.0 = 无限制。 alert_thresholdf64 0.8各限额的告警阈值（0.0-1.0 的比例）。设为 0.8 时，达到限额 80% 即记录告警日志。 default_max_llm_tokens_per_houru64 0全局覆盖每个 Agent 的每小时 Token 预算。大于 0 时覆盖所有 Agent 自身的 Token 限制。0 = 保持各 Agent 自身的限制。
[thinking]配置支持扩展思维（思维链推理）的模型（例如启用了 thinking 模式的 Claude 3.7 Sonnet）。
[ thinking ] budget_tokens = 10000 stream_thinking = false Copied! 字段 类型 默认值 说明 budget_tokensu32 10000分配给思维/推理阶段的最大 Token 数。 stream_thinkingbool false是否将思维 Token 流式传输给客户端（在 API 响应流中可见）。
[tts]配置语音合成（Text-to-Speech）功能。
[ tts ] enabled = false provider = "openai" # openai | elevenlabs 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 Copied! [tts] 字段：
字段 类型 默认值 说明 enabledbool false启用 TTS 合成。 providerstring 或 null null默认 TTS 提供商："openai" 或 "elevenlabs"。 max_text_lengthusize 4096单次 TTS 请求的最大文本长度（字符数）。 timeout_secsu64 30每次 TTS 调用的请求超时时间（秒）。
[tts.openai] 字段：
字段 类型 默认值 说明 voicestring "alloy"语音名称。可选：alloy、echo、fable、onyx、nova、shimmer。 modelstring "tts-1"TTS 模型："tts-1"（快速）或 "tts-1-hd"（高质量）。 formatstring "mp3"输出格式：mp3、opus、aac、flac。 speedf32 1.0语速倍率（0.25 到 4.0）。
[tts.elevenlabs] 字段：
字段 类型 默认值 说明 voice_idstring "21m00Tcm4TlvDq8ikWAM"ElevenLabs 语音 ID（默认：Rachel）。 model_idstring "eleven_monolingual_v1"ElevenLabs 模型 ID。 stabilityf32 0.5语音稳定性（0.0-1.0）。越高越稳定，但表现力越低。 similarity_boostf32 0.75语音相似度增强（0.0-1.0）。
[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 = [] Copied! 字段 类型 默认值 说明 enabledbool false启用 Docker 沙箱用于代码执行。 imagestring "python:3.12-slim"沙箱容器使用的 Docker 镜像。 container_prefixstring "librefang-sandbox"容器名称前缀。 workdirstring "/workspace"容器内的工作目录。 networkstring "none"网络模式："none"（隔离）、"bridge" 或自定义网络名称。 memory_limitstring "512m"内存限制（例如 "256m"、"1g"）。 cpu_limitf64 1.0CPU 限制（例如 0.5、1.0、2.0）。 timeout_secsu64 60每条命令的最大执行时间（秒）。 read_only_rootbool true将根文件系统挂载为只读。 modestring "off"激活模式。见下表。 scopestring "session"容器生命周期范围。见下表。 reuse_cool_secsu64 300释放的容器在此秒数冷却后才可重用。 idle_timeout_secsu64 86400容器闲置超过此秒数后被销毁（默认 24 小时）。 max_age_secsu64 604800容器最大存活时间，超时后强制销毁（默认 7 天）。 blocked_mountslist of strings []禁止绑定挂载到容器的宿主机路径。 cap_addlist of strings []添加到容器的 Linux 能力（例如 ["NET_ADMIN"]）。请谨慎使用。 tmpfslist of strings ["/tmp:size=64m"]容器内的 tmpfs 挂载。每个条目格式为 "path:options"（例如 "/tmp:size=128m"）。 pids_limitu32 100容器内的最大进程数。防止 Fork 炸弹。
mode 值说明：
值 说明 off禁用 Docker 沙箱（默认）。 non_main仅对非主（子）Agent 使用 Docker。 all对所有 Agent 使用 Docker。
scope 值说明：
值 说明 session每个会话一个容器，会话结束时销毁（默认）。 agent每个 Agent 一个容器，跨会话重用。 shared所有 Agent 共享容器池。
[canvas]配置 Canvas（Agent 到 UI）工具，允许 Agent 在仪表盘中渲染 HTML。
[ canvas ] enabled = false max_html_bytes = 524288 allowed_tags = [] Copied! 字段 类型 默认值 说明 enabledbool false启用 Canvas 工具。 max_html_bytesusize 524288HTML 负载的最大大小（字节）。默认 512 KB。 allowed_tagslist of strings []用于净化的允许 HTML 标签名称。空列表 = 允许所有安全标签。
[auto_reply]配置后台自动回复引擎，可以在无需人工交互的情况下自动回复传入消息。
[ auto_reply ] enabled = false max_concurrent = 3 timeout_secs = 120 suppress_patterns = [ "/stop" , "/pause" ] Copied! 字段 类型 默认值 说明 enabledbool false启用自动回复引擎。 max_concurrentusize 3最大并发自动回复任务数。 timeout_secsu64 120每个自动回复任务的默认超时时间（秒）。 suppress_patternslist of strings ["/stop", "/pause"]抑制自动回复的传入消息匹配模式。
[broadcast]配置消息广播，将单条传入消息同时路由到多个 Agent。
[ broadcast ] strategy = "parallel" routes = { "announcement-channel" = [ "agent-a" , "agent-b" , "agent-c" ] } Copied! 字段 类型 默认值 说明 strategystring "parallel"投递策略。"parallel" = 同时发送给所有 Agent；"sequential" = 按顺序逐个发送。 routesmap of string to list of strings {}将对等方/通道标识符映射到接收消息的 Agent 名称列表。
[inbox]基于文件的异步外部命令输入收件箱。将文本文件放入监控目录后，文件内容会作为消息分发给 Agent。已处理的文件会被移动到 processed/ 子目录以避免重复投递。
[ inbox ] enabled = true directory = "~/.librefang/inbox/" poll_interval_secs = 5 default_agent = "assistant" Copied! 字段 类型 默认值 说明 enabledbool false启用收件箱目录监控。 directorystring 或 null null监控的目录。默认为 $HOME_DIR/inbox/。支持 ~ 展开。 poll_interval_secsu64 5扫描目录新文件的间隔（秒）。最小值 1。 default_agentstring 或 null null文件中未找到 agent: 指令时路由到的 Agent 名称。
文件格式： 纯文本文件（.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 Copied! 发送到默认 Agent：
echo "Summarize today's system logs" > ~/.librefang/inbox/summarize.txt Copied! 定时任务：
# crontab -e 0 9 * * * grep ERROR /var/log/app.log > ~/.librefang/inbox/daily_errors.txt Copied! CI/CD 构建后处理：
echo "agent:devops Build failed, please analyze: $( tail -100 build.log)" > ~/.librefang/inbox/build_ $( date +%s ) .txt Copied! 批量处理：
for doc in ~/reports/*.md ; do cp " $doc " ~/.librefang/inbox/ done Copied! 检查收件箱状态：
curl -s http://127.0.0.1:4545/api/inbox/status # {"enabled":true,"pending_count":3,"processed_count":12,...} Copied! [[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" ] Copied! 顶层字段：
字段 类型 说明 agentstring 匹配的消息路由到的目标 Agent 名称或 ID。 match_ruleobject 匹配条件。所有指定的（非空）字段必须全部匹配。
match_rule 字段：
字段 类型 默认值 说明 channelstring 或 null null要匹配的通道类型（例如 "discord"、"telegram"、"slack"）。 account_idstring 或 null null通道内特定的 Bot 账号 ID（用于多 Bot 场景）。 peer_idstring 或 null null用于私聊路由的用户/对等方 ID。 guild_idstring 或 null null服务器/Guild ID（Discord/Slack）。 roleslist of strings []基于角色的路由；用户必须拥有其中至少一个角色。
具体度评分 （分值越高越先匹配）：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" Copied! 字段 类型 默认值 说明 enabledbool false启用设备配对。 max_devicesusize 10最大配对设备数。 token_expiry_secsu64 300配对令牌有效期（秒）。默认 5 分钟。 push_providerstring "none"推送通知提供商："none"、"ntfy" 或 "gotify"。 ntfy_urlstring 或 null nullntfy 服务器 URL（当 push_provider = "ntfy" 时使用）。 ntfy_topicstring 或 null null推送通知的 ntfy 主题。
[extensions]配置 MCP 服务器的重连行为和健康监控。
[ extensions ] auto_reconnect = true reconnect_max_attempts = 10 reconnect_max_backoff_secs = 300 health_check_interval_secs = 60 Copied! 字段 类型 默认值 说明 auto_reconnectbool trueMCP 服务器断开连接时自动重连。 reconnect_max_attemptsu32 10放弃前的最大重连尝试次数。 reconnect_max_backoff_secsu64 300重连尝试之间的最大退避时间（秒）。 health_check_interval_secsu64 60已连接扩展的健康检查间隔（秒）。
[vault]配置用于存储敏感密钥的加密凭据库。
[ vault ] enabled = true # path = "~/.librefang/vault.enc" Copied! 字段 类型 默认值 说明 enabledbool true启用凭据库。如果 vault.enc 已存在则自动检测。 pathpath 或 null null自定义凭据库文件路径。默认为 ~/.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 Copied! 字段 类型 默认值 说明 enabledbool false启用 Webhook 触发器端点。 token_envstring "LIBREFANG_WEBHOOK_TOKEN"存放 Bearer 令牌的环境变量名称（不是令牌本身）。令牌长度必须大于等于 32 个字符。enabled = true 时必填。 max_payload_bytesusize 65536入站负载的最大大小（字节）。默认 64 KB。 rate_limit_per_minuteu32 30每个来源 IP 每分钟的最大 Webhook 请求数。
[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" Copied! 字段 类型 默认值 说明 http_proxystring 或 null nullHTTP 代理 URL。回退到 HTTP_PROXY / http_proxy 环境变量。URL 中的凭据在日志中会被脱敏。 https_proxystring 或 null nullHTTPS 代理 URL。回退到 HTTPS_PROXY / https_proxy 环境变量。 no_proxystring 或 null null绕过代理的主机/域名逗号分隔列表。回退到 NO_PROXY / no_proxy 环境变量。
[[sidecar_channels]]Sidecar 通道适配器允许外部进程（使用任何编程语言编写）充当通道适配器。通过 stdin/stdout 上的换行分隔 JSON 进行通信。
[[ sidecar_channels ]] name = "my-custom-channel" command = "python3" args = [ "adapters/my_adapter.py" ] channel_type = "custom_platform" [ sidecar_channels . env ] MY_API_TOKEN = "secret" Copied! 字段 类型 默认值 说明 namestring 必填 此适配器的显示名称。 commandstring 必填 要运行的可执行文件（例如 "python3"、"/usr/local/bin/my-adapter"）。 argslist of strings []传递给命令的参数。 envmap of string to string {}传递给子进程的额外环境变量。 channel_typestring 或 null null通道类型标识符。为 null 时默认为 Custom(<name>)。
[session]配置空闲或多余会话的自动清理。
[ session ] retention_days = 30 max_sessions_per_agent = 100 cleanup_interval_hours = 24 Copied! 字段 类型 默认值 说明 retention_daysu32 0空闲会话在自动清理前的最大保留天数。0 = 无限制。 max_sessions_per_agentu32 0每个 Agent 的最大会话数（最旧的优先清理）。0 = 无限制。 cleanup_interval_hoursu32 24后台清理任务的运行间隔（小时）。
[terminal]配置交互式终端 WebSocket 端点的访问控制。
[ terminal ] enabled = true allow_remote = false allowed_origins = [ "https://dashboard.example.com" ] tmux_enabled = true max_windows = 16 # tmux_binary_path = "/usr/local/bin/tmux" Copied! 字段 类型 默认值 说明 enabledbool true终端功能总开关。设为 false 时，终端 WebSocket 端点会被完全禁用。 allow_remotebool false允许来自远程或反向代理的连接。当未配置认证时，还必须同时将 allow_unauthenticated_remote 设为 true，否则连接会被拒绝。默认行为是仅允许本地无认证访问。 allow_unauthenticated_remotebool false强制防呆开关。当 allow_remote = true 且未配置任何认证时，必须显式将本项设为 true 才能对外暴露未认证的 shell；否则即使 allow_remote = true，此类连接也会被拒绝。 allowed_originslist of strings []除 localhost 之外，允许用于终端 WebSocket 连接的额外浏览器 Origin 列表。适用于 dashboard 部署在自定义域名下的情况。["*"] 表示允许任意 HTTP/HTTPS origin，应仅在明确知情的情况下使用。 require_proxy_headersbool false当为 true 时，没有代理头（X-Forwarded-For、X-Real-IP）的环回连接将被拒绝。仅在使用注入这些头的反向代理时启用。（旧名：trust_proxy_headers，仍作为别名兼容。） tmux_enabledbool true启用基于 tmux 的多窗口终端。仅当系统上存在 tmux 二进制文件时生效。 max_windowsu32 16最大同时存在的 tmux 窗口数量。用于防止资源耗尽。 tmux_binary_pathstring 或 null nulltmux 二进制文件的显式路径。如果为 null，则通过 PATH 解析。
说明：
对于非浏览器客户端，缺少 Origin 头是允许的。
allow_remote = true 不会关闭认证；如果已配置 API Key 或 dashboard 凭据，远程客户端仍然需要提供有效认证。对浏览器访问，优先使用明确的 HTTPS origin，而不是 "*"。
[rate_limit] 中的 ws_terminal_messages_per_minute（默认值：3600）控制交互式终端会话的每连接 WebSocket 消息吞吐量。
[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 Copied! [queue] 字段：
字段 类型 默认值 说明 max_depth_per_agentu32 0每个 Agent 的最大排队任务数。队列满时新任务被拒绝。0 = 无限制。 max_depth_globalu32 0所有 Agent 的最大排队任务总数。0 = 无限制。 task_ttl_secsu64 3600未处理的任务在此秒数后过期。0 = 无限制。
[queue.concurrency] 字段：
字段 类型 默认值 说明 main_laneusize 3并发用户消息任务数。 cron_laneusize 2并发定时任务数。 subagent_laneusize 3并发子 Agent 调用任务数。
[external_auth]配置 OAuth2/OIDC 外部认证，允许用户通过 Google、GitHub、Okta、Auth0 或 Keycloak 等身份提供商登录。
[ external_auth ] enabled = true issuer_url = "https://accounts.google.com" client_id = "your-client-id.apps.googleusercontent.com" client_secret_env = "LIBREFANG_OAUTH_CLIENT_SECRET" redirect_url = "http://127.0.0.1:4545/api/auth/callback" scopes = [ "openid" , "profile" , "email" ] allowed_domains = [ "example.com" ] session_ttl_secs = 86400 Copied! 字段 类型 默认值 说明 enabledbool false启用外部认证。 issuer_urlstring ""OIDC 发行者 URL，用于在 {issuer_url}/.well-known/openid-configuration 进行提供商发现。 client_idstring ""在身份提供商注册的 OAuth2 客户端 ID。 client_secret_envstring "LIBREFANG_OAUTH_CLIENT_SECRET"存放 OAuth2 客户端密钥的环境变量名称。 redirect_urlstring "http://127.0.0.1:4545/api/auth/callback"OAuth2 授权码流程的回调 URL。 scopeslist of strings ["openid","profile","email"]请求的 OAuth2 权限范围。 allowed_domainslist of strings []限制登录到这些邮箱域名。空列表 = 允许所有。 audiencestring ""要验证的 JWT audience 声明。为空时默认使用 client_id。 session_ttl_secsu64 86400会话令牌有效期（秒）。默认 24 小时。 providerslist of objects []多个 OIDC/OAuth2 提供商。配置后优先于上述单提供商字段。
对于多提供商配置，使用 [[external_auth.providers]]，支持以下字段：id、display_name、issuer_url、auth_url、token_url、userinfo_url、jwks_uri、client_id、client_secret_env、redirect_url、scopes、allowed_domains、audience。
[vertex_ai]配置 Google Cloud Vertex AI 作为 LLM 提供商。
[ vertex_ai ] project_id = "my-gcp-project" region = "us-central1" credentials_path = "/path/to/service-account.json" Copied! 凭据按以下顺序解析：
配置中的 credentials_path（JSON 字符串或文件路径）
VERTEX_AI_SERVICE_ACCOUNT_JSON 环境变量GOOGLE_APPLICATION_CREDENTIALS 环境变量（文件路径）gcloud auth print-access-token CLI 后备
字段 类型 默认值 说明 project_idstring 或 null nullGCP 项目 ID。回退到 VERTEX_AI_PROJECT_ID、GOOGLE_CLOUD_PROJECT，或服务账号 JSON 中的 project_id 字段。 regionstring 或 null nullVertex AI 端点的 GCP 区域。回退到 VERTEX_AI_REGION 或 GOOGLE_CLOUD_REGION 环境变量。默认："us-central1"。 credentials_pathstring 或 null nullGCP 服务账号 JSON 密钥文件的路径，或原始 JSON 字符串。
[oauth]配置仪表盘使用的 PKCE（Proof Key for Code Exchange）流程的 OAuth 客户端 ID。
[ oauth ] google_client_id = "your-google-client-id.apps.googleusercontent.com" github_client_id = "your-github-app-client-id" microsoft_client_id = "your-azure-app-client-id" slack_client_id = "your-slack-app-client-id" Copied! 字段 类型 默认值 说明 google_client_idstring 或 null null用于 PKCE 流程的 Google OAuth2 客户端 ID。 github_client_idstring 或 null null用于 PKCE 流程的 GitHub OAuth 应用客户端 ID。 microsoft_client_idstring 或 null nullMicrosoft（Entra ID / Azure AD）OAuth 应用客户端 ID。 slack_client_idstring 或 null nullSlack OAuth 应用客户端 ID。
[auth_profiles]为每个提供商配置多个 API Key 配置文件，以实现当某个 Key 被限速或用尽时的轮换。
[ auth_profiles ] anthropic = [ {name = "primary" , api_key_env = "ANTHROPIC_API_KEY_1" , priority = 0 }, {name = "secondary" , api_key_env = "ANTHROPIC_API_KEY_2" , priority = 1 }, ] openai = [ {name = "main" , api_key_env = "OPENAI_API_KEY" , priority = 0 }, ] Copied! 值是从提供商名称到 AuthProfile 对象列表的映射：
字段 类型 默认值 说明 namestring 必填 配置文件名称（例如 "primary"、"secondary"）。 api_key_envstring 必填 存放该配置文件 API Key 的环境变量名称。 priorityu32 0Key 选择优先级。值越小越优先。
配置全局工具访问规则、分组和递归深度限制。引用 ToolPolicy 类型。
[ tool_policy ] subagent_max_depth = 10 subagent_max_concurrent = 5 [[ tool_policy . global_rules ]] pattern = "shell_*" effect = "deny" [[ tool_policy . groups ]] name = "web_tools" tools = [ "web_search" , "web_fetch" ] Copied! 字段 类型 默认值 说明 agent_ruleslist of ToolPolicyRule []每个 Agent 的工具规则（最高优先级，最先检查）。 global_ruleslist of ToolPolicyRule []应用于所有 Agent 的全局工具规则（在 agent 规则之后检查）。 groupslist of ToolGroup []命名工具组，便于在规则中重用。 subagent_max_depthu32 10子 Agent 最大生成深度。 subagent_max_concurrentu32 5最大并发子 Agent 数。
ToolPolicyRule 字段：
字段 类型 说明 patternstring 匹配工具名称的 Glob 模式（例如 "shell_*"、"web_*"、"mcp_github_*"）。 effectstring "allow" 或 "deny"。拒绝优先：只要有任何 deny 规则匹配，该工具就会被阻止，无论是否有 allow 规则。
ToolGroup 字段：
字段 类型 说明 namestring 组名（例如 "web_tools"、"code_tools"）。 toolslist of strings 包含在该组中的工具名称模式。
配置每个工具的执行超时时间。全局默认超时适用于所有工具，除非被精确名称或 glob 模式覆盖。
# 所有工具的全局默认超时（秒） tool_timeout_secs = 300 # 每个工具的超时覆盖（精确匹配或 glob 模式） [ tool_timeouts ] agent_send = 600 agent_spawn = 600 "mcp_browser_*" = 900 shell_exec = 300 Copied! 字段 类型 默认值 说明 tool_timeout_secsu64 300所有工具执行的全局超时（秒）。对于浏览器自动化或长时间运行的构建，请增加此值。 tool_timeoutsmap of string->u64 {}每个工具的超时覆盖。键是精确的工具名称或 glob 模式（例如 "mcp_browser_*"）。精确匹配优先于 glob 模式；在多个 glob 模式中，最长的匹配模式获胜（最具体的优先）。当没有匹配项时，回退到 tool_timeout_secs。
解析顺序：
tool_timeouts 中的精确工具名称匹配tool_timeouts 中最长的匹配 glob 模式全局 tool_timeout_secs
[proactive_memory]配置主动记忆提取（mem0 风格的自动记忆管理）。引用 ProactiveMemoryConfig 类型。
[ proactive_memory ] enabled = true auto_memorize = true auto_retrieve = true max_retrieve = 10 extraction_threshold = 0.7 # extraction_model = "gpt-4o-mini" # 使用默认提供商 # extraction_model = "anthropic/claude-haiku-4" # 指定特定提供商 # extraction_model = "anthropic:claude-haiku-4" # 冒号格式也可用 extract_categories = [ "user_preference" , "important_fact" , "task_context" , "relationship" ] session_ttl_hours = 24 duplicate_threshold = 0.5 confidence_decay_rate = 0.01 max_memories_per_agent = 1000 Copied! 字段 类型 默认值 说明 enabledbool true主开关——为 false 时整个主动记忆子系统被禁用。 auto_memorizebool true每次 Agent 执行后自动提取并存储记忆。 auto_retrievebool true每次 Agent 执行前自动检索相关记忆。 max_retrieveusize 10每次查询检索的最大记忆数。 extraction_thresholdf32 0.7近似重复检测的置信度阈值（0.0-1.0）。 extraction_modelstring 或 null null用于提取的 LLM 模型。支持 提供商/模型 格式（如 "anthropic/claude-haiku-4"）、提供商:模型 格式，或裸模型名（使用默认提供商）。为 null 时使用基于规则的提取。没有单独的 extraction_provider 字段。 extract_categorieslist of strings ["user_preference", "important_fact", "task_context", "relationship"]从对话中提取的类别。 session_ttl_hoursu32 24会话记忆的 TTL（小时）。超过此时间的记忆在每次 Agent 执行前被清理。 duplicate_thresholdf32 0.5重复检测的相似度阈值（0.0-1.0）。有嵌入向量时使用余弦相似度，否则回退到 Jaccard 词重叠。 confidence_decay_ratef64 0.01每天的置信度衰减率。遵循指数衰减：conf x e^(-rate x days)。默认 0.01 约 70 天减半。 max_memories_per_agentusize 1000每个 Agent 的最大记忆数。超出时淘汰最旧/置信度最低的条目。0 = 无上限。
[context_engine]配置可插拔的上下文组装引擎，控制 Agent 记忆如何被召回并组装到提示词中。
[ context_engine ] engine = "default" # plugin = "qdrant-recall" # 解析为 ~/.librefang/plugins/qdrant-recall/ [ context_engine . hooks ] # ingest = "~/.librefang/scripts/my_recall.py" # after_turn = "~/.librefang/scripts/my_indexer.py" # runtime = "python" # python（默认）| native | v | node | deno | go | ruby | bash | bun | php | lua [[ context_engine . plugin_registries ]] name = "Official" github_repo = "librefang/librefang-registry" Copied! 字段 类型 默认值 说明 enginestring "default"内置引擎名称。目前仅支持 "default"。 pluginstring 或 null null插件名称。解析为 ~/.librefang/plugins/<name>/plugin.toml。设置时优先于手动 hooks。 hooks.ingeststring 或 null nullingest 钩子的脚本路径（在收到新用户消息时调用）。hooks.after_turnstring 或 null nullafter_turn 钩子的脚本路径（在每轮对话完成后调用）。hooks.runtimestring 或 null "python"运行钩子脚本的启动器。可选：python、native（直接执行预编译二进制）、v、node、deno、go、ruby、bash、bun、php、lua。未知值回退到 python 并打印 warning。 plugin_registrieslist of objects 官方注册表 插件注册表（GitHub owner/repo），用于浏览可安装的插件。
钩子脚本使用语言无关的 JSON-over-stdin/stdout 协议 —— 根据脚本选对应的 runtime：
# Go 插件 [ context_engine . hooks ] ingest = "~/.librefang/plugins/my-go-recall/hooks/ingest.go" runtime = "go" # V 编译成原生二进制 [ context_engine . hooks ] ingest = "~/.librefang/plugins/fast-recall/hooks/ingest" runtime = "native" Copied! 检查 runtime 可用性
调用 GET /api/plugins/doctor 会扫描主机上所有支持的 runtime，返回每个 runtime 检测到的版本和缺失时的安装提示，并把已安装的插件和它们声明的 runtime 对照起来，标出哪些插件因为 runtime 缺失无法运行。
官方 Docker 镜像里的 runtime
官方镜像（基于 node:lts-bookworm-slim）默认带了 python、node、bash、nativeFROM 后 extend：
# V RUN git clone --depth 1 https://github.com/vlang/v /opt/v \ && make -C /opt/v && ln -s /opt/v/v /usr/local/bin/v # Deno RUN curl -fsSL https://deno.land/install.sh | DENO_INSTALL=/usr/local sh # Go RUN curl -fsSL https://go.dev/dl/go1.23.0.linux-amd64.tar.gz | tar -C /usr/local -xz \ && ln -s /usr/local/go/bin/go /usr/local/bin/go # Ruby RUN apt-get update && apt-get install -y --no-install-recommends ruby && rm -rf /var/lib/apt/lists/* # Bun RUN curl -fsSL https://bun.sh/install | BUN_INSTALL=/usr/local bash # PHP RUN apt-get update && apt-get install -y --no-install-recommends php-cli && rm -rf /var/lib/apt/lists/* # Lua（Lua 脚手架模板用到 dkjson） RUN apt-get update && apt-get install -y --no-install-recommends lua5.4 lua-dkjson && rm -rf /var/lib/apt/lists/* Copied! 如果插件声明的 runtime 不在 PATH 上，对应的 hook 会返回 LauncherNotFound 错误并附上安装提示 —— 其他插件继续正常运行，只有配置不对的那个受影响。
[audit]配置审计日志保留策略。
[ audit ] retention_days = 90 Copied! 字段 类型 默认值 说明 retention_daysu32 90审计日志条目的保留天数。0 = 无限期保留。
[health_check]配置 LLM 提供商的定期健康检查。
[ health_check ] health_check_interval_secs = 60 Copied! 字段 类型 默认值 说明 health_check_interval_secsu64 60提供商健康检查的间隔（秒）。
[plugins]配置额外的插件注册表，用于搜索可安装的上下文引擎插件。
[ plugins ] plugin_registries = [ "acme-corp/librefang-plugins" ] Copied! 字段 类型 默认值 说明 plugin_registrieslist of strings []额外的 GitHub owner/repo 插件注册表。与 context_engine.plugin_registries 合并。
[prompt_intelligence]配置 Prompt 版本管理和 A/B 实验功能。启用后，LibreFang 自动追踪 prompt 版本历史，支持运行 A/B 实验对比不同 prompt 变体。详细文档见 Prompt 智能指南 。
[ prompt_intelligence ] enabled = false hash_prompts = true max_versions_per_agent = 50 Copied! 字段 类型 默认值 说明 enabledbool false总开关。关闭时不追踪 prompt 版本，不运行实验 hash_promptsbool true计算 prompt 内容哈希用于去重 max_versions_per_agentu32 50每个 agent 最大 prompt 版本数，超出后自动清理最旧的非活跃版本
以下是配置中引用的所有环境变量的完整表格。这些变量不由配置文件本身读取——它们在运行时由内核和通道适配器读取。
LLM 提供商密钥
变量 使用者 说明 ANTHROPIC_API_KEY[default_model]Anthropic API Key（Claude 系列模型）。 GEMINI_API_KEYGemini 驱动 Google Gemini API Key。别名：GOOGLE_API_KEY。 OPENAI_API_KEYOpenAI 兼容驱动 OpenAI API Key。 GROQ_API_KEYGroq 提供商 Groq API Key（快速 Llama 推理）。 DEEPSEEK_API_KEYDeepSeek 提供商 DeepSeek API Key。 PERPLEXITY_API_KEYPerplexity 提供商 / 网页搜索 Perplexity API Key。 OPENROUTER_API_KEYOpenRouter 提供商 OpenRouter API Key。 TOGETHER_API_KEYTogether AI 提供商 Together AI API Key。 MISTRAL_API_KEYMistral 提供商 Mistral AI API Key。 FIREWORKS_API_KEYFireworks 提供商 Fireworks AI API Key。 COHERE_API_KEYCohere 提供商 Cohere API Key。 AI21_API_KEYAI21 提供商 AI21 Labs API Key。 CEREBRAS_API_KEYCerebras 提供商 Cerebras API Key。 SAMBANOVA_API_KEYSambaNova 提供商 SambaNova API Key。 HUGGINGFACE_API_KEYHugging Face 提供商 Hugging Face Inference API Key。 XAI_API_KEYxAI 提供商 xAI (Grok) API Key。 REPLICATE_API_KEYReplicate 提供商 Replicate API Key。
网页搜索密钥
变量 使用者 说明 BRAVE_API_KEY[web.brave]Brave Search API Key。 JINA_API_KEY[web.jina]Jina AI Search API Key。 TAVILY_API_KEY[web.tavily]Tavily Search API Key。 PERPLEXITY_API_KEY[web.perplexity]Perplexity Search API Key（与 LLM 提供商共用）。
通道令牌
变量 通道 说明 TELEGRAM_BOT_TOKENTelegram 从 @BotFather 获取的 Bot API 令牌。 DISCORD_BOT_TOKENDiscord Discord Bot 令牌。 SLACK_APP_TOKENSlack Slack 应用级令牌（xapp-），用于 Socket Mode。 SLACK_BOT_TOKENSlack Slack Bot 令牌（xoxb-），用于 REST API。 WHATSAPP_ACCESS_TOKENWhatsApp WhatsApp Cloud API 访问令牌。 WHATSAPP_VERIFY_TOKENWhatsApp Webhook 验证令牌。 MATRIX_ACCESS_TOKENMatrix Matrix 家服务器访问令牌。 EMAIL_PASSWORDEmail 邮箱密码或应用专用密码。 TEAMS_APP_PASSWORDTeams Azure Bot Framework 应用密码。 MATTERMOST_TOKENMattermost Mattermost Bot 令牌。 TWITCH_OAUTH_TOKENTwitch Twitch OAuth 令牌。 ROCKETCHAT_TOKENRocket.Chat Rocket.Chat 认证令牌。 ZULIP_API_KEYZulip Zulip Bot API Key。 XMPP_PASSWORDXMPP XMPP 账号密码。 GOOGLE_CHAT_SERVICE_ACCOUNTGoogle Chat 服务账号 JSON 密钥。 LINE_CHANNEL_SECRETLINE LINE Channel Secret。 LINE_CHANNEL_ACCESS_TOKENLINE LINE Channel Access Token。 VIBER_AUTH_TOKENViber Viber Bot 认证令牌。 MESSENGER_PAGE_TOKENMessenger Facebook 页面访问令牌。 MESSENGER_VERIFY_TOKENMessenger Webhook 验证令牌。 REDDIT_CLIENT_SECRETReddit Reddit 应用客户端密钥。 REDDIT_PASSWORDReddit Reddit Bot 账号密码。 MASTODON_ACCESS_TOKENMastodon Mastodon 访问令牌。 BLUESKY_APP_PASSWORDBluesky Bluesky 应用密码。 FEISHU_APP_SECRETFeishu 飞书/Lark 应用密钥。 REVOLT_BOT_TOKENRevolt Revolt Bot 令牌。 NEXTCLOUD_TOKENNextcloud Nextcloud Talk 认证令牌。 GUILDED_BOT_TOKENGuilded Guilded Bot 令牌。 KEYBASE_PAPERKEYKeybase Keybase 纸钥匙。 THREEMA_SECRETThreema Threema Gateway API 密钥。 NOSTR_PRIVATE_KEYNostr Nostr 私钥（nsec 或十六进制格式）。 WEBEX_BOT_TOKENWebex Webex Bot 令牌。 PUMBLE_BOT_TOKENPumble Pumble Bot 令牌。 FLOCK_BOT_TOKENFlock Flock Bot 令牌。 TWIST_TOKENTwist Twist API 令牌。 MUMBLE_PASSWORDMumble Mumble 服务器密码。 DINGTALK_APP_KEYDingTalk 钉钉 App Key / Client ID（stream 模式）。 DINGTALK_APP_SECRETDingTalk 钉钉 App Secret / Client Secret（stream 模式）。 DINGTALK_ACCESS_TOKENDingTalk 钉钉 Webhook 访问令牌（webhook 模式）。 DINGTALK_SECRETDingTalk 钉钉签名密钥（webhook 模式）。 DISCOURSE_API_KEYDiscourse Discourse API Key。 GITTER_TOKENGitter Gitter 认证令牌。 NTFY_TOKENntfy ntfy 认证令牌（公共主题可选）。 GOTIFY_APP_TOKENGotify Gotify 应用令牌（发送）。 GOTIFY_CLIENT_TOKENGotify Gotify 客户端令牌（接收）。 WEBHOOK_SECRETWebhook 用于 Webhook 验证的 HMAC 签名密钥。 LINKEDIN_ACCESS_TOKENLinkedIn LinkedIn OAuth2 访问令牌。
KernelConfig::validate() 在启动时运行，返回一组警告 （非致命错误）。内核仍会启动，但会逐条记录警告日志。
校验范围
对于每个已启用的通道 （即其配置节存在于 TOML 中），校验器会检查对应的环境变量是否已设置且非空：
通道 检查的环境变量 Telegram bot_token_envDiscord bot_token_envSlack app_token_env、bot_token_env（两者都检查）WhatsApp access_token_envMatrix access_token_envEmail password_envTeams app_password_envMattermost token_envZulip api_key_envTwitch oauth_token_envRocket.Chat token_envGoogle Chat service_account_envXMPP password_envLINE access_token_envViber auth_token_envMessenger page_token_envReddit client_secret_envMastodon access_token_envBluesky app_password_envFeishu app_secret_envRevolt bot_token_envNextcloud token_envGuilded bot_token_envKeybase paperkey_envThreema secret_envNostr private_key_envWebex bot_token_envPumble bot_token_envFlock bot_token_envTwist token_envMumble password_envDingTalk app_key_env（stream）或 access_token_env（webhook）Discourse api_key_envGitter token_envntfy token_env（仅当 token_env 非空时；公共主题无需认证）Gotify app_token_envWebhook secret_envLinkedIn access_token_env
对于网页搜索提供商 ，校验器检查：
提供商 检查的环境变量 braveweb.brave.api_key_envjinaweb.jina.api_key_envtavilyweb.tavily.api_key_envperplexityweb.perplexity.api_key_envduckduckgo（无需检查——不需要 API Key） auto（无需检查——级联回退会处理缺失的 Key）
不在校验范围内的内容
[default_model] 中的 api_key_env 不会被 validate() 检查。缺失的 LLM Key 会在驱动首次使用时产生运行时错误。[network] 中的 shared_secret 不会对照 network_enabled 进行校验。如果启用了网络但密钥为空，认证将在连接时失败。MCP 服务器配置不在配置加载时校验。连接错误会在后台 MCP 连接阶段暴露。
Agent 清单有自己独立的校验流程。
部分子系统有自己的配置，不在 config.toml 中，但值得了解：
会话压缩
通过 config.toml 中的 [compaction] 部分配置：
[ compaction ] threshold_messages = 30 # 消息数超过此值时触发压缩 keep_recent = 10 # 压缩后逐字保留的最近消息数 max_summary_tokens = 1024 # LLM 摘要的最大 Token 数 token_threshold_ratio = 0.7 # 估算 Token 超过上下文窗口此比例时触发 max_chunk_chars = 80000 # 每个摘要分块的最大字符数 max_retries = 3 # LLM 摘要的最大重试次数 Copied! 字段 默认值 说明 threshold_messages30会话消息数超过此值时触发压缩。 keep_recent10压缩后保留的最近消息数量（逐字保留）。 max_summary_tokens1024LLM 对压缩消息生成摘要的最大 Token 数。 token_threshold_ratio0.7估算 Token 超过上下文窗口此比例时触发压缩。 max_chunk_chars80000每个摘要分块的最大字符数。 max_retries3LLM 摘要的最大重试次数。
WASM 沙箱（运行时）
通过 SandboxConfig 内部配置（目前未在 config.toml 中暴露）：
字段 默认值 说明 fuel_limit1000000最大 CPU 指令预算。0 = 无限制。 max_memory_bytes16777216（16 MB）WASM 线性内存上限。 timeout_secsnull（回退 30 秒）基于 epoch 中断的挂钟超时时间。
模型路由（Agent 清单）
在 Agent 清单中通过 ModelRoutingConfig 配置：
字段 默认值 说明 simple_model"claude-haiku-4-5-20251001"简单查询使用的模型。 medium_model"claude-sonnet-4-20250514"中等复杂度查询使用的模型。 complex_model"claude-sonnet-4-20250514"复杂查询使用的模型。 simple_threshold100Token 数低于此值的查询被归类为简单查询。 complex_threshold500Token 数高于此值的查询被归类为复杂查询。
自主模式护栏（Agent 清单）
在 Agent 清单中通过 AutonomousConfig 配置：
字段 默认值 说明 quiet_hoursnull静默时段的 Cron 表达式（Agent 在此时间窗口暂停）。 max_iterations50每次调用的最大工具使用迭代次数。 max_restarts10永久停止前的最大自动重启次数。 heartbeat_interval_secs30心跳健康检查的间隔（秒）。 heartbeat_channelnull发送心跳状态的通道（例如 "telegram"）。