Config Reference

Config Reference

自动生成/校准日期：2026-05-04。事实来源：SouWen 主仓库 pr-88 commit a312645 的 registry、config model、CLI/API 代码与 checked-in docs。

SouWen 配置优先级：

环境变量 > ./souwen.yaml > ~/.config/souwen/config.yaml > .env > 默认值

环境变量规则通常是 SOUWEN_<FIELD_NAME_UPPER>；WARP 字段额外支持 Docker 兼容别名，例如 WARP_MODE。

LLM 摘要

字段	环境变量	类型	默认值	说明
llm	SOUWEN_LLM	LLMConfig	{}	LLM 摘要配置对象，控制 summarize 和 fetch/summarize，不影响普通搜索和抓取。

MCP

字段	环境变量	类型	默认值	说明
mcp_server_url	SOUWEN_MCP_SERVER_URL	str | null	null	外部 MCP Server URL；配置后 mcp fetch provider 可把抓取委托给该服务。
mcp_transport	SOUWEN_MCP_TRANSPORT	str	streamable_http	外部 MCP 传输方式；默认 streamable_http。
mcp_fetch_tool_name	SOUWEN_MCP_FETCH_TOOL_NAME	str	fetch	外部 MCP Server 上用于抓取的 tool 名称，默认调用 fetch。
mcp_extra_headers	SOUWEN_MCP_EXTRA_HEADERS	dict[str, str]	{}	调用外部 MCP Server 时附加的 HTTP headers，例如内部网关认证头。
mcp_http_enabled	SOUWEN_MCP_HTTP_ENABLED	bool	False	是否启用 SouWen 自身的 HTTP MCP endpoint。
mcp_http_enable_sse	SOUWEN_MCP_HTTP_ENABLE_SSE	bool	True	HTTP MCP endpoint 是否同时启用 SSE 兼容入口。
mcp_http_stateless	SOUWEN_MCP_HTTP_STATELESS	bool	True	HTTP MCP endpoint 是否以 stateless 模式运行，适合无会话部署。
mcp_http_json_response	SOUWEN_MCP_HTTP_JSON_RESPONSE	bool	True	HTTP MCP endpoint 是否返回 JSON response，便于代理或客户端解析。

WARP

字段	环境变量	类型	默认值	说明
warp_enabled	SOUWEN_WARP_ENABLED / WARP_ENABLED	bool	False	启动时是否启用 WARP。
warp_mode	SOUWEN_WARP_MODE / WARP_MODE	str	auto	auto、wireproxy、kernel、usque、warp-cli、external。
warp_socks_port	SOUWEN_WARP_SOCKS_PORT / WARP_SOCKS_PORT	int	1080	SOCKS5 端口。
warp_endpoint	SOUWEN_WARP_ENDPOINT / WARP_ENDPOINT	str | null	null	自定义 endpoint。
warp_bind_address	SOUWEN_WARP_BIND_ADDRESS / WARP_BIND_ADDRESS	str	127.0.0.1	本地绑定地址。
warp_startup_timeout	SOUWEN_WARP_STARTUP_TIMEOUT / WARP_STARTUP_TIMEOUT	int	15	启动等待秒数。
warp_device_name	SOUWEN_WARP_DEVICE_NAME / WARP_DEVICE_NAME	str | null	null	kernel 模式设备名。
warp_proxy_username	SOUWEN_WARP_PROXY_USERNAME / WARP_PROXY_USERNAME	str | null	null	代理认证用户名。
warp_proxy_password	SOUWEN_WARP_PROXY_PASSWORD / WARP_PROXY_PASSWORD	str | null	null	代理认证密码。
warp_usque_path	SOUWEN_WARP_USQUE_PATH / WARP_USQUE_PATH	str | null	null	usque 二进制路径。
warp_usque_config	SOUWEN_WARP_USQUE_CONFIG / WARP_USQUE_CONFIG	str | null	null	usque config.json 路径。
warp_usque_transport	SOUWEN_WARP_USQUE_TRANSPORT / WARP_USQUE_TRANSPORT	str	auto	auto、quic、http2。
warp_usque_system_dns	SOUWEN_WARP_USQUE_SYSTEM_DNS / WARP_USQUE_SYSTEM_DNS	bool	False	usque 是否使用系统 DNS。
warp_usque_on_connect	SOUWEN_WARP_USQUE_ON_CONNECT / WARP_USQUE_ON_CONNECT	str | null	null	连接后执行脚本。
warp_usque_on_disconnect	SOUWEN_WARP_USQUE_ON_DISCONNECT / WARP_USQUE_ON_DISCONNECT	str | null	null	断开后执行脚本。
warp_http_port	SOUWEN_WARP_HTTP_PORT / WARP_HTTP_PORT	int	0	HTTP 代理端口，0 表示关闭。
warp_license_key	SOUWEN_WARP_LICENSE_KEY / WARP_LICENSE_KEY	str | null	null	WARP+ license key。
warp_team_token	SOUWEN_WARP_TEAM_TOKEN / WARP_TEAM_TOKEN	str | null	null	ZeroTrust team token。
warp_gost_args	SOUWEN_WARP_GOST_ARGS / WARP_GOST_ARGS	str | null	null	warp-cli 上层 GOST 参数。
warp_external_proxy	SOUWEN_WARP_EXTERNAL_PROXY / WARP_EXTERNAL_PROXY	str | null	null	external 模式外部代理 URL。

专利源凭据

字段	环境变量	类型	默认值	说明
uspto_api_key	SOUWEN_USPTO_API_KEY	str | null	null	API Key，供 uspto_odp 使用；认证要求：必须凭据。
epo_consumer_key	SOUWEN_EPO_CONSUMER_KEY	str | null	null	OAuth consumer key，供 epo_ops 使用；认证要求：必须凭据。
epo_consumer_secret	SOUWEN_EPO_CONSUMER_SECRET	str | null	null	OAuth consumer secret，供 epo_ops 使用；认证要求：必须凭据。
cnipa_client_id	SOUWEN_CNIPA_CLIENT_ID	str | null	null	OAuth/client ID，供 cnipa 使用；认证要求：必须凭据。
cnipa_client_secret	SOUWEN_CNIPA_CLIENT_SECRET	str | null	null	OAuth/client secret，供 cnipa 使用；认证要求：必须凭据。
lens_api_token	SOUWEN_LENS_API_TOKEN	str | null	null	API Token，供 the_lens 使用；认证要求：必须凭据。
patsnap_api_key	SOUWEN_PATSNAP_API_KEY	str | null	null	API Key，供 patsnap 使用；认证要求：必须凭据。

内容抓取

字段	环境变量	类型	默认值	说明
jina_api_key	SOUWEN_JINA_API_KEY	str | null	null	API Key，供 jina_reader 使用；认证要求：可选凭据。 配置后主要效果：提升限流额度或降低受限概率 (rate_limit)。
scrapfly_api_key	SOUWEN_SCRAPFLY_API_KEY	str | null	null	API Key，供 scrapfly 使用；认证要求：必须凭据。
diffbot_api_token	SOUWEN_DIFFBOT_API_TOKEN	str | null	null	API Token，供 diffbot 使用；认证要求：必须凭据。
scrapingbee_api_key	SOUWEN_SCRAPINGBEE_API_KEY	str | null	null	API Key，供 scrapingbee 使用；认证要求：必须凭据。
zenrows_api_key	SOUWEN_ZENROWS_API_KEY	str | null	null	API Key，供 zenrows 使用；认证要求：必须凭据。
scraperapi_api_key	SOUWEN_SCRAPERAPI_API_KEY	str | null	null	API Key，供 scraperapi 使用；认证要求：必须凭据。
apify_api_token	SOUWEN_APIFY_API_TOKEN	str | null	null	API Token，供 apify 使用；认证要求：必须凭据。
cloudflare_api_token	SOUWEN_CLOUDFLARE_API_TOKEN	str | null	null	API Token，供 cloudflare 使用；认证要求：必须凭据。
cloudflare_account_id	SOUWEN_CLOUDFLARE_ACCOUNT_ID	str | null	null	Cloudflare Account ID（Browser Rendering），供 cloudflare 使用；认证要求：必须凭据。

开发者/社区/办公

字段	环境变量	类型	默认值	说明
github_token	SOUWEN_GITHUB_TOKEN	str | null	null	Token，供 github 使用；认证要求：可选凭据。 配置后主要效果：提升限流额度或降低受限概率 (rate_limit)。
stackoverflow_api_key	SOUWEN_STACKOVERFLOW_API_KEY	str | null	null	API Key，供 stackoverflow 使用；认证要求：可选凭据。 配置后主要效果：启用或提升 API 配额 (quota)。
feishu_app_id	SOUWEN_FEISHU_APP_ID	str | null	null	应用 App ID，供 feishu_drive 使用；认证要求：必须凭据。
feishu_app_secret	SOUWEN_FEISHU_APP_SECRET	str | null	null	应用 App Secret，供 feishu_drive 使用；认证要求：必须凭据。

插件

字段	环境变量	类型	默认值	说明
plugins	SOUWEN_PLUGINS	list[str]	[]	手动指定的插件列表，格式为 'module.path:attribute'
plugin_config	SOUWEN_PLUGIN_CONFIG	dict[str, dict[str, Any]]	{}	按插件名传递给第三方插件的配置字典

社交源

字段	环境变量	类型	默认值	说明
twitter_bearer_token	SOUWEN_TWITTER_BEARER_TOKEN	str | null	null	Bearer Token，供 twitter 使用；认证要求：必须凭据。
reddit_client_id	SOUWEN_REDDIT_CLIENT_ID	str | null	null	Reddit OAuth2 App Client ID；配置后 Reddit 客户端优先走 oauth.reddit.com，否则回退公开 JSON 搜索。
reddit_client_secret	SOUWEN_REDDIT_CLIENT_SECRET	str | null	null	Reddit OAuth2 App Client Secret；需与 reddit_client_id 配套使用。
facebook_app_id	SOUWEN_FACEBOOK_APP_ID	str | null	null	应用 App ID，供 facebook 使用；认证要求：必须凭据。
facebook_app_secret	SOUWEN_FACEBOOK_APP_SECRET	str | null	null	应用 App Secret，供 facebook 使用；认证要求：必须凭据。

网络与代理

字段	环境变量	类型	默认值	说明
proxy	SOUWEN_PROXY	str | null	null	全局代理 URL；未设置时直接联网，频道级 sources.<name>.proxy 可覆盖。
proxy_pool	SOUWEN_PROXY_POOL	list[str]	[]	代理池列表，供需要轮换出口的抓取或搜索场景使用。
default_http_backend	SOUWEN_DEFAULT_HTTP_BACKEND	str	auto	爬虫源默认 HTTP backend；auto 会按依赖可用性选择，必要时可固定为 curl_cffi 或 httpx。
http_backend	SOUWEN_HTTP_BACKEND	dict[str, str]	{}	按源名覆盖 HTTP backend，例如为 duckduckgo 指定 curl_cffi。

网页搜索与自建源

字段	环境变量	类型	默认值	说明
searxng_url	SOUWEN_SEARXNG_URL	str | null	null	自建实例基础 URL，供 searxng 使用；认证要求：自建实例 URL。
tavily_api_key	SOUWEN_TAVILY_API_KEY	str | null	null	API Key，供 tavily 使用；认证要求：必须凭据。
exa_api_key	SOUWEN_EXA_API_KEY	str | null	null	API Key，供 exa 使用；认证要求：必须凭据。
serper_api_key	SOUWEN_SERPER_API_KEY	str | null	null	API Key，供 serper 使用；认证要求：必须凭据。
brave_api_key	SOUWEN_BRAVE_API_KEY	str | null	null	API Key，供 brave_api 使用；认证要求：必须凭据。
serpapi_api_key	SOUWEN_SERPAPI_API_KEY	str | null	null	API Key，供 serpapi 使用；认证要求：必须凭据。
firecrawl_api_key	SOUWEN_FIRECRAWL_API_KEY	str | null	null	API Key，供 firecrawl 使用；认证要求：必须凭据。
perplexity_api_key	SOUWEN_PERPLEXITY_API_KEY	str | null	null	API Key，供 perplexity 使用；认证要求：必须凭据。
linkup_api_key	SOUWEN_LINKUP_API_KEY	str | null	null	API Key，供 linkup 使用；认证要求：必须凭据。
xcrawl_api_key	SOUWEN_XCRAWL_API_KEY	str | null	null	API Key，供 xcrawl 使用；认证要求：必须凭据。
scrapingdog_api_key	SOUWEN_SCRAPINGDOG_API_KEY	str | null	null	API Key，供 scrapingdog 使用；认证要求：必须凭据。
metaso_api_key	SOUWEN_METASO_API_KEY	str | null	null	API Key，供 metaso 使用；认证要求：必须凭据。
whoogle_url	SOUWEN_WHOOGLE_URL	str | null	null	自建实例基础 URL，供 whoogle 使用；认证要求：自建实例 URL。
websurfx_url	SOUWEN_WEBSURFX_URL	str | null	null	自建实例基础 URL，供 websurfx 使用；认证要求：自建实例 URL。
zhipuai_api_key	SOUWEN_ZHIPUAI_API_KEY	str | null	null	API Key，供 zhipuai 使用；认证要求：必须凭据。
aliyun_iqs_api_key	SOUWEN_ALIYUN_IQS_API_KEY	str | null	null	API Key，供 aliyun_iqs 使用；认证要求：必须凭据。

视频源

字段	环境变量	类型	默认值	说明
youtube_api_key	SOUWEN_YOUTUBE_API_KEY	str | null	null	API Key，供 youtube 使用；认证要求：必须凭据。
bilibili_sessdata	SOUWEN_BILIBILI_SESSDATA	str	""	Bilibili 登录态 Cookie SESSDATA，供 bilibili 使用；认证要求：可选凭据。 配置后主要效果：启用登录态或个性化能力 (personalization)。

认证与服务

字段	环境变量	类型	默认值	说明
api_password	SOUWEN_API_PASSWORD	str | null	null	兼容旧版本的 API 访问密码；新部署优先区分 visitor/user/admin 三类密码。
visitor_password	SOUWEN_VISITOR_PASSWORD	str | null	null	访客/查询类接口密码，用于搜索、抓取、sources 等低权限访问。
user_password	SOUWEN_USER_PASSWORD	str | null	null	普通用户权限密码，适合允许配置部分个人功能但不开放管理操作的场景。
admin_password	SOUWEN_ADMIN_PASSWORD	str | null	null	管理员密码；保护 /api/v1/admin/*、插件安装卸载、运行时配置等高权限操作。
guest_enabled	SOUWEN_GUEST_ENABLED	bool	False	是否允许 guest 模式访问；关闭时需要按角色提供 Bearer Token 或密码。
cors_origins	SOUWEN_CORS_ORIGINS	list[str]	[]	CORS 允许的来源列表,为空时不启用 CORS
trusted_proxies	SOUWEN_TRUSTED_PROXIES	list[str]	[]	受信反向代理的 IP/CIDR 列表;只有来自这些地址的请求才会读取 X-Forwarded-For 头解析真实客户端 IP.
expose_docs	SOUWEN_EXPOSE_DOCS	bool	True	是否暴露 /docs、/redoc、/openapi.json;生产环境可设为 false.

论文源凭据

字段	环境变量	类型	默认值	说明
openalex_email	SOUWEN_OPENALEX_EMAIL	str | null	null	联系邮箱或账号邮箱，供 openalex 使用；认证要求：可选凭据。 配置后主要效果：礼貌调用/联系邮箱，用于帮助上游识别调用方 (politeness)。
semantic_scholar_api_key	SOUWEN_SEMANTIC_SCHOLAR_API_KEY	str | null	null	API Key，供 semantic_scholar 使用；认证要求：可选凭据。 配置后主要效果：提升限流额度或降低受限概率 (rate_limit)。
core_api_key	SOUWEN_CORE_API_KEY	str | null	null	API Key，供 core 使用；认证要求：必须凭据。
openaire_api_key	SOUWEN_OPENAIRE_API_KEY	str | null	null	API Key，供 openaire 使用；认证要求：可选凭据。 配置后主要效果：启用或提升 API 配额 (quota)。
doaj_api_key	SOUWEN_DOAJ_API_KEY	str | null	null	API Key，供 doaj 使用；认证要求：可选凭据。 配置后主要效果：提升限流额度或降低受限概率 (rate_limit)。
zenodo_access_token	SOUWEN_ZENODO_ACCESS_TOKEN	str | null	null	Access Token，供 zenodo 使用；认证要求：可选凭据。 配置后主要效果：启用或提升 API 配额 (quota)。
pubmed_api_key	SOUWEN_PUBMED_API_KEY	str | null	null	NCBI/PubMed API Key；PubMed 与 PMC 客户端会读取该字段，不配置仍可访问公开端点但限流较低。
unpaywall_email	SOUWEN_UNPAYWALL_EMAIL	str | null	null	联系邮箱或账号邮箱，供 unpaywall 使用；认证要求：必须凭据。
ieee_api_key	SOUWEN_IEEE_API_KEY	str | null	null	API Key，供 ieee_xplore 使用；认证要求：必须凭据。
zotero_api_key	SOUWEN_ZOTERO_API_KEY	str | null	null	API Key，供 zotero 使用；认证要求：必须凭据。
zotero_library_id	SOUWEN_ZOTERO_LIBRARY_ID	str | null	null	Zotero library ID，供 zotero 使用；认证要求：必须凭据。
zotero_library_type	SOUWEN_ZOTERO_LIBRARY_TYPE	str | null	null	Zotero library 类型，通常为 user 或 group；未设置时客户端按 user 处理。

运行时基础配置

字段	环境变量	类型	默认值	说明
timeout	SOUWEN_TIMEOUT	int	30	默认请求超时秒数；CLI/API 层也可能提供单次调用覆盖。
max_retries	SOUWEN_MAX_RETRIES	int	3	默认重试次数，用于网络抖动、限流或临时上游失败场景。
data_dir	SOUWEN_DATA_DIR	str	~/.local/share/souwen	SouWen 本地数据目录，用于持久化运行时配置、缓存或插件相关数据。
respect_robots_txt	SOUWEN_RESPECT_ROBOTS_TXT	bool	False	抓取时是否遵守 robots.txt；生产或公开服务建议按目标站点政策开启。

频道级数据源配置

字段	环境变量	类型	默认值	说明
sources	SOUWEN_SOURCES	dict[str, SourceChannelConfig]	{}	频道级数据源覆盖字典，键为源名，值为 enabled/proxy/http_backend/base_url/api_key/headers/params 等运行时覆盖。

嵌套配置

• Source Channel Config：sources.<name> 的字段。
• LLM Config：llm 的字段。
• WARP Config：WARP 运行模式和组件配置。