配置文件

免责声明

本文档可能已过时、不完整或不准确。请参阅你安装中附带的默认 config.yaml 以获取最新、最完整的设置列表。

警告：请勿直接编辑默认配置。这样做不会产生任何正面效果。请改为编辑仓库根目录中它的副本。

config.yaml 是 SillyTavern 服务器的主配置文件，在完成安装并首次运行服务器后，你可以在仓库根目录找到它。它是一个 YAML 文件，包含网络、安全以及后端相关的各种设置。对该文件所做的更改将在重启服务器后生效。

在更新仓库后重启服务器时，上游新增的设置会自动填充默认值，随后你可以按需修改这些设置。若想在启动前补全缺失的设置，请运行 npm run init 脚本。

对于嵌套设置，使用点号表示法来表示层级关系。例如，protocol.ipv6: false 指的是 protocol 节下的 ipv6 设置，其值为 false。

protocol:
  ipv6: false

命令行参数

启动 SillyTavern 服务器时可以传入命令行参数，以覆盖 config.yaml 中的部分设置。

示例

node server.js --port 8000 --listen false
# or
npm run start -- --port 8000 --listen false
# or (Windows only)
Start.bat --port 8000 --listen false

支持的参数

所有参数都不是必填的。如果你不提供它们，SillyTavern 将使用 config.yaml 中的设置。

选项	说明	类型
`--version`	显示版本号	boolean
`--global`	强制使用系统级路径存放应用数据	boolean
`--configPath`	覆盖 config.yaml 文件的路径（仅独立模式）	string
`--dataRoot`	设置数据存储的根目录（仅独立模式）	string
`--port`	设置 SillyTavern 运行的端口	number
`--listen`	让 SillyTavern 在所有网络接口上监听	boolean
`--whitelist`	启用白名单模式	boolean
`--basicAuthMode`	启用基础认证	boolean
`--enableIPv4`	启用 IPv4 协议	boolean
`--enableIPv6`	启用 IPv6 协议	boolean
`--listenAddressIPv4`	指定要监听的 IPv4 地址	string
`--listenAddressIPv6`	指定要监听的 IPv6 地址	string
`--dnsPreferIPv6`	DNS 解析时优先使用 IPv6	boolean
`--ssl`	启用 SSL	boolean
`--certPath`	设置证书文件的路径	string
`--keyPath`	设置私钥文件的路径	string
`--browserLaunchEnabled`	自动在浏览器中启动 SillyTavern	boolean
`--browserLaunchHostname`	设置浏览器启动的主机名	string
`--browserLaunchPort`	覆盖浏览器启动的端口	string
`--browserLaunchAvoidLocalhost`	自动模式下浏览器启动时避免使用 'localhost'	boolean
`--corsProxy`	启用 CORS 代理	boolean
`--requestProxyEnabled`	启用为出站请求使用代理	boolean
`--requestProxyUrl`	设置请求代理 URL（HTTP 或 SOCKS 协议）	string
`--requestProxyBypass`	设置请求代理的绕过列表（以空格分隔的主机列表）	array
`--disableCsrf`	禁用 CSRF 防护（不推荐）	boolean

环境变量

配置也可以通过环境变量来设置，环境变量会覆盖 config.yaml 文件中的值。

环境变量应以 SILLYTAVERN_ 为前缀，并且设置名使用大写字母。例如，dataRoot 设置可以通过 SILLYTAVERN_DATAROOT 环境变量来覆盖。

嵌套设置之间应使用下划线分隔。例如，protocol.ipv6 可以通过 SILLYTAVERN_PROTOCOL_IPV6 环境变量来覆盖。

期望接收数组或对象的配置应进行 JSON 序列化。例如，要通过 SILLYTAVERN_WHITELIST 环境变量覆盖 whitelist 设置，你应将其设为 JSON 字符串：SILLYTAVERN_WHITELIST='["127.0.0.1", "::1"]'。

如果你使用 Node.js v20 或更高版本，你也可以将环境变量存储在 .env 文件中，并通过 --env-file 标志将其传递给服务器。例如，要使用位于仓库根目录的 .env 文件，你可以使用以下命令启动服务器：

node --env-file=.env server.js

或者，直接通过命令行传递环境变量：

SILLYTAVERN_LISTEN=true SILLYTAVERN_PORT=8000 node server.js

有关使用环境变量的更多信息，请参阅 Node.js 文档。

数据配置

设置	说明	默认值	允许的值
`dataRoot`	用户数据存储的根目录（仅独立模式）	`./data`	任何有效的目录路径
`skipContentCheck`	跳过对新默认内容的检查	`false`	`true`、`false`
`enableDownloadableTokenizers`	启用按需下载分词器	`true`	`true`、`false`
`whitelistImportDomains`	导入网络托管角色卡与素材时受信任的域名列表	参见此处	字符串数组

日志配置

设置	说明	默认值	允许的值
`logging.minLogLevel`	在终端中显示的最低日志级别	`0` (DEBUG)	(DEBUG = 0, INFO = 1, WARN = 2, ERROR = 3)
`logging.enableAccessLog`	将服务器访问日志写入文件和控制台	`true`	`true`、`false`

网络配置

设置	说明	默认值	允许的值
`listen`	启用对入站连接的监听	`false`	`true`、`false`
`port`	服务器监听端口	`8000`	任何有效的端口号（1-65535）
`heartbeatInterval`	为 Docker 健康检查写入心跳文件的间隔（秒）。设为 0 则禁用	`0`	`0`（禁用）、正整数
`protocol.ipv4`	启用对 IPv4 协议的监听	`true`	`true`、`false`、`auto`
`protocol.ipv6`	启用对 IPv6 协议的监听	`false`	`true`、`false`、`auto`
`listenAddress.ipv4`	监听特定的 IPv4 地址	`0.0.0.0`	有效的 IPv4 地址
`listenAddress.ipv6`	监听特定的 IPv6 地址	`'[::]'`	有效的 IPv6 地址
`dnsPreferIPv6`	DNS 解析时优先使用 IPv6	`false`	`true`、`false`
`enableKeepAlive`	全局启用 HTTP/HTTPS keep-alive	`false`	`true`、`false`

SSL 配置

设置	说明	默认值	允许的值
`ssl.enabled`	启用 SSL/TLS 加密和 HTTPS 协议	`false`	`true`、`false`
`ssl.keyPath`	SSL 私钥的路径（相对于服务器目录）	`"./certs/privkey.pem"`	有效的文件路径
`ssl.certPath`	SSL 证书的路径（相对于服务器目录）	`"./certs/cert.pem"`	有效的文件路径
`ssl.keyPassphrase`	SSL 私钥的口令。如不需要则留空	`""`	任何字符串

安全配置

IP 白名单

设置	说明	默认值	允许的值
`whitelistMode`	启用 IP 白名单过滤	`true`	`true`、`false`
`enableForwardedWhitelist`	检查转发头中的白名单 IP。头信息在转发头配置一节中定义	`true`	`true`、`false`
`whitelist`	允许的 IP 地址列表	`["::1", "127.0.0.1"]`	有效的 IP 地址数组
`whitelistDockerHosts`	自动将 Docker 主机 IP 加入白名单	`true`	`true`、`false`

转发头配置

调整用于确定真实 IP 的头信息，以支持 IP 白名单、速率限制和访问日志等功能。

仅在你确定使用的是正确配置的反向代理时才进行更改，否则可能导致 IP 欺骗。

设置	说明	默认值	允许的值
`forwardedHeaders.xRealIp`	使用 `X-Real-IP` 头来检测客户端 IP	`true`	`true`、`false`
`forwardedHeaders.xForwardedFor`	使用 `X-Forwarded-For` 头来检测客户端 IP	`true`	`true`、`false`
`forwardedHeaders.cfConnectingIp`	使用 `CF-Connecting-IP` 头来检测客户端 IP	`false`	`true`、`false`

私有地址白名单

这是一层额外的安全防护，用于防范服务器端请求伪造（SSRF）攻击，会对解析为私有 IP 地址的服务器端 HTTP 请求执行白名单检查。启用后，私有网络范围将被阻止，除非在 privateAddressWhitelist.allowedRanges 设置中显式允许。

该功能默认禁用，但在启用监听模式时，或当你的服务器可被不受信任的用户访问时，推荐启用。

设置	说明	默认值	允许的值
`privateAddressWhitelist.enabled`	启用私有地址白名单	`false`	`true`、`false`
`privateAddressWhitelist.allowUnresolvedHosts`	允许向无法解析的主机发起请求	`false`	`true`、`false`
`privateAddressWhitelist.allowedRanges`	允许的私有 IP 地址和 CIDR 范围列表	`['127.0.0.0/8', '::1/128']`	有效的 IP 地址和 CIDR 范围数组
`privateAddressWhitelist.log.blockedRequests`	记录被阻止的解析为私有 IP 地址的请求	`true`	`true`、`false`
`privateAddressWhitelist.log.allowedRequests`	记录被允许的解析为私有 IP 地址的请求	`false`	`true`、`false`

主机白名单

设置	说明	默认值	允许的值
`hostWhitelist.enabled`	启用主机白名单	`false`	`true`、`false`
`hostWhitelist.scan`	记录来自不受信任主机的入站请求	`true`	`true`、`false`
`hostWhitelist.hosts`	受信任的主机名列表	`[]`	有效的主机名数组

安全覆盖

强烈不建议禁用安全措施。在做出更改之前，请确保你清楚自己在做什么。

设置	说明	默认值	允许的值
`allowKeysExposure`	允许在 UI 中暴露未遮掩的 API 密钥	`false`	`true`、`false`
`disableCsrfProtection`	禁用 CSRF 防护（不推荐）	`false`	`true`、`false`
`securityOverride`	禁用启动时的安全检查（不推荐）	`false`	`true`、`false`

用户认证

默认对基础认证和用户账户登录尝试都启用了速率限制。你可以在速率限制配置一节中调整限制值。

如果在隧道连接（例如 Cloudflare 隧道）后使用基础认证，请务必相应地调整速率限制设置和 IP 地址检测，以免被锁定。

设置	说明	默认值	允许的值
`basicAuthMode`	启用基础认证	`false`	`true`、`false`
`basicAuthUser.username`	基础认证用户名	`"user"`	任何字符串
`basicAuthUser.password`	基础认证密码	`"password"`	任何字符串
`enableUserAccounts`	启用多用户模式	`false`	`true`、`false`
`enableDiscreetLogin`	在登录界面隐藏用户列表	`false`	`true`、`false`
`sessionTimeout`	用户会话超时时间（秒）	`-1`（禁用）	任何数字（-1 表示禁用，0 表示浏览器关闭时登出，>0 表示超时时间）
`perUserBasicAuth`	使用账户凭据进行基础认证	`false`	`true`、`false`

SSO 流程的安全配置不当可能导致未授权访问。请务必正确配置可信代理，并在启用 SSO 之前测试你的设置。如果你不确定其安全影响，建议保持 SSO 自动登录处于禁用状态，改用其他身份验证方式。

设置	说明	默认值	允许的值
`sso.trustedProxies`	用于 SSO 身份验证的可信代理 IP 列表	`["::1", "127.0.0.1"]`	有效的 IP 地址、CIDR 范围或通配符模式数组
`sso.autheliaAuth`	启用基于 Authelia 的自动登录。参见：SSO	`false`	`true`、`false`
`sso.authentikAuth`	启用基于 Authentik 的自动登录。参见：SSO	`false`	`true`、`false`

速率限制配置

要禁用某个路由的速率限制，请将限制值设为 0。

例如，要禁用登录的速率限制，请将 rateLimiting.accountsLoginMaxAttempts 设为 0。

设置	说明	默认值	允许的值
`rateLimiting.preferRealIpHeader`	进行速率限制时，使用转发头配置中配置的头中的 IP，而非 socket IP	`false`	`true`、`false`
`rateLimiting.accountsLoginMaxAttempts`	用户账户在临时锁定（1 分钟）前的最大登录尝试次数	`5`	任何正整数，或 `0`
`rateLimiting.accountsRecoverMaxAttempts`	临时锁定（5 分钟）前的最大密码恢复尝试次数	`5`	任何正整数，或 `0`
`rateLimiting.basicAuthMaxAttempts`	临时锁定（1 分钟）前的最大基础认证尝试次数	`5`	任何正整数，或 `0`

请求代理配置

请求代理与私有地址白名单功能冲突。如果同时启用两者，只有绕过代理的请求会接受私有地址白名单检查，而经代理的请求则完全不会被检查。如不确定，建议禁用请求代理。

设置	说明	默认值	允许的值
`requestProxy.enabled`	启用出站请求的代理	`false`	`true`、`false`
`requestProxy.url`	代理服务器 URL	`null`	有效的代理 URL（例如 `"socks5://username:password@example.com:1080"`）
`requestProxy.bypass`	要绕过代理的主机	`["localhost", "127.0.0.1"]`	主机名/IP 数组

CORS 代理配置

某些扩展可能需要启用 CORS 代理。任何内置功能都不需要它。

在没有适当安全措施（例如 IP、主机和私有地址白名单）的情况下启用 CORS 代理可能导致 SSRF 漏洞。如果启用此功能，请务必相应地配置白名单，并且仅在你信任需要它的扩展时才启用。

设置	说明	默认值	允许的值
`enableCorsProxy`	启用 CORS 代理中间件	`false`	`true`、`false`

CORS 配置

设置	说明	默认值	允许的值
`cors.enabled`	启用或禁用 CORS 中间件	`true`	`true`、`false`
`cors.origin`	允许的来源。`"null"` 匹配默认的浏览器文件来源	`["null"]`	`"*"`（任何来源）、允许的来源数组
`cors.methods`	允许的 HTTP 方法	`["OPTIONS"]`	HTTP 方法数组
`cors.allowedHeaders`	允许的请求头	`[]`	头名称数组
`cors.exposedHeaders`	暴露的响应头	`[]`	头名称数组
`cors.credentials`	允许携带凭据（cookie、授权头）	`false`	`true`、`false`
`cors.maxAge`	预检缓存的最大时间（秒）	`null`	`null`、正整数

浏览器启动配置

此前称为 "Autorun" 设置。

设置	说明	默认值	允许的值
`browserLaunch.enabled`	服务器启动时自动打开浏览器	`true`	`true`、`false`
`browserLaunch.browser`	用于打开 URL 的浏览器	`"default"`	`"default"`、`"chrome"`、`"firefox"`、`"edge"`、`"brave"`
`browserLaunch.hostname`	覆盖浏览器启动的主机名	`"auto"`	`"auto"`、任何有效的主机名（例如 `"localhost"`、`"st.example.com"`）
`browserLaunch.port`	覆盖浏览器启动的端口	`-1`	`-1`（使用服务器端口）、任何有效的端口号
`browserLaunch.avoidLocalhost`	避免在启动 URL 中使用 'localhost'	`false`	`true`、`false`

性能配置

设置	说明	默认值	允许的值
`performance.lazyLoadCharacters`	懒加载角色数据	`true`	`true`、`false`
`performance.useDiskCache`	为角色卡启用磁盘缓存	`true`	`true`、`false`
`performance.memoryCacheCapacity`	最大内存缓存容量	`100mb`	人类可读的大小（例如 `100mb`、`1gb`）
`performance.requestCompression.enabled`	为大负载的客户端请求（例如设置或聊天保存）启用 gzip 压缩	`false`	`true`、`false`
`performance.requestCompression.minPayloadSize`	触发压缩的最小负载大小。设为 0 则无论大小对所有请求都进行压缩	`256kb`	人类可读的大小（例如 `256kb`、`1mb`）
`performance.requestCompression.maxPayloadSize`	压缩的负载大小硬上限。设为 0 则允许压缩任意大小	`8mb`	人类可读的大小（例如 `8mb`、`16mb`）
`performance.requestCompression.timeout`	请求压缩的超时时间（毫秒）	`4000`	正整数

缓存清理配置

需要 localhost 或启用了 HTTPS 的域名，否则不会生效！

设置	说明	默认值	允许的值
`cacheBuster.enabled`	在首次加载或上传图片文件后清理浏览器缓存	`false`	`true`、`false`
`cacheBuster.userAgentPattern`	仅对匹配指定正则模式的用户代理清理缓存。示例：`'firefox'`（不区分大小写）。	`''`	任何有效的正则字符串

缩略图配置

设置	说明	默认值	允许的值
`thumbnails.enabled`	启用缩略图生成	`true`	`true`、`false`
`thumbnails.quality`	JPEG 缩略图质量	`95`	0-100
`thumbnails.format`	缩略图的图像格式	`jpg`	`jpg`、`png`
`thumbnails.dimensions.bg`	背景缩略图尺寸	`[160, 90]`	包含两个数字的数组（宽度、高度）
`thumbnails.dimensions.avatar`	头像缩略图尺寸	`[96, 144]`	包含两个数字的数组（宽度、高度）
`thumbnails.dimensions.persona`	人格缩略图尺寸	`[96, 144]`	包含两个数字的数组（宽度、高度）

备份配置

设置	说明	默认值	允许的值
`backups.common.numberOfBackups`	要保留的备份数量	`50`	任何正整数
`backups.chat.enabled`	启用自动聊天备份	`true`	`true`、`false`
`backups.chat.checkIntegrity`	在保存前校验聊天文件的完整性	`true`	`true`、`false`
`backups.chat.throttleInterval`	备份节流间隔（毫秒）	`10000`	任何正整数
`backups.chat.maxTotalBackups`	要保留的最大聊天备份总数	`-1`	任何正整数或 -1
`backups.allowFullDataBackup`	允许用户创建其数据的完整备份归档	`true`	`true`、`false`

扩展配置

设置	说明	默认值	允许的值
`extensions.enabled`	启用 UI 扩展	`true`	`true`、`false`
`extensions.autoUpdate`	自动更新扩展（需扩展清单启用）	`true`	`true`、`false`
`extensions.models.autoDownload`	启用自动模型下载	`true`	`true`、`false`
`extensions.models.classification`	用于分类的 HuggingFace 模型 ID	`"Cohee/distilbert-base-uncased-go-emotions-onnx"`	有效的模型 ID
`extensions.models.captioning`	用于图像描述的 HuggingFace 模型 ID	`"Xenova/vit-gpt2-image-captioning"`	有效的模型 ID
`extensions.models.embedding`	用于嵌入的 HuggingFace 模型 ID	`"Cohee/jina-embeddings-v2-base-en"`	有效的模型 ID
`extensions.models.speechToText`	用于语音转文本的 HuggingFace 模型 ID	`"Xenova/whisper-small"`	有效的模型 ID
`extensions.models.textToSpeech`	用于文本转语音的 HuggingFace 模型 ID	`"Xenova/speecht5_tts"`	有效的模型 ID

服务器插件

设置	说明	默认值	允许的值
`enableServerPlugins`	启用服务器端插件	`false`	`true`、`false`
`enableServerPluginsAutoUpdate`	启动时尝试自动更新服务器插件	`true`	`true`、`false`

Git 配置

Git 后端说明

auto - 优先使用系统二进制程序，失败时回退到内置引擎
system - 使用 simple-git 的系统 git 二进制程序
builtin - 使用 isomorphic-git 的内置引擎

设置	说明	默认值	允许的值
`git.backend`	用于插件/扩展仓库操作的 Git 后端	`auto`	`auto`、`system`、`builtin`

API 集成设置

OpenAI 配置

设置	说明	默认值	允许的值
`promptPlaceholder`	空提示词的默认消息	`"[Start a new chat]"`	任何字符串
`openai.randomizeUserId`	为 API 调用随机化用户 ID	`false`	`true`、`false`
`openai.captionSystemPrompt`	用于描述补全的系统消息	`""`	任何字符串

MistralAI 配置

设置	说明	默认值	允许的值
`mistral.enablePrefix`	启用回复预填充。前缀会在响应中回显	`false`	`true`、`false`

Ollama 配置

设置	说明	默认值	允许的值
`ollama.keepAlive`	模型保活时长（秒）	`-1`	`-1`（无限期）、`0`（立即卸载）、正整数
`ollama.batchSize`	控制生成请求的 "num_batch"（批大小）参数	`-1`	`-1`（模型默认值）、正整数

Claude 配置

重要提示！

请谨慎使用，并且仅在提示词前缀是静态的、不会在请求之间变化时使用。{{random}} 宏、世界书、向量、摘要等很可能会使缓存失效，结果只是把钱浪费在缓存未命中上。服务商可能对缓存有最小提示词大小的要求。其行为可能不可预测，无法提供任何保证，请查阅 API 文档。

参见：提示词缓存

设置	说明	默认值	允许的值
`claude.enableSystemPromptCache`	启用系统提示词缓存	`false`	`true`、`false`
`claude.cachingAtDepth`	启用消息历史缓存	`-1`	`-1`（禁用）、`0` 或正整数
`claude.extendedTTL`	使用 1 小时 TTL 替代默认的 5 分钟。注意这也会增加请求成本。	`false`	`true`、`false`
`claude.enableAdaptiveThinking`	为受支持的模型（Opus 4.6+）启用自适应思考。禁用以强制使用旧版思考模式（带思考预算）。参见：自适应思考	`false`	`true`、`false`

Google Gemini 配置

设置	说明	默认值	允许的值
`gemini.apiVersion`	API 端点版本（仅 AI Studio）	`v1beta`	`v1beta`、`v1alpha`
`gemini.thoughtSignatures`	向请求添加思维签名（如果可用）。仅适用于 Gemini 3 及以上版本	`true`	`true`、`false`
`gemini.enableSystemPromptCache`	启用系统提示词的缓存（仅 OpenRouter）	`false`	`true`、`false`
`gemini.image.personGeneration`	参见：https://ai.google.dev/gemini-api/docs/imagen#imagen-configuration	`allow_adult`	`dont_allow`、`allow_adult`、`allow_all`

DeepL 配置

设置	说明	默认值	允许的值
`deepl.formality`	翻译的正式程度级别	`"default"`	`"default"`、`"more"`、`"less"`、`"prefer_more"`、`"prefer_less"`