配置手册#
ThinkWatch Core 只读一个文件:config.yaml。本文逐项说明其中每个字段的作用、默认值、可选值,以及改动如何进入正在运行的进程。在服务器上运行 core、由桌面应用远程管理,见在服务器上运行 core。
本文的字段表由代码生成,与代码不一致时测试失败。表中列出的字段,就是程序实际读取的字段。
文件位置#
| 平台 | 默认位置 |
|---|---|
| macOS、Linux | ~/.thinkwatch/config.yaml |
| Windows | %APPDATA%\ThinkWatch\config.yaml |
THINKWATCH_HOME 替换整个目录;--config <路径> 为单条命令指定文件。core 的其余数据也在这个目录里:请求数据库(data.db)、概览「最近一年」所用的逐小时用量合计(usage.db,请求数据库重建时保留,不随请求记录的保留期删除)、配置的备份(history/)、下载的价目表(model_prices.json),以及本地控制通道的 socket 文件(twcore.sock;Windows 上是回环端口,记录在 control.port 中)。目录只有所有者可访问(0700),配置文件权限为 0600:其中以明文保存密钥。
这两项权限就是这份文件在本机上的全部保护:挡得住其他用户,挡不住以同一用户身份运行的程序。这样的程序能读到文件里的每一把密钥,也能用其中的控制通道密钥经控制通道修改配置。出站脱敏不改变这一点:它保护的是请求带出本机的内容,不是磁盘上的文件。显示配置时给控制通道密钥打码,是为了让经控制通道的写入改不了它(见 listen.control),而不是对本机程序隐藏它;上游密钥和网关密钥按原样显示。
脱敏的例外值(security.redact.exceptions)以每个值不加盐的 SHA-256 保存。能读到这份文件的人不难还原它:手机号这样的短值,逐个试遍所有号码即可从哈希得出原值。文件里本就以明文保存上游密钥,哈希并没有多泄露什么;但它会随导出、同步和备份带走,因此只把不敏感的值列为例外。请求数据库不保存任何命中值的哈希:安全日志「列为例外」所用的哈希只在内存中保留最近 20,000 条,core 重启后即清空。
工具调用审查为这个目录内置了一条规则 thinkwatch-data:工具调用的路径或命令指向上述默认位置之一,或服务器上的 /var/lib/thinkwatch、/etc/thinkwatch 时记录下来,enforce 下切断响应。这样模型无法被诱导去读取这些密钥、改写约束它自己的防护。只是提到这个路径(例如在正在编辑的文档里)不算。THINKWATCH_HOME 指向别处时,可以在 security.inspect_tools 里为那个路径加一条自定义规则。
没有配置文件时,twcore serve 会写入一份初始配置;twcore init 也可以按需生成。两者生成的内容如下:
version: 1
listen:
control:
key: 6629…753d # 自动生成
clients:
- name: default
key: tw-… # 自动生成
这已是一份完整、合法的配置。其中还没有上游,因此控制面照常运行,请求会得到「尚未配置上游」的错误。加上一个上游即可转发:
providers:
- name: anthropic
base_url: https://api.anthropic.com
key: ${ANTHROPIC_API_KEY}
读取规则#
- **本文没有的字段名一律是错误。**把
port写成prot时,不会被悄悄忽略、让网关在默认端口上起来;整份配置被拒绝,错误信息指出那个字段。 - **默认值不写进文件。**没写的字段取下表中的默认值。应用和命令行只在取值不同于默认值时才写入字段,因此文件里出现的都是有人做出的选择。
${VAR}读取环境变量,适用于标注「可写${VAR}」的字段:上游密钥、请求头的值、代理密码。取值来自 core 进程的环境,在发送请求时读取;变量未设置时,该上游的请求失败,错误信息指出变量名。在 systemd 下,这个环境就是 unit 的EnvironmentFile。- **名字即引用。**规则、策略组、密钥按名字引用上游、策略组、路由和价目表。指向不存在的名字,在加载时就报错,而不是成为一条永不命中的规则。在应用里改名时,所有引用在同一次写入中一起修改。以
__开头的名字保留给内置项。 version是格式版本,目前为1。版本更高的文件出自更新的 twcore,整份拒绝。
改动如何生效#
修改配置有三种途径:桌面应用、twcore config … 命令、用编辑器直接修改文件。三者走同一条路径。core 监视配置文件,保存后一秒内重新加载,无需重启。
新版本要通过以下每一关才会换入:
- 能按 YAML 解析。
- 符合结构:字段名已知,类型正确。
- 自洽:名字不重复、引用都能找到、正则能编译、CIDR 写法正确。
- 能据此建立运行时对象。
任何一关失败,原有配置继续服务,错误信息说明失败在哪一关、哪个位置。写错一个字不会让网关停下。在保存出合法版本之前,桌面应用会一直显示这次拒绝。
listen.gateway 的改动同样即时生效:core 打开新的监听;打不开时(例如端口被占用)保留原监听并报告原因。保留期限的改动在下一次每小时的清理时生效。
两方同时修改时(应用和手工编辑),后写入的一方因版本不一致被拒绝,不会覆盖先写入的内容。
备份、导出与导入#
配置每改动一次,配置文件旁边的 history/ 目录中就留下一个版本:一个配置包(.twconfig),连同插件和应用的通用偏好,并记录来源(应用、命令行、外部编辑、导入、恢复、同步)。保留最近 10 个版本;凭据轮换不生成版本。版本中的控制面密钥一律打码。
twcore check # 只校验配置,不启动任何服务
twcore config show # 打印当前配置及其版本
twcore backup list # 列出备份版本,最新的在前
twcore backup restore 1792315800000 --dry-run # 恢复会改动什么
twcore backup restore 1792315800000 # 恢复到某个版本
twcore export -o all.twconfig # 把全部配置导出为配置包
twcore export --providers relay --no-secrets --encrypt -o relay.twconfig
twcore import all.twconfig --dry-run # 导入会做什么
twcore config set /listen/gateway/port 8790 --int
恢复时保留本机设置(监听、控制面密钥、保留期限、同步设置)、ChatGPT 的登录,以及本机已接管的客户端正在使用的网关密钥。导入时加入本机没有的项目,与本机不同的项目逐项选择处理方式(--on-conflict 一次指定全部)。配置包不含本机设置与 ChatGPT 登录;未指定 --no-secrets 时其中以明文保存密钥,除非指定 --encrypt(口令在终端输入,或取自环境变量 TWCORE_PASSPHRASE)。以不含密钥的配置包覆盖本机项目时,只有目的地不变(协议、主机与端口,AWS 区域,OAuth 令牌端点,所走的出站代理,代理的地址)才沿用本机的密钥;目的地变了的、改名导入的上游以停用状态导入,填入密钥后再启用。
这些命令直接操作文件,因此 core 没有运行时也能使用,而那往往正是最需要恢复的时候;配置完全无法读取时,恢复把整个版本写回,控制面密钥保持现在的值。正在运行的 core 会像对待其他保存一样接收这些改动。
twcore config set <路径> <值> 修改文件中已经写出的一个值。路径中的列表项按其 name 定位(/providers/anthropic/base_url);数字表示下标(/routes/0/rules/1/to)。值默认按字符串写入,--int、--bool、--null 另作指定。写入前先校验结果。要添加文件中还没有的字段,请直接编辑文件。
网关写回的凭据#
有一种写入不是由人发起的。上游的 OAuth token 端点换发新的 refresh token 后,旧的随即作废,因此网关会把新 token(以及 access token 和过期时间)写回 providers[].oauth。只改这几个值,注释和排版保持原样。
字段参考#
每张表列出一节的全部字段。「默认值」一栏为「—」表示不写就没有这个字段,其含义见说明。
顶层#
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
version | 整数 | 必填 | 文件格式的版本,目前只有 1。更大的数字说明文件出自更新的 twcore,整份拒绝,不按一知半解的方式读。 |
listen | 对象,见 listen | — | 网关和控制通道在哪里监听。 |
clients | 对象列表,见 clients[] | [] | 网关密钥。至少要有一把;twcore init 和首次 twcore serve 会写入一把名为 default 的。 |
providers | 对象列表,见 providers[] | [] | 上游。一个都没有也是合法配置:控制面照常运行,请求得到「尚未配置上游」的错误。 |
proxies | 对象列表,见 proxies[] | [] | 出站代理。在这里声明一次,由 providers[].proxy 按名字引用。 |
pricing | 对象,见 pricing | — | 默认价目表是否定期刷新,以及自定义价目表。 |
web_tools | 对象,见 web_tools | — | 网关执行的搜索与公开网页工具,在 Lite 的「路由 → 辅助请求」中配置。 |
client_probes | 对象,见 client_probes | — | 客户端自行发出的辅助请求(连通性检查、预热、起标题)如何处理。 |
security | 对象,见 security | — | 三项防护。出厂时都处在 observe,不改变、不拒绝任何请求。 |
retention | 对象,见 retention | — | 请求日志保留多久。 |
failover | 对象,见 failover | — | 上游失败后停用多久,以及流式回答的开头最多等多久。 |
aliases | 映射:别名 → 字符串、字符串列表或对象 | {} | 模型别名:同一个模型在各上游的名称合用一个名字,按顺序列出各上游的名称。请求别名时,提供其中任一名称的上游都能服务,发给它的是列表中它提供的第一个名称。别名不能列出别的别名。对象写法接受 models 和 hide_originals(默认 false);隐藏只影响客户端列表,不改变访问权限。 |
groups | 对象列表,见 groups[] | [] | 策略组:多个上游合用一个名字,并规定如何在其中选择。 |
routes | 对象列表,见 routes[] | [] | 路由。一条都不写时,请求按上游的声明顺序故障转移。 |
default_route | 字符串 | — | 未指定路由的密钥走哪条路由。不写:名为 default 的路由;没有这条路由时走内置的故障转移。 |
default_key | 字符串 | — | 没有专用密钥的客户端使用哪一把。不写:名为 default 的那把,没有则取第一把。这把密钥不能停用。 |
plugins | 对象列表,见 plugins[] | [] | 脚本插件,按运行的顺序。由应用安装,每个插件的代码和设置是本文件旁边的一个文件。 |
sync | 对象,见 sync | — | 多设备同步。属于本机设置:配置包和其他设备不会带走它,恢复备份时保留当前值。不写:不同步。 |
listen#
core 在哪里接受连接。连接分两种:客户端发送请求的 AI 网关,以及桌面应用和 twcore 命令使用的控制通道。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
gateway | 对象,见 listen.gateway | — | AI 网关,即客户端发送请求的地址。 |
control | 对象,见 listen.control | — | 控制通道,即桌面应用和 twcore 命令连接 core 的途径。其中有控制密钥,因此每份配置都有这一节。 |
listen.gateway#
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
bind | loopback | all | 网卡名 | IP 地址 | loopback | loopback 只有本机;all 所有网卡;网卡名(en0、eth0)每隔几秒重新解析,地址变了也能跟上,网卡暂时不在时先只监听 127.0.0.1,出现后再补上;写死的 IP 地址在地址变化后失效。绑定单张网卡时同时监听 127.0.0.1。 |
additional | 字符串列表 | [] | 额外监听的网卡名或固定 IP,与网关共用端口和来源白名单。保留本机回环;主绑定设为回环时停用所有额外监听。某张网卡离线不影响其余可用监听。仅本机监听时应清空此列表。 |
port | 整数 | 8788 | 网关的 TCP 端口。 |
allow_from | 字符串列表 | [10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7] | 本机以外允许连接的来源,写 CIDR 网段或单个地址。本机始终放行。[] 表示只有本机;放行所有来源要明确写 0.0.0.0/0。 |
bind 超出本机范围时,由 allow_from 决定允许谁连接。网关不提供 TLS:只在可信的网络中开放,或放在隧道、VPN 之后。
listen:
gateway:
bind: all
port: 8788
allow_from: [192.168.1.0/24]
listen.control#
控制通道供桌面应用,以及同一台机器上的 twcore config、twcore control-key 与 core 通信。本地通道是数据目录中的 socket 文件(Windows 上是回环端口);除非启用 remote,控制通道不开任何网络端口。
每条控制连接,无论本地还是远程,都以一次握手开始,证明双方都持有 key(Noise_NNpsk0_25519_ChaChaPoly_BLAKE2s:密钥作为预共享密钥,每条连接协商新的会话密钥,通信内容加密)。不使用证书。不持有密钥的一方无法完成第一条握手消息。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
key | 字符串 | 自动生成 | 控制密钥:64 个十六进制字符(32 字节)。所有控制连接,无论本地还是远程,都要证明持有这把密钥。缺失时 twcore serve 在开始监听前写入一把;格式不对的配置整份拒绝。用 twcore control-key 查看,twcore control-key --rotate 更换。 |
remote | 对象,见 listen.control.remote | — | 供另一台机器上的桌面应用连接的网络端口。它是本地通道之外额外开的,不取代本地通道。 |
key 缺失时,由 twcore serve 在控制通道开始监听之前写入;twcore init 生成的配置也带有它。凡是显示配置或写入备份的地方,这个字段一律打码;把打码值原样存回时保留原值。密钥缺失或格式不对(不是 64 个十六进制字符)时整份配置无效,因此无法把它换成一把容易猜到的短密钥。
twcore control-key # 显示密钥,用于粘贴到桌面应用
twcore control-key --rotate # 更换密钥;已连接的应用需要重新连接
两条命令都在运行 core 的机器上执行。
listen.control.remote#
供另一台机器上的桌面应用连接的网络端口。它在本地通道之外额外开启,因此这里写错(端口被占用、allow_from 把自己挡在外面)也不会把本机锁在门外:twcore config 和本机应用照常可用。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
enabled | 布尔 | false | 是否监听远程端口。不写或 false:不为控制面开任何网络端口。twcore remote enable / twcore remote disable 切换它;运行中的 core 在一秒内跟上。 |
bind | loopback | all | 网卡名 | IP 地址 | all | 监听哪张网卡,写法同 listen.gateway.bind。 |
port | 整数 | 必填 | TCP 端口。没有固定默认值:twcore init 和 twcore remote enable 写出这一节时随机写入 20000 到 32000 之间的一个端口(不会和网关相同)。不能是 0,也不能和网关端口相同。 |
allow_from | 字符串列表 | [10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7] | 允许连接的来源,写法同 listen.gateway.allow_from,但本机不会自动放行(本机有本地通道)。其他来源的连接在握手之前关闭,不回任何字节;收窄名单时,已经连着、不再放行的连接也随即断开。同一来源一分钟内握手失败 5 次,之后一分钟不理它。 |
listen:
control:
key: 9f2c…e41a # 64 个十六进制字符
remote:
enabled: true
bind: all
port: 23483 # 随机生成,在生成这一节时写入
allow_from: [192.168.1.0/24]
经远程端口的连接无论应用如何请求,都不能做三件事:关闭 core(它由 systemd 管理)、修改 listen.control(它进来的那扇门)、生成诊断包(诊断包会写在服务器上)。握手限时 5 秒;同一来源一分钟内握手失败 5 次,封禁一分钟。
clients#
网关密钥,即 Claude Code、Codex 等客户端向网关发送的密钥。密钥即身份:并发上限、模型范围、路由都按密钥设置。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | 字符串 | 必填 | 密钥的名字,不能重复。路由规则用 when.client 匹配它。 |
key | 字符串 | 必填 | 客户端发送的密钥(放在 x-api-key 或 Authorization: Bearer 中)。生成的密钥以 tw- 开头,以免被误认作上游的密钥。不能重复。 |
max_concurrent | 整数 | — | 用这把密钥同时进行的请求数上限,超出的排队等待。不写:不限。0 会被拒绝。 |
allow | 字符串列表 | — | 这把密钥可用的模型,写模型 ID 或通配(claude-*)。写上游模型名,列有它的别名一并可用;写别名只放行别名。不写:全部模型。[]:一个都不给。 |
route | 字符串 | — | 这把密钥的请求走哪条路由。不写:default_route。 |
client | 字符串 | — | 这把密钥是为哪个客户端生成的(claude-code、codex 等),由桌面应用接管客户端时写入。一个客户端最多一把。 |
disabled | 布尔 | false | 拒绝使用这把密钥的所有请求,密钥本身保留。 |
limits | 对象列表,见 clients[].limits[] | — | 用量上限:每分钟、每小时、每天、每周或每月的请求数、token 数或费用。请求要通过每一条。不写:不限。 |
clients:
- name: default
key: tw-a3f9c8d1e5b2h7k4m6n8p2q4
- name: build-server
key: tw-q8r2s4t6u8v2w4x6y8z2a4b6
max_concurrent: 4
allow: [claude-sonnet-*]
route: cheap
clients[].limits#
一把密钥的用量上限:每分钟、每小时、每天、每周或每月最多多少个请求、多少 token、多少美元。 每一条只数其中一种;一把密钥可以有好几条,请求要通过每一条。
minute、hour 是滚动的:最近 60 秒、最近 60 分钟;写了 every 就是几个这样的单位,
{ per: hour, every: 5 } 是最近 5 小时。用满之后,下一个空位在
failover.wait_secs(默认 120 秒)之内空出来,请求就等它;等不到就拒绝。之后若还要等
上游,用的是同一段时间里剩下的部分。day、week、month 按 twcore 所在机器的
本地时区算,在零点、周一零点、每月一号零点重新开始;用满之后,到重新开始之前的请求一律拒绝。
机器换了时区时,当前这一天、这一周、这个月的用量按新的时区从请求记录里重新加起来。
被拒的请求收到 HTTP 429,错误格式和客户端自己的一致,写明是哪把密钥、哪一条上限、用了多少、
什么时候重置;流量列表里也有这一条。没有发到上游的请求不计入任何上限:被规则、内容过滤或
上限拒绝的,以及因为上游都已达到 max_concurrent 而被退回的。费用按每个请求记下的费用算,所以没有价格的模型、
billing: free 的上游算 0。还在进行的请求先按输入的估算计入,记下之后换成实际用量。
重启之后,这一天、这一周、这个月的用量从请求记录里重新加起来,所以请求记录要留够那一期:
设了按天的上限时 retention.row_days 至少 1,按周至少 7,按月至少 31;按分钟、按小时的
上限从零开始。
Responses 的 WebSocket 连接上,每个 response.create 各算一个请求:带着各自的用量和费用记下,
按这些上限检查;被拒的那一个收到 response.failed,连接保持不断。Realtime 的连接
(/v1/realtime)整条算一个请求:连上时按这些上限检查,这条连接上所有回答的 token 和费用在
断开时计入。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
per | minute | hour | day | week | month | 必填 | 按多长一段时间算。minute、hour 是滚动的(最近 60 秒、最近 60 分钟,或者 every 个这样的单位);day、week、month 在本地时间的零点、周一零点、每月一号零点重新算。 |
every | 整数 | — | 滚动窗口有几分钟、几小时:{per: hour, every: 5} 是最近 5 小时。minute 取 1 到 60,hour 取 1 到 24;day、week、month 不能写。不写:1。 |
requests | 整数 | — | 最多这么多个请求。数 token 的请求、网关自己答的、没有发到上游的不算。 |
tokens | 整数 | — | 最多这么多 token:未命中缓存的输入、写入缓存的和输出。 |
cost | 数字 | — | 最多花这么多美元,按每个请求记下的费用算;至少 0.01。没有价格的模型、billing: free 的上游算 0。 |
cache_reads | 布尔 | false | 把读取缓存的 token 也算进去。只有 tokens 上限能写。 |
clients:
- name: build-server
key: tw-q8r2s4t6u8v2w4x6y8z2a4b6
limits:
- { per: minute, requests: 30 }
- { per: day, cost: 5 }
- { per: month, tokens: 20000000, cache_reads: true }
providers#
上游,即请求被转发到的接口。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | 字符串 | 必填 | 上游的名字,不能重复,也不能和策略组同名。以 __ 开头的名字保留给内置项。 |
base_url | 字符串 | 必填 | 接口地址,http:// 或 https://,按服务商文档写到版本段为止(https://api.anthropic.com、https://api.openai.com/v1)。Bedrock 写所在区域的推理地址:https://bedrock-runtime.<区域>.amazonaws.com。地址中不能有反斜杠,主机前不能写用户名或密码(凭据写在 key 或 headers 中)。 |
key | 字符串,可写 ${VAR} | — | API 密钥,放进协议规定的请求头:x-api-key(Anthropic)、Authorization: Bearer(OpenAI,以及 Bedrock API Key)、x-goog-api-key(Gemini)。上游不需要密钥、或凭据写在 headers 里时不写。不能和 oauth、aws 同时写。 |
headers | 请求头名 → 值的映射 | {} | 额外的请求头,按书写顺序发送;值可以用 ${VAR},配置了 oauth 时可以用 {{access_token}}。最多 32 个。HTTP 或网关管理的请求头(host、content-length、connection 等)不能设置。 |
oauth | 对象,见 providers[].oauth | — | OAuth 凭据:用 refresh token 换取 access token。与 key 二选一。 |
aws | 对象,见 providers[].aws | — | Bedrock 上游的 AWS 访问密钥,写在这里或者从 AWS 的 profile 读:每个请求用它们签名(SigV4)。与 key(Bedrock API Key)二选一。 |
protocol | anthropic | openai-chat | openai-responses | gemini | chatgpt | bedrock | — | 上游的接口格式。不写:官方地址按 base_url 识别(Bedrock 的推理地址是 bedrock),其余按 anthropic 处理。 |
reasoning_history | auto | reasoning-content | reasoning | content-blocks | disabled | auto | Chat 请求的思考历史格式:auto 使用已验证的端点默认值,其余同来源保留原生内容块和既有的 reasoning_content 字段惯例。兼容网关可显式选择 reasoning-content、reasoning、content-blocks 或 disabled。模型级设置优先。带签名的历史不发送到来源或格式不兼容的上游。 |
reasoning_history_group | 字符串 | — | 带签名的 Chat 历史的显式兼容组。不写时按上游、模型及配置凭据隔离;只有确认后端相互接受签名时才共享组。空白视为未设置。 |
forward_client_identity | 布尔 | false | 同时发送客户端自己的身份:它的 User-Agent、x-app 和 originator 等身份请求头,以及请求体中的身份字段(如 metadata.user_id)。发送的都是客户端的原值,不做伪造。关闭时请求使用 ThinkWatch 的 User-Agent,不带客户端身份。用于只接受特定客户端的上游(Kimi For Coding、百炼 Coding Plan、只允许官方客户端的中转站)。chatgpt 不可用。 |
proxy | 字符串 | direct | direct;system,即 core 进程环境变量 HTTPS_PROXY、HTTP_PROXY、ALL_PROXY 中的代理;或 proxies 中某一项的名字。 |
on_proxy_fail | fail | direct | fail | 代理不可用时:请求失败(fail),或改为直连(direct)。 |
models | 字符串列表 | [] | 手动添加的模型,写确切的 ID:上游能服务、却没有列进清单的模型。它们和上游列出的模型一起算作这家提供的模型,上游不提供清单时就是全部:出现在 /v1/models 里,相应的请求也会路由到这家。models_only 照样适用。不支持通配,不能重复,每项最多 256 个字符。 |
models_only | 字符串列表 | — | 只使用这家的这些模型,写 ID 或通配。范围外的模型不出现在模型列表里,也不会路由到这家。不写:全部。写空列表会被拒绝,暂停使用请用 disabled。 |
billing | per-token | free | per-token | per-token:费用为用量乘以所选价目表中的单价,订阅账号同样如此。free:费用记为 0。 |
pricing | 字符串 | — | pricing.sheets 中某张价目表的名字。不写:默认价目表。 |
model_specs | 映射: 模型 ID → providers[].model_specs.* | {} | 手写这家上游某些模型的上下文窗口、输出上限、会不会推理、收不收图,按模型 ID 完全匹配。写了就优先于价目表,用于价目表里没有或写错的模型。 |
max_concurrent | 整数 | — | 同时发给这家的请求最多几个,取值 1 到 1000。满了的时候,留在这家的对话等空位,别的请求换下一家;等多久见 failover.wait_secs。不写:不限。 |
min_speed | 对象,见 providers[].min_speed | — | 流式回答生成得太慢时结束它:从第一个 token 起每秒看一次,最近 window_secs 秒的平均速度低于 tokens_per_sec 时,回答以一条客户端会重试的错误结束(503,Anthropic 格式的客户端收到 overloaded_error),这家记一次失败,计入 failover.failures_to_pause。中途较长的停顿和摘要式的推理不算进平均速度,停顿由无响应超时处理。不是流式的回答不管。不写:不管。 |
limits | 对象列表,见 providers[].limits[] | — | 这家上游的用量上限,照着它自己的限额写:每几分钟、每几小时、每天、每周或每月的请求数、token 数或费用。每一条都有余量才往这家发。滚动窗口满了,请求换下一家或者等它空出来;天、周、月用满了,到下一期之前请求换下一家。不写:不限。 |
disabled | 布尔 | false | 不参与路由,模型也不出现在模型列表里;配置原样保留。 |
balance | auto | off | openrouter | deepseek | moonshot | sub2api | newapi | thinkwatch | auto | 从哪里读这家上游的余额,用它自己的密钥、走它自己的代理:openrouter、deepseek、moonshot、sub2api、newapi(New API 和 One API)或 thinkwatch(ThinkWatch 企业网关)。auto:OpenRouter、DeepSeek、Moonshot 按 base_url 识别;其他地址(Anthropic、OpenAI、Gemini 的官方地址除外)询问一次它是不是 Sub2API、ThinkWatch 企业网关或 New API 中转站,结果只保存在内存中。off:不读余额。ChatGPT、Z.ai 账号和 Bedrock 不读余额,与这里写什么无关。 |
signed_in | zai | bigmodel | — | key 来自哪一家的账号登录:zai(Z.ai)或 bigmodel(BigModel)。在桌面端登录账号时写入,在桌面端更换密钥时删除。不影响请求的发送方式。不写:密钥是手动填写的。 |
auto 也能从未知 Chat 兼容接口的结构化 HTTP 400/422 校验错误中学习:只识别
messages[n].reasoning_content 或 messages[n].reasoning 的 extra_forbidden,
不会据此猜另一种格式。网关从原始历史重新编码,只省略明确被拒绝的普通字段,再次执行
出站脱敏;每个逻辑请求最多修复一次,与推理强度、自动缓存断点和封存历史的修复共用预算。
显式设置和签名历史不参与自动协商,要求回传思考历史的协议配置也不自动省略。
含糊的报错、SSE 错误、超时或已经开始生成后的错误都不触发协商。
只有调整后被接受的请求才会留下学习记录。缓存只在内存中,最多 1024 条、24 小时过期, 按上游及解析后的凭据、模型、实际接口路径、工具和思考设置隔离;重载配置或重启后清空。 学习记录完全由程序内部管理,正常使用无需额外设置。高级配置仍可显式覆盖上游或模型的历史格式。
凭据有四种写法:key,放进协议规定的请求头;oauth,用 refresh token 换取 token;aws,Bedrock 上游签名请求用的访问密钥;headers,用于上游自有的鉴权方式。headers 可以和其余几种同时使用,但不能再设置已经承载凭据的那个请求头。
providers:
- name: anthropic
base_url: https://api.anthropic.com
key: ${ANTHROPIC_API_KEY}
- name: relay
base_url: https://relay.example.com/v1
protocol: openai-chat
headers:
X-Relay-Token: ${RELAY_TOKEN}
proxy: office
models_only: [gpt-4.1*, o3]
pricing: relay-discount
max_concurrent: 4
- name: local
base_url: http://127.0.0.1:11434/v1
protocol: openai-chat
billing: free
一家上游提供的模型,是它在 /v1/models 列出的模型(Bedrock 为所在区域的模型清单),加上 models 中手动添加的模型。上游的清单常常不全:中转站只列出一部分,账号类的后端对旧版本客户端隐藏新模型。写进 models 的模型出现在 /v1/models 里,可以写进别名、在规则中指定、在密钥的 allow 中放行,也和列出的模型一样路由到这家;models_only 对两者同样适用。上游不提供清单时,models 就是它的全部模型;两者都没有时,它不列出任何模型,但任何模型的请求仍可能路由到这家。
每个请求只带请求本身和上游需要的请求头,客户端的其他信息一律不发:凭据和 headers 中写的请求头、ThinkWatch 自己的 User-Agent,以及客户端请求中该上游协议使用的请求头(Anthropic 为 anthropic-*,OpenAI 为 Idempotency-Key 和 X-Client-Request-Id,Gemini 没有)。客户端自动填写的身份字段(如 Claude Code 的 metadata.user_id)从请求体中去掉。只接受特定客户端的上游,打开 forward_client_identity。
请求转换为 Anthropic 格式、或转给 Bedrock 上的 Claude 时,客户端自己没有标出缓存位置的,由网关标出可以缓存的位置。Codex 等使用 OpenAI 或 Gemini 格式的客户端无从标注:这两家自动缓存重复的提示,Anthropic 只缓存标出的部分。标注的位置是工具列表末尾、系统提示末尾和最后两条用户消息的末尾,最多四处,缓存时长为默认的五分钟。两条用户消息中靠前的那一处正是上一个请求结束的位置,因此每一轮都能读回上一轮写入的缓存,这部分按缓存价而不是全额输入价计费。缓存的写入和读取按价目表中的缓存单价计费。自带标注的请求(如 Claude Code 的)保持原样,按上游自身格式直接转发的请求不做改动。
Bedrock 上只为 AWS 列出支持提示缓存的 Claude 模型标注:Claude 3.7 Sonnet、Claude 3.5 Sonnet v2,以及 4.5 起的所有 Claude,包括尚未列出的更新版本。更早的模型(如 Claude 3 Haiku、Sonnet 4、Opus 4.1)不标注。上游拒绝这些标注时,网关去掉标注重新发送一次,此后在 core 重启之前不再为这家上游的该模型标注。
ChatGPT 账号上游(protocol: chatgpt)只接受桌面应用登录得到的凭据,不能手写。不支持 Claude 和 Google 的订阅登录,请使用 API 密钥。
生成请求默认按客户端要求的流式或非流式模式发送。已知的后端要求优先:ChatGPT 账号后端继续使用既有的仅流式处理。其他后端在 HTTP 400、422 或 501 的 JSON API 错误中拒绝请求时,网关可以在同一家上游试一次另一种模式,不要求特定错误码或英文文案。历史字段、推理强度和缓存断点的已知修复优先,与模式试探共用每个请求最多一次的自动修复预算,并受请求等待期限约束。明确指向其他参数的错误、可识别的鉴权、额度、限流、过载或超时错误,以及带重试提示的响应不试探。因此,无法识别原因的其他请求错误也可能多一次被拒的尝试。
流式回答收齐后返回完整 JSON,整包回答则写成客户端要求的流,后一种仍需等待上游生成完整回答。上游已经成功返回另一种模式的响应时,直接转换,不再重发。试探同样被 HTTP 拒绝、或者回答开始之前失败时,保留原始错误,两次尝试的结果都记录下来;原始服务端错误仍可故障转移到下一家上游。已经收到的部分回答不重放,成功响应流中的错误也不发起模式试探。
只有完整成功的回答才留下可用模式偏好,在内存中记 30 分钟,按上游账号、模型、API 和工具、推理等请求选项隔离。使用缓存不会延长过期时间,到期后下个请求重新尝试客户端模式;重载配置会清空,符合试探条件的拒绝会使记住的偏好失效。无需增加上游配置。
原生协议请求要求多个候选、对数概率或非文本输出时不自动切换,避免当前响应转换器丢失这些字段。WebSocket 请求不参与协商。
有的中转站和账号同时只接受几个请求,多出来的直接拒绝。max_concurrent 让网关守住这个数:请求发出时占用这家的一个位置,回答完整交给客户端、或者客户端断开时归还。这家满了的时候,为复用提示缓存而留在这家的对话等空位,别的请求直接换下一家。最多等多久由 failover.wait_secs 决定。等待不算失败,这家不会因此停用。只计算 token 数的请求不占位置。Responses 的 WebSocket 连接上,每个 response.create 从发出起占一个位置,直到它的回答结束,密钥的 max_concurrent 也一样;空闲的连接不占位置。
providers[].min_speed#
自部署的模型偶尔会掉到每秒几个 token 并一直这样。内容一直在来,无响应超时不会触发,而重试
通常就能恢复正常速度。写了 min_speed,流式回答从第一个 token 起每秒判断一次:最近
window_secs 秒的平均速度低于 tokens_per_sec 时,网关以一条客户端可以重试的错误结束回答
(503:Anthropic 格式的客户端收到 overloaded_error,Responses 格式收到带 server_error 的
response.failed,Gemini 格式收到 UNAVAILABLE),并断开和上游的连接。
速度和应用里显示的实时速度同一个算法:正文、推理和工具参数,按估算并用上游报的实数校准。
中途 5 秒以上(判定时长不到 20 秒时为它的四分之一以上)的停顿不算在内,由无响应超时处理;扣掉
之后剩下的不到窗口的一半时,这一秒不判断。停着的时候(一秒多没有新内容)不判断:工具参数常常
停一下再一下子到。以摘要形式隔几秒到一段的推理(Anthropic、Gemini、Bedrock 的推理,Responses
的推理摘要)进行着的时候不判断,这段时间之后也不算;原样流出来的推理(OpenAI Chat 的
reasoning_content、Responses 的 reasoning_text)和正文一样判断。第一个 token 之前的等待、
回答说完之后、不是流式的回答都不判断,不带 alt=sse 的 Gemini 流也不判断。
请求记为失败并记下当时的速度,已经生成的部分照常计费,这家记一次失败,计入
failover.failures_to_pause;有别的候选时,重试的请求先去别家。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
tokens_per_sec | 整数 | 必填 | 最低生成速度,单位 token/秒,和应用里显示的实时速度同一个算法。取值 1 到 1000。 |
window_secs | 整数 | 20 | 按最近多少秒的平均速度判断。第一次判断在第一个 token 之后这么久。取值 5 到 120。 |
providers:
- name: local-vllm
base_url: http://127.0.0.1:8000/v1
min_speed: { tokens_per_sec: 15, window_secs: 20 }
providers[].limits#
一家上游的用量上限,照着这家自己的限额写:每几分钟、每几小时、每天、每周或每月最多多少个
请求、多少 token、多少美元。写法和密钥的 limits 一样;一家上游可以有好几条,每一条都有
余量才往这家发。
每一次发到这家的尝试算一个请求,成功失败都算,这家回 429 的不算。token 和费用算在得到回答 的那一次尝试上。只计算 token 数的请求不算。还在进行的尝试按输入的估算计入,记下之后换成 实数。
minute、hour 的窗口满了,这家和并发数满了一样被跳过:留在这家的对话等它空出余量,别的
请求换下一家;候选都没有余量时,请求等最先空出来的那一家,最多等一个请求能等的时间(见
failover)。day、week、month 用满之后,到下一期开始之前请求换下一家,不等它。满了
不算失败,这家不会因此停用。重启之后,这一天、这一周、这个月的用量从请求记录里重新加起来,
所以 retention.row_days 要留够那一期,和密钥的一样;分钟、小时的窗口从空的开始。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
per | minute | hour | day | week | month | 必填 | 按多长一段时间算。minute、hour 是滚动的(最近 60 秒、最近 60 分钟,或者 every 个这样的单位);day、week、month 在本地时间的零点、周一零点、每月一号零点重新算。 |
every | 整数 | — | 滚动窗口有几分钟、几小时:{per: hour, every: 5} 是最近 5 小时。minute 取 1 到 60,hour 取 1 到 24;day、week、month 不能写。不写:1。 |
requests | 整数 | — | 最多往这家发这么多个请求。每一次发到了这家的尝试都算,它回 429 的不算;数 token 的请求不算。 |
tokens | 整数 | — | 这家回答的请求最多用这么多 token:未命中缓存的输入、写入缓存的和输出。 |
cost | 数字 | — | 这家回答的请求最多花这么多美元,按每个请求记下的费用算;至少 0.01。没有价格的模型算 0,billing: free 时全都算 0。 |
cache_reads | 布尔 | false | 把读取缓存的 token 也算进去。只有 tokens 上限能写。 |
providers:
- name: relay
base_url: https://relay.example.com
key: sk-relay
limits:
- { per: hour, every: 5, requests: 200 }
- { per: week, cost: 50 }
providers[].oauth#
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
access | 字符串 | — | 当前的 access token。每次刷新后由网关写回;不写则在第一次使用时换取。 |
expires_at | 字符串 | — | access 的过期时间,RFC 3339(UTC),随 token 一起写回。不写:一直用到上游返回 401。 |
refresh | 字符串 | 必填 | Refresh token。token 端点换发新的之后旧的即作废,因此网关会把新的写回本文件。 |
endpoint | 字符串 | 必填 | token 端点的地址。 |
client_id | 字符串 | — | OAuth 客户端 ID,端点需要时填写。 |
client_secret | 字符串 | — | OAuth 客户端密钥,端点需要时填写。 |
refresh_before | 时长(30s、5m、1h) | — | 提前多久刷新。不写或写法无法识别:5m。 |
access token 默认放进协议的鉴权请求头。要放在别处,在 headers 中写出那个请求头,用 {{access_token}} 标出 token 的位置:
oauth:
refresh: ${VENDOR_REFRESH_TOKEN}
endpoint: https://auth.example.com/oauth/token
client_id: my-client
headers:
X-Access: Token {{access_token}}
providers[].aws#
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
access_key_id | 字符串,可写 ${VAR} | — | 访问密钥 ID。与 secret_access_key 一起写;也可以改写 profile。 |
secret_access_key | 字符串,可写 ${VAR} | — | 私有访问密钥。 |
session_token | 字符串,可写 ${VAR} | — | 临时凭证(如 STS 签发的)的会话令牌。过期之后请求会被拒绝,直到换上新的。 |
profile | 字符串 | — | 从 AWS 凭证文件读访问密钥时用的 profile,代替把密钥写在这里:~/.aws/credentials 和 ~/.aws/config,或 AWS_SHARED_CREDENTIALS_FILE、AWS_CONFIG_FILE 指定的文件,读的是 core 所在机器上的。文件变了会重新读。 |
region | 字符串 | — | 签名用的区域。不写:取 base_url 里的区域,这时 base_url 必须是标准的推理地址。base_url 是 VPC 端点或代理时必须写。 |
Bedrock 上游有两种认证方式。Bedrock API Key 写在 key 中,以 Authorization: Bearer 发送。AWS 访问密钥写在 aws 中,或者用 aws.profile 从 AWS 凭证文件里的某个 profile 读取:每个请求在请求体定稿之后用它们签名(SigV4),密钥本身不会发送。写在配置中的密钥可以用 ${VAR} 从环境变量读取。profile 读的是 core 所在机器上的文件,文件变了会重新读,因此把临时密钥刷新进 ~/.aws/credentials 的工具不需要重启 core。获取凭证时不执行任何命令,因此经 IAM Identity Center 登录(aws sso login)、运行 credential_process 或扮演角色的 profile 无法使用,请改为导出它们生成的密钥。
providers:
- name: bedrock
base_url: https://bedrock-runtime.us-east-1.amazonaws.com
key: ${AWS_BEARER_TOKEN_BEDROCK}
- name: bedrock-keys
base_url: https://bedrock-runtime.eu-west-1.amazonaws.com
aws:
access_key_id: ${AWS_ACCESS_KEY_ID}
secret_access_key: ${AWS_SECRET_ACCESS_KEY}
session_token: ${AWS_SESSION_TOKEN}
- name: bedrock-profile
base_url: https://bedrock-runtime.us-west-2.amazonaws.com
aws:
profile: dev
请求转换为 Converse 格式。模型清单取自所在区域的控制面:可按需调用的基础模型、AWS 预设的推理配置(us.anthropic.claude-…),以及账号自己创建的应用推理配置(按调用时使用的 ARN 列出)。列出清单需要 bedrock:ListFoundationModels 和 bedrock:ListInferenceProfiles 权限;没有这两项权限时请求照常转发,可以在 models 中手动列出模型。使用 VPC 端点或代理时,在 base_url 中写它的地址,在 aws.region 中写区域;模型清单也向该地址获取。
providers[].model_specs#
模型发现默认读取上游报告的能力,上游缺少的已知规格由价目表补充。在这里按上游、按真实模型 ID(完全匹配)覆盖缺失或错误的值。每项至少填写一个规格;上下文窗口和输出上限必须是正整数。
手动值也用于上下文容量判断,以及补充转换到 Anthropic 请求时缺少的输出上限。模型发现按手动值、上游报告、价目表的顺序取值。推理档位没有价目表回退:在 reasoning_effort 中填写支持的档位和可选默认值。非空档位自动表示支持推理,空列表明确表示不可调,移除覆盖恢复自动获取。对外提供的档位取所有路由候选的交集,并受实际协议转换能力限制。参见 Codex 模型发现。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
reasoning_history | auto | reasoning-content | reasoning | content-blocks | disabled | — | 覆盖这个模型的请求侧思考历史格式。不写时遵从上游设置;与模型会不会推理是两项独立能力。 |
context_window | 整数 | — | 上下文窗口,即一次请求最多输入多少 token。不写:取价目表的。 |
max_output_tokens | 整数 | — | 一次回答最多输出多少 token。不写:取价目表的。 |
reasoning | 布尔 | — | 这个模型会不会推理。此开关不声明可调档位,档位由 reasoning_effort 指定。false 不能与非空手动档位并存。不写:使用已知元数据或价目表。 |
reasoning_effort | 对象,见 providers[].model_specs.*.reasoning_effort | — | 整组覆盖推理档位。不写时自动使用上游元数据;supported_levels 空列表明确表示不可调。非空档位自动表示支持推理。 |
image_input | 布尔 | — | 这个模型收不收图。模型列表里以 input_modalities 给出。不写:取价目表的;价目表也没写时,列表里不给这一项。 |
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
supported_levels | 字符串列表 | 必填 | 支持的档位:minimal、low、medium、high、xhigh、max、ultra,不可重复。空列表明确表示不可调;协议转换可能进一步限制可用档位。 |
default_level | minimal | low | medium | high | xhigh | max | ultra | — | 必须属于 supported_levels。不写时在最终可用集合中优先 medium,否则最低档;手动档位不混用上游默认值。 |
providers:
- name: relay
base_url: https://relay.example.com/v1
protocol: openai-chat
model_specs:
glm-5-air: { context_window: 128000, max_output_tokens: 16384 }
claude-sonnet-4-5: { context_window: 1000000 }
proxies#
出站代理。不同上游需要的代理往往不同,因此没有全局开关:由每个上游用 proxy 选择。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | 字符串 | 必填 | providers[].proxy 引用的名字。direct 和 system 是内置的。 |
type | socks5 | socks5h | http | https | socks5h | socks5h 把域名交给代理解析;socks5 先在本地解析。http 和 https 是 HTTP 代理。 |
addr | 字符串 | 必填 | 代理的 host:port。 |
auth | 对象,见 proxies[].auth | — | 代理需要时填写用户名和密码。 |
proxies[].auth#
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
user | 字符串 | 必填 | 用户名。 |
pass | 字符串,可写 ${VAR} | 必填 | 密码。 |
proxies:
- name: office
type: http
addr: proxy.example.com:3128
auth:
user: alice
pass: ${PROXY_PASSWORD}
on_proxy_fail 默认为 fail:静默改为直连会让请求走一条意料之外的路径,而使用者仍以为请求经过了代理。
pricing#
一次请求的费用为用量乘以模型单价。单价来自默认价目表(LiteLLM 的公开数据集,程序内置一份,每天联网刷新),或来自上游选用的自定义价目表。单价变动只影响此后的请求,不改变已记录请求的费用。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
auto_update | 布尔 | true | 每天联网刷新一次默认价目表,保存为 config.yaml 旁边的 model_prices.json;此前以及离线时使用内置于程序中的价目表。 |
sheets | 对象列表,见 pricing.sheets[] | [] | 自定义价目表。上游用 providers[].pricing 选用。 |
pricing.sheets#
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | 字符串 | 必填 | 价目表的名字,不能重复。 |
multiplier | 数字 | 1 | 作用于默认价目表的全部单价,包括缓存和长上下文单价。 |
models | 映射: 模型 ID → pricing.sheets[].models.* | {} | 单独定价的模型。它们取代默认价目表中该模型的单价,不乘倍率。 |
pricing.sheets[].models#
单价以每百万 token 的美元计,与厂商价格页上的写法一致。每个字段都要写明,计价时不做任何推算。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
input | 数字 | 必填 | 每百万输入 token 的美元价格。 |
output | 数字 | 必填 | 每百万输出 token 的美元价格。 |
cache_read | 数字 | 必填 | 每百万缓存读取 token 的美元价格。 |
cache_write_5m | 数字 | 必填 | 每百万写入 5 分钟缓存 token 的美元价格。 |
cache_write_1h | 数字 | 必填 | 每百万写入 1 小时缓存 token 的美元价格。 |
input_above_200k | 数字 | — | 单次请求的输入(连同缓存读写)超过 200K token 后的输入单价。与 output_above_200k 同时写或都不写;缓存单价仍按上面写的算。 |
output_above_200k | 数字 | — | 单次请求的输入(连同缓存读写)超过 200K token 后的输出单价。 |
pricing:
sheets:
- name: relay-discount
multiplier: 0.8
models:
claude-sonnet-4-5-thinking:
input: 3
output: 15
cache_read: 0.3
cache_write_5m: 3.75
cache_write_1h: 6
client_probes#
客户端发出的请求中,有一部分并非出自使用者:连通性检查、预热、会话标题、话题检测、建议。每一类要么在本地应答(intercept,不向上游发送任何内容),要么转发(forward)。转发的请求和普通请求一样经过路由规则,并带着自己的类别,规则可以用 when.intent 匹配。默认只拦下拦了也不会少任何东西的那几类。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
health_check | intercept | forward | intercept | 连通性检查(max_tokens: 1)。默认在本地应答,不影响任何功能。 |
warmup | intercept | forward | intercept | 预热请求。默认在本地应答。 |
titling | intercept | forward | forward | 为会话起标题的请求。默认转发:拦下后所有会话都会是同一个标题。 |
topic_detect | intercept | forward | forward | 话题检测。默认转发。 |
suggestion | intercept | forward | forward | 建议。默认转发。 |
security#
三项防护,对所有上游一视同仁。每一项都有 mode:off、observe(检测并记录,不改变任何行为)、enforce(按每条规则的动作处理)。出厂时三项都是 observe。每条规则各有动作:出站脱敏替换为占位符或只记录,工具调用审查切断响应或只记录,内容过滤拒绝、删除、替换或只记录。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
redact | 对象,见 security.redact | — | 出站脱敏(应用里叫「密钥与隐私」):请求发出前,按每条规则把其中正文(消息、系统提示、推理、工具调用的参数和结果、工具说明)里的凭据和个人信息替换为占位符,或只记录;id、模型名等协议字段原样发出。 |
inspect_tools | 对象,见 security.inspect_tools | — | 工具调用审查(应用里叫「危险命令」):模型返回的工具调用中出现危险命令时切断响应。 |
content | 对象,见 security.content | — | 内容过滤:调用方发送的内容中、或模型回答的正文中出现指定的词、写法或字符(包括隐藏字符)时,按规则拒绝请求、删除或替换命中的内容,或只记录。 |
security.redact#
请求发出前,在请求中写出的正文里查找凭据和个人信息:系统提示、各角色的消息(包括之前的回答)、推理、工具调用的参数、工具结果和工具说明。enforce 下将规则找到的内容替换为占位符,回答中重复出现时再换回原值;action: record 的规则找到的内容原样发送,只作记录。协议要求原样保留的值(如 id、类型、角色、工具名、模型名、签名)一律不查,字段名、图片、文件、配置项以及网关不认作正文的部分也不查。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
mode | off | observe | enforce | observe | off 不检测(应用里叫「关闭」);observe 检测并记录,不改变任何行为(「监控」);enforce 检测并按每条规则的动作处理(「开启」)。 |
enable | 字符串列表 | [] | 打开出厂时关着的内置规则,按 id。 |
disable | 字符串列表 | [] | 关掉内置规则,按 id。 |
actions | 映射: 内置规则 id → placeholder | record | {} | 内置规则在 enforce 下的动作,只写与出厂不同的(email: record)。placeholder 将值替换为占位符后发送,回答中出现该占位符时还原为原值;record 原样发送,记录命中。 |
custom | 对象列表,见 security.redact.custom[] | [] | 自定义规则:匹配到的内容和凭据一样替换,或只记录。 |
exceptions | 对象列表,见 security.redact.exceptions[] | [] | 例外值:在任何规则下都不替换、不记录。只保存哈希,不保存值本身;最多 500 个。保存的凭据不能列为例外:规则为 thinkwatch-saved-secret 的条目可以读入,但不生效。 |
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | 字符串 | 必填 | 日志和应用里显示的名字,也是规则的标识;同一项防护里不能重名。 |
pattern | 字符串 | 必填 | 要查找的文字;match: regex 时为正则表达式。 |
match | contains | regex | contains | contains:按原样查找 pattern,.、* 等字符没有特殊含义。regex:pattern 是正则表达式。 |
case_sensitive | 布尔 | false | 区分大小写。默认不区分:ABC 和 abc 都会匹配。 |
label | 字符串 | SECRET | 占位符名称:匹配到的内容替换为 <<TW_名称_序号>>,每个名称各自编号。只能使用大写字母、数字和下划线,以字母开头,最多 24 个字符。 |
action | placeholder | record | placeholder | enforce 下将匹配到的内容替换为占位符(placeholder),或只记录、原样发送(record)。 |
disabled | 布尔 | false | 停用这条规则,规则本身留在文件里。 |
内置规则:
| id | 名称 | 出厂 |
|---|---|---|
anthropic-api-key | Anthropic API 密钥 | 开 |
openai-project-key | OpenAI 项目密钥 | 开 |
openai-api-key | OpenAI API 密钥 | 开 |
github-personal-token | GitHub 个人令牌 | 开 |
github-oauth-token | GitHub OAuth 令牌 | 开 |
github-server-token | GitHub 服务器令牌 | 开 |
github-user-token | GitHub 用户令牌 | 开 |
github-fine-grained-token | GitHub 细粒度令牌 | 开 |
slack-bot-token | Slack 机器人令牌 | 开 |
slack-user-token | Slack 用户令牌 | 开 |
slack-app-token | Slack 应用令牌 | 开 |
aws-access-key-id | AWS 访问密钥 ID | 开 |
aws-temporary-key-id | AWS 临时访问密钥 ID | 开 |
google-api-key | Google API 密钥 | 开 |
google-oauth-token | Google OAuth 令牌 | 开 |
gitlab-token | GitLab 令牌 | 开 |
stripe-live-key | Stripe 生产密钥 | 开 |
stripe-restricted-key | Stripe 受限密钥 | 开 |
npm-token | npm 令牌 | 开 |
digitalocean-token | DigitalOcean 令牌 | 开 |
sendgrid-key | SendGrid 密钥 | 开 |
private-key | 私钥 | 开 |
jwt | JWT | 开 |
conn-string-password | 连接串口令 | 开 |
cn-resident-id | 居民身份证号 | 开 |
bank-card | 银行卡号 | 开 |
email | 邮箱地址 | 关 |
cn-mobile-phone | 中国大陆手机号 | 关 |
internal-ip | 内网地址 | 关 |
internal-domain | 内部域名 | 关 |
thinkwatch-saved-secret | ThinkWatch 中保存的密钥 | 开 |
openai-service-key | OpenAI 服务账号与管理密钥 | 开 |
openrouter-key | OpenRouter API 密钥 | 开 |
xai-key | xAI API 密钥 | 开 |
groq-key | Groq API 密钥 | 开 |
huggingface-token | Hugging Face 令牌 | 开 |
replicate-token | Replicate 令牌 | 开 |
perplexity-key | Perplexity API 密钥 | 开 |
bedrock-api-key | Amazon Bedrock API 密钥 | 开 |
fireworks-key | Fireworks AI API 密钥 | 开 |
cerebras-key | Cerebras API 密钥 | 开 |
langsmith-key | LangSmith API 密钥 | 开 |
langfuse-secret-key | Langfuse 私密密钥 | 开 |
pinecone-key | Pinecone API 密钥 | 开 |
tavily-key | Tavily API 密钥 | 开 |
minimax-key | MiniMax API 密钥 | 开 |
zhipu-api-key | 智谱 API 密钥 | 开 |
qianfan-api-key | 百度千帆 API 密钥 | 开 |
sk-compat-key | OpenAI 兼容格式 API 密钥 | 开 |
github-refresh-token | GitHub 刷新令牌 | 开 |
gitlab-other-token | GitLab 其他令牌 | 开 |
pypi-token | PyPI 令牌 | 开 |
rubygems-token | RubyGems 令牌 | 开 |
clojars-token | Clojars 令牌 | 开 |
docker-hub-token | Docker Hub 令牌 | 开 |
artifactory-key | JFrog Artifactory 密钥 | 开 |
databricks-token | Databricks 令牌 | 开 |
sentry-token | Sentry 令牌 | 开 |
grafana-token | Grafana 令牌 | 开 |
postman-key | Postman API 密钥 | 开 |
aws-other-key-id | AWS 其他访问密钥 ID | 开 |
alibaba-access-key-id | 阿里云 AccessKey ID | 开 |
tencent-secret-id | 腾讯云 SecretId | 开 |
volcengine-access-key-id | 火山引擎 AccessKey ID | 开 |
azure-ad-client-secret | Azure AD 客户端密码 | 开 |
digitalocean-other-token | DigitalOcean 其他令牌 | 开 |
cloudflare-origin-ca-key | Cloudflare Origin CA 密钥 | 开 |
vault-token | HashiCorp Vault 令牌 | 开 |
terraform-token | Terraform Cloud 令牌 | 开 |
doppler-token | Doppler 令牌 | 开 |
pulumi-token | Pulumi 令牌 | 开 |
heroku-key | Heroku API 密钥 | 开 |
flyio-token | Fly.io 令牌 | 开 |
supabase-key | Supabase 密钥 | 开 |
age-secret-key | age 私钥 | 开 |
onepassword-token | 1Password 服务账号令牌 | 开 |
stripe-webhook-secret | Stripe Webhook 签名密钥 | 开 |
shopify-token | Shopify 令牌 | 开 |
twilio-api-key | Twilio API 密钥 | 开 |
brevo-key | Brevo API 密钥 | 开 |
slack-other-token | Slack 其他令牌 | 开 |
linear-key | Linear API 密钥 | 开 |
notion-token | Notion 令牌 | 开 |
atlassian-token | Atlassian API 令牌 | 开 |
auth-header-credential | 请求头中的凭据 | 开 |
command-line-password | 命令行中的口令 | 开 |
url-token | URL 中的令牌 | 开 |
bot-webhook | 机器人 Webhook | 开 |
telegram-bot-token | Telegram 机器人令牌 | 开 |
config-assignment | 配置文件中的密钥赋值 | 开 |
crypto-mnemonic | 助记词 | 开 |
crypto-wif-key | WIF 私钥 | 开 |
crypto-extended-key | 扩展私钥 | 开 |
uuid | UUID/紧凑标识符 | 开 |
crypto-hex-key | 裸钱包私钥/32 字节哈希 | 开 |
crypto-solana-key | Solana 密钥对 | 开 |
crypto-sui-key | Sui 私钥 | 开 |
crypto-stellar-key | Stellar 私密种子 | 开 |
crypto-xrp-seed | XRP 账户种子 | 开 |
crypto-address | 区块链账户/扩展公钥 | 开 |
crypto-secret-field | 字段中的钱包机密 | 开 |
exchange-credential | 交易 API/签名鉴权凭证 | 开 |
crypto-keystore | 钱包密钥库/密文 | 开 |
crypto-rpc-key | 区块链 RPC 地址凭证 | 开 |
cn-resident-id-15 | 15 位旧身份证号 | 关 |
passport-mrz | 护照机读区 | 开 |
cn-passport | 中国护照号 | 关 |
hk-macau-taiwan-id | 港澳台身份证号 | 关 |
mainland-travel-permit | 港澳台往来内地通行证号 | 关 |
us-ssn | 美国社会安全号 | 关 |
uk-nino | 英国国民保险号 | 关 |
sg-nric | 新加坡 NRIC / FIN | 关 |
kr-rrn | 韩国居民登录号 | 关 |
jp-my-number | 日本个人番号 | 关 |
in-aadhaar | 印度 Aadhaar 号码 | 关 |
br-cpf | 巴西 CPF | 关 |
iban | 国际银行账号(IBAN) | 开 |
cn-landline | 中国大陆固定电话 | 关 |
intl-phone | 国际电话号码 | 关 |
cn-address | 中国大陆详细地址 | 关 |
geo-coordinates | 精确坐标 | 关 |
cn-license-plate | 中国大陆车牌号 | 关 |
vin | 车辆识别代号(VIN) | 关 |
imei | IMEI | 关 |
mac-address | MAC 地址 | 关 |
public-ip | 公网 IP 地址 | 关 |
labeled-name | 带字段名的姓名 | 关 |
labeled-address | 带字段名的住址 | 关 |
labeled-birth-date | 带字段名的出生日期 | 关 |
labeled-account | 带字段名的银行账号 | 关 |
labeled-health | 带字段名的健康信息 | 关 |
uuid 出厂开启:匹配带连字符的 8-4-4-4-12 或连续 32 位十六进制 UUID,不区分大小写、不限制版本。订单号、追踪 ID 和同形的紧凑哈希也替换;更长的标识符不截取,JSON 数字仍保留为数字。监控模式只记录命中。单凭 UUID 的形状不会触发工具的「凭据发往陌生主机」检查;用户保存的凭据仍按具体值检查。
cn-resident-id、bank-card、email、cn-mobile-phone 查找的是个人信息而不是凭据。前两条出厂开启,只认结构上核对得上的:
cn-resident-id:18 位的中华人民共和国居民身份证号码。前两位须是省级行政区划代码,出生日期须是 1900 年 1 月 1 日至今天之间的真实日期,末位须是正确的校验码(ISO 7064 MOD 11-2)。15 位的旧号码不认。bank-card:卡号。开头和位数须属于银联、Visa、Mastercard、American Express、JCB、Discover 或 Diners Club,并通过 Luhn 校验;连续书写,或四位一组、以单个空格或单个连字符分隔均可(American Express 另认 4-6-5,Diners Club 另认 4-6-4)。Stripe、Braintree、Adyen 公开的测试卡号不认。
email 和 cn-mobile-phone 出厂关闭:它们没有可核对的结构,代码和文档中形似的内容很多。
email:邮箱地址,域名至少两段、最后一段为两个以上的字母。URL 中的用户名(https://user@host)和icon@2x.png这类文件名不认。cn-mobile-phone:中国大陆手机号,11 位数字,以1开头、第二位为3至9,前后不紧挨其他数字。
夹在更长的一串字母或数字中间的号码不认;请求体中以 JSON 数值写出的号码(例如工具调用的参数)也不认,替换它会使请求体不再是合法的 JSON。占位符写明原来是什么(<<TW_ID_NUMBER_1>>、<<TW_CARD_NUMBER_1>>、<<TW_EMAIL_1>>、<<TW_PHONE_1>>),安全日志中号码只显示最后四位,邮箱只显示第一个字和域名。自定义规则替换为 <<TW_SECRET_1>>,写了占位符名称(label)时用它。
例外值:某个值反复被规则认出、但并不敏感(测试用的固定值、文档里的示例密钥)时,可以写进 exceptions。规则照常工作,只有这个值在任何规则下、observe 和 enforce 两档都不处理。每一项只保存值的 SHA-256,不保存值本身,因此可以随导出、同步和备份一起带走。(不加盐的 SHA-256,见文件位置)。应用从安全日志或粘贴的值加入;手写时 sha256 是值在消息中原本的样子的哈希,不含两边的引号和 JSON 转义。只有最近的日志记录可以从日志列为例外:每个值的哈希只在内存中保留最近 20,000 条、不跨重启;由几处重叠的命中合成的一段不能列为例外。更早的记录既没有按钮也不显示「例外」标签,可以粘贴该值手动加入。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
sha256 | 字符串 | 必填 | 值的 SHA-256,64 个小写十六进制字符。请求体中的转义先解开:哈希按值本身计算。 |
masked | 字符串 | '' | 加入时显示的值,打码方式与安全日志相同。 |
rule | 字符串 | '' | 最先认出该值的规则:内置规则的 id 或自定义规则的名称。手动添加且没有规则认出的值为空。 |
added_at | 整数 | 0 | 加入的时间,Unix 纪元以来的毫秒数。 |
security.inspect_tools#
按规则检查模型返回的工具调用。enforce 下命中处置为 cut 的规则时切断响应,客户端拿不到可执行的完整调用。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
mode | off | observe | enforce | observe | off 不检测(应用里叫「关闭」);observe 检测并记录,不改变任何行为(「监控」);enforce 检测并按每条规则的动作处理(「开启」)。 |
enable | 字符串列表 | [] | 打开出厂时关着的内置规则,按 id。 |
disable | 字符串列表 | [] | 关掉内置规则,按 id。 |
actions | 映射: 内置规则 id → cut | record | {} | 内置规则在 enforce 下的处置,只写与出厂不同的(rm-rf-root: record)。 |
custom | 对象列表,见 security.inspect_tools.custom[] | [] | 自定义规则,按工具调用的参数匹配。 |
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | 字符串 | 必填 | 日志和应用里显示的名字,也是规则的标识;同一项防护里不能重名。 |
pattern | 字符串 | 必填 | 正则表达式。 |
action | cut | record | record | enforce 下切断响应(cut),或只记录(record)。 |
disabled | 布尔 | false | 停用这条规则,规则本身留在文件里。 |
内置规则:
| id | 名称 | enforce 下出厂处置 |
|---|---|---|
curl-pipe-sh | 下载即执行 | cut |
base64-decode-exec | 解码后执行 | cut |
exfil-env | 外发环境变量 | cut |
exfil-credentials | 外发凭据文件 | cut |
exfil-credentials-reversed | 外发凭据文件(动词在前) | cut |
ssh-key-read | 读取私钥或云凭据 | cut |
secret-to-unknown-host | 凭据发往陌生主机 | cut |
thinkwatch-data | 读写 ThinkWatch 自己的数据 | cut |
write-startup-item | 写入启动项 | cut |
crontab-install | 安装定时任务 | cut |
rm-rf-root | 删除主目录或根目录 | record |
chmod-777 | 开放全部写权限 | record |
upload-file-to-host | 上传本地文件到外部主机 | record |
security.content#
调用方发送的内容中(用户消息及其中的工具结果,不含系统提示和模型自己的回答)出现的词、写法或字符;scope 含 response 的自定义规则还检查模型回答的正文。每条规则按关键词(contains)、正则(regex)或码位(codepoints,仅用于请求)匹配,并写明 enforce 下的动作:block 拒绝请求(仅用于请求),strip 删除全部命中的内容后发出,replace 将全部命中的内容替换为规则的 replacement 后发出,record 只记录。请求中删除或替换之后会再检查一遍:被隐藏字符拆开的关键词,删掉隐藏字符后照样命中;替换上去的文字不再检查。回答中删除或替换的内容不会送达客户端,请求记录中保存客户端实际收到的回答。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
mode | off | observe | enforce | observe | off 不检测(应用里叫「关闭」);observe 检测并记录,不改变任何行为(「监控」);enforce 检测并按每条规则的动作处理(「开启」)。 |
enable | 字符串列表 | [] | 打开出厂时关着的内置规则,按 id。 |
disable | 字符串列表 | [] | 关掉内置规则,按 id。 |
actions | 映射: 内置规则 id → block | strip | replace | record | {} | 内置规则在 enforce 下的动作,只写与出厂不同的。内置规则只检查请求;replace 将命中的内容替换为 ***。 |
custom | 对象列表,见 security.content.custom[] | [] | 自定义规则,每条可检查请求、回答或两者。 |
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | 字符串 | 必填 | 日志和应用里显示的名字,也是规则的标识;同一项防护里不能重名。 |
pattern | 字符串 | 必填 | 关键词;match: regex 时为正则表达式;match: codepoints 时为码位(U+200B, U+E0000–U+E007F)。 |
scope | 列表,每项是 request | response | [request] | 检查对象:request 为调用方发送的内容(用户消息及其中的工具结果);response 为客户端看到的回答正文,包含 Codex apply_patch 等自由格式工具的输入,不含工具调用与思考过程。两项可同时列出。流式回答不整体缓冲,只暂缓发送可能构成命中的末尾片段:「包含」规则不超过最长匹配内容的字符数减一,正则规则最多 256 个字符;超过此长度的正则命中,其起始部分可能已送达客户端。enforce 下有删除内容的规则时,再多暂缓同样多的字符:删除处前后拼接成的文字重新检查,直到不再有命中。嵌套层数超出暂缓范围的命中,其起始部分可能已送达客户端,其余部分删除。enforce 下有检查回答的规则删除或替换内容时,流式回答中的 logprobs 一律去掉,非流式回答在正文有改动时去掉:logprobs 按 token 重复了正文。检查回答的规则不能用 block,也不能按 codepoints 匹配。 |
match | contains | regex | codepoints | contains | contains:正文按原样包含 pattern,.、* 等字符没有特殊含义。regex:pattern 是正则表达式。codepoints:正文中出现 pattern 所列码位或码位范围内的字符,多个之间用逗号分隔;仅用于请求。 |
case_sensitive | 布尔 | false | 区分大小写。默认不区分:ABC 和 abc 都会匹配。码位不受此项影响。 |
action | block | strip | replace | record | record | enforce 下拒绝请求(block,仅用于请求)、删除命中的内容后发出(strip)、将命中的内容替换为 replacement 后发出(replace),或只记录(record)。删除处前后拼接成的文字重新检查,直到不再有命中;替换上的文字不再检查;回答中锚定正文或行首尾的正则(^、$、\A、\z)只检查一次。替换不可还原,回答中不换回原文。 |
replacement | 字符串 | "***" | 动作为 replace 时替换成的文字。 |
disabled | 布尔 | false | 停用这条规则,规则本身留在文件里。 |
内置规则:
| id | 名称 | 分组 | 出厂 | enforce 下出厂处置 |
|---|---|---|---|---|
unicode-tags | Unicode 标签字符 | invisible | 开 | strip |
bidi-controls | 双向控制符 | invisible | 开 | strip |
zero-width | 零宽字符 | invisible | 关 | strip |
private-use | 私用区字符 | invisible | 关 | strip |
ignore-previous-instructions | 要求忽略先前的指令 | injection | 开 | block |
ignore-all-previous | 要求忽略之前的全部内容 | injection | 开 | block |
disregard-your-instructions | 要求无视指令 | injection | 开 | block |
jailbreak | 越狱 | injection | 关 | block |
dan | DAN | injection | 关 | block |
developer-mode | 开发者模式 | injection | 关 | block |
you-are-now | 重新设定身份 | persona | 关 | block |
new-persona | 新的人设 | persona | 关 | record |
act-as | 要求扮演角色 | persona | 关 | record |
pretend-to-be | 要求假装身份 | persona | 关 | record |
system-prompt | 索取系统提示词 | persona | 关 | record |
reveal-your-instructions | 要求透露指令 | persona | 关 | record |
what-are-your-rules | 询问规则 | persona | 关 | record |
base64-wall | 长串 Base64 | persona | 关 | record |
zh-ignore-previous | 要求忽略先前的指令(中文) | chinese | 关 | block |
zh-forget-your | 要求忘记指令(中文) | chinese | 关 | block |
zh-do-not-follow | 要求不要遵循(中文) | chinese | 关 | block |
zh-you-are-now | 重新设定身份(中文) | chinese | 关 | block |
zh-role-play | 要求扮演角色(中文) | chinese | 关 | record |
zh-reveal-your | 要求透露指令(中文) | chinese | 关 | record |
zh-system-prompt | 系统提示词(中文) | chinese | 关 | record |
zh-jailbreak | 越狱(中文) | chinese | 关 | block |
invisible(隐藏字符)一组匹配人看不见、模型读得到的字符。Unicode 标签字符(U+E0000–U+E007F)和双向控制符(U+202A–U+202E、U+2066–U+2069)出厂开启;零宽字符(U+200B–U+200D、U+2060、U+FEFF)和私用区字符(U+E000–U+F8FF、U+F0000–U+FFFFD、U+100000–U+10FFFD)出厂关闭,表情符号、波斯文和图标字体也会用到它们。四条在 enforce 下都删除命中的字符。
security:
redact:
mode: enforce
enable: [internal-ip]
custom:
- name: employee-id
pattern: 'EMP-\d{6}'
label: EMPLOYEE
inspect_tools:
mode: enforce
content:
mode: enforce
enable: [zero-width]
custom:
- name: project-x
pattern: project-x
action: strip
- name: codename
pattern: polaris
scope: [request, response]
action: replace
replacement: "[codename]"
retention#
设两个期限,是因为两类数据的体积相差三个数量级:一条请求的正文有几十 KB,一条请求记录只有几百字节。字节上限用于应对用量突增。
每份请求和响应正文最多保存 4 MiB,更长的只保存开头。正文写入磁盘前已去掉凭据和个人号码:enforce 下保存的请求带着发给上游的占位符,脱敏规则(security.redact)认出的其他内容一律打码保存,off 时也一样。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
body_days | 整数 | 7 | 请求和响应正文保留的天数。 |
row_days | 整数 | 90 | 每条请求记录(时间、模型、用量、费用)保留的天数。 |
body_max_bytes | 整数 | 5368709120 | 正文最多占用的字节数,超出时从最早的日期开始删除。默认 5 GiB。 |
failover#
上游失败后会停用一段时间,接下来的请求直接交给下一个候选。停用多久取决于上游
给出的原因:余额不足要等充值,额度用完要等到上游说的重置时刻。只有一个候选的请求
不受影响。Responses 的 WebSocket 连接上,每个 response.create
在这里和一个请求一样算:第一段内容到达之前因为上游出错而失败的,算作一次失败;上游
拒绝或连不上的连接也一样。
流式回答在第一段内容交给客户端之前,上游在流里报的错误和错误状态码一样,会把 请求换到下一个候选。
候选都试过之后,最后一个候选在内容交给客户端之前暂时出错的 —— 500、502、503、504、529,
流式回答里报的过载或服务端错误,连不上,流在内容之前断了或收尾 —— 请求不把错误交给客户端,
而是等待一段时间后重试。等待 2、4、8 秒,之后每次 16 秒,上下浮动不超过两成;上游要求等得
更久的(retry-after-ms、Retry-After),按它要求的。每次重试再发给暂时出错的那几个候选,按原来的顺序,停用中的跳过,
都在停用中时照样重试;留在某一家的对话只重试这一家。下一次等待会超出 wait_secs(一个请求
合计最多等的时间)时不再重试,客户端收到最后一次的错误。限流、额度用完、余额不足、凭据被拒、
模型不存在、请求本身的错误、流里报的其他错误、其他 5xx 和无响应超时都不重试,照旧换到下一个
候选。每次重试在请求的尝试链上单列一跳,带着它是
第几次重试和之前等了多久。wait_secs: 0 关闭重试。
上游也可能不出声:收下请求之后一直不发内容,或者发到一半停住。连续
idle_timeout_secs 秒(默认 300)没有内容,网关就不再等它。计时从请求发给这家上游的
那一刻起,等空位的时间不算在内;每来一段内容重新计时:正文、推理、工具调用都算,心跳
(SSE 注释、Anthropic 的 ping、空块、Responses 的 response.in_progress)不算,所以
只保持连接、不出内容的上游同样会超时。整包(非流式)的回答从发出算到整份回来。
- 还没有内容交给客户端时,这家上游记一次失败(和 5xx 一样计入
failures_to_pause), 尝试链上这一跳的结果是idle_timeout,请求换到下一个候选。在此之前上游的回答不交给 客户端,下一家从头开始回答。没有候选了,客户端收到它自己格式的超时错误(504)。 客户端收的是流、请求还能在wait_secs之内重试时,最后一个候选的流同样暂存;否则它的 流边收边交给客户端,响应开始之后再超时,回答以一条错误事件收尾。最后一个候选的整包 回答一律边收边交。 - 流式回答最多暂存 15 秒。到时还没有内容,客户端先收到
200和流式响应头,以免它自己 等响应头的时限先到,之后每 15 秒收到一行 SSE 注释(: keep-alive);Gemini 的客户端 不发注释。上游的事件照旧暂存到第一段内容,故障转移在同一个200之下照常进行:下一家 的流从头开始;没有候选了,流以客户端格式的错误事件结束,不再是 504。注释不算内容。 - 已经有内容交给客户端时,换一家会重复已经发出的内容,所以不换:回答按客户端的格式 以一条错误事件收尾,请求记为失败。
之后这段对话在这一轮里不再留在这家上游。先思考很久才输出的模型,需要把超时调长。
failover:
idle_timeout_secs: 600
上游回 429(限流)时不停用,而是暂停:上游给出了等待时间的(retry-after-ms、
Retry-After 或错误正文里的等待时间;不到一秒的、retry-after-ms 不到一毫秒的当作没有
给出)暂停那么久,没有给出的按这家连续被限流的次数
暂停 5、10、20、40 秒,之后每次 60 秒;上游回了别的答复就重新计数。暂停最长
rate_limit_max_pause_secs 秒,熔断和 load-balance 都不把它算作失败。收到 429 的
请求换下一个候选,或者等暂停结束,客户端察觉不到。流式回答在内容之前报的限流也按 429
处理;只有请求的最后一个候选、而且这个请求已经不能再等(wait_secs)时,客户端才会收到这个
错误(这家照样暂停)。暂停结束时先放一个请求过去,这家接受了它(流式回答要等到内容开始),其余的请求再
跟上;这个请求没有得到答复、超时,或者遇到这家额度用完,其余的请求也照常发出。暂停只保留
到 twcore 重启为止。
一个请求等暂时不能发的上游合计最多 wait_secs 秒:并发数满了(max_concurrent)的、
回了 429 正在暂停的、到了 minute 或 hour 用量上限的都算。等密钥的 minute、hour
上限和重试之前的等待也算在这段时间里,几样加起来不超过 wait_secs。进行中的对话等它留在的那一家,到时
还没有恢复就换下一家,缓存在那边从头建;新的对话遇到这样的上游直接跳过。用完了天、周、
月用量上限的上游也跳过。没有候选了,请求等最先恢复的那一家;流式回答照上文先收到 200
和保活,连接不会因此断开。都没有恢复,客户端收到 429,Retry-After 和 retry-after-ms
是最先恢复的那一家还要多久;候选全都用完了这一期的,Retry-After 是最早的重置时刻,
x-should-retry 是 false。如果有上游收到过这个请求并且失败了,客户端收到的是那次失败。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
failures_to_pause | 整数 | 3 | 没有说明原因的失败(5xx、连接失败)连续几次后停用这家上游,取值 1 到 100。 |
pause_secs | 整数 | 60 | 这类失败第一次停用的秒数。之后每停用一次翻一倍,直到 max_pause_secs;成功一次后回到这个值。 |
max_pause_secs | 整数 | 600 | 翻倍后的停用上限,单位秒,不小于 pause_secs。 |
no_balance_pause_secs | 整数 | 1800 | 上游报告余额不足时停用的秒数。 |
quota_pause_secs | 整数 | 3600 | 上游报告额度用完、但没有给出重置时间时停用的秒数。给出了重置时间的,停用到那一刻。 |
rate_limit_max_pause_secs | 整数 | 3600 | 上游回 429(限流)后暂停这家的最长秒数。上游给出了等待时间的(retry-after-ms、Retry-After 或错误正文里的等待时间)按它给的暂停;没有给出的,按这家连续被限流的次数退避:5、10、20、40 秒,之后每次 60 秒。暂停不算失败:请求在 wait_secs 之内等这家恢复,熔断也不计入。 |
idle_timeout_secs | 整数 | 300 | 上游多少秒没有发出内容,网关就不再等它。从请求发出的那一刻算起,每来一段内容重新计时:正文、推理、工具调用都算,心跳不算。整包(非流式)的回答从发出算到整份回来。还没有内容交给客户端时,这家上游记一次失败,请求换到下一家;没有下一家了,客户端收到超时错误。已经有内容交给客户端的,回答以一条错误收尾。取值 30 到 3600。 |
wait_secs | 整数 | 120 | 一个请求合计最多等的秒数,从过了密钥自己的 max_concurrent 时算起:等密钥的 minute、hour 上限空出名额,等暂时不能发的上游 —— 并发数满了(max_concurrent)、回了 429 正在暂停、到了这家 minute 或 hour 的用量上限 —— 和上游在内容之前暂时出错(过载、服务端出错、连不上)后重试之前的等待,都算在里面。密钥的上限到时空不出来就拒绝。上游暂时不能发的先换下一家,没有下一家了就等最先恢复的那一家;留在某一家的对话等这一家。到时都没有恢复,客户端收到带 Retry-After 的 429;到时重试仍未成功,客户端收到最后一次的上游错误。0:不等,也不重试。取值 0 到 600。 |
aliases#
模型别名是同一个模型的另一个名称。客户端像请求其他模型一样请求它,每家上游收到的是自己对这个模型的叫法。
aliases:
deepseek-v4.1: DeepSeek-v4.1-flash
claude-sonnet-5:
- claude-sonnet-5
- us.anthropic.claude-sonnet-5-v1:0
- anthropic/claude-sonnet-5
要从客户端模型列表隐藏对应的上游原名,使用对象写法:
aliases:
coding:
models: [provider-model-2026]
hide_originals: true # 可选,默认 false
models 和简单写法一样接受字符串或列表。此选项只影响模型发现(/v1/models、Gemini 列表和 /codex/models);原名请求、单模型查询仍沿用原有权限和路由。先按协议、可用性和密钥权限筛选,再由可用且可见的别名精确隐藏目标原名。别名身份始终保留;多个别名共享目标时,最后一个有效隐藏来源关闭或删除后才恢复原名。修改会热加载;客户端可能缓存模型菜单,需要刷新模型列表。管理目录和权限编辑始终保留完整清单。
- 上游在
models_only范围内提供列出的任一名称,就能服务这个别名,收到的是列表里它提供的第一个名称。能服务同一别名的上游互为备用。 GET /v1/models默认在上游模型旁一并列出别名;上面的选项可隐藏原名,原名调用照常可用。- 别名优先于同名的上游模型:上例中请求
claude-sonnet-5只会发给提供这三个名称之一的上游。要让某家上游继续用自己的同名模型提供服务,把它的名称列进去。 - 密钥的
allow和规则的when.model写上游模型名时,对列有这个名称的别名同样有效;写别名时只对别名有效。 - 上游答的是发给它的那个模型时,回答里的模型名写成客户端请求的名称;答的是别的模型,原样转发。
- 计价和上游体检按发给上游的名称;请求记录保留客户端请求的名称,每次尝试记录实际发出的名称。
- 要把某把密钥的请求发到某家上游的某个模型,用带指定模型的规则(
routes[].rules[].to),不要用别名:别名会改变这个名称对所有客户端的含义。
groups#
策略组让多个上游合用一个名字。规则用 to 把请求交给策略组。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | 字符串 | 必填 | 策略组的名字,不能重复,也不能和上游同名。 |
type | fallback | select | load-balance | url-test | cheapest | fallback | fallback:按顺序取第一个健康的。select:取 selected 指定的那个。load-balance:请求按成员的权重分;进行中的对话留在原来那一家。url-test:按实测从发出请求到回答第一段内容的时间取最快的。cheapest:取输入单价最低的。 |
providers | 列表,每项是字符串或对象,对象见 groups[].providers[] | 必填 | 成员上游的名字,不能是策略组。同一个上游在一个策略组中只出现一次。load-balance 组的成员可以写成 {name, weight}。 |
selected | 字符串 | — | select 类型选中的成员。 |
balance_by | weights | latency | health | latency-health | weights | load-balance 类型用:成员的权重再乘上什么。weights:不乘,只按权重。latency:越快的上游分得越多。health:越少失败的上游分得越多。latency-health:两者都看。其他类型只能是 weights。 |
默认类型为 fallback:单个使用者的机器上没有需要分散的负载。
load-balance 组的成员可以带权重,取值 1 到 100;只写名字的成员权重为 1。权重决定组内请求怎么分:写成 { name: anthropic, weight: 7 } 和 relay 时,每十个请求有七个由官方 API 服务。进行中的对话留在回答它的那一家(见下文),也算进那一家的份额,因此份额靠新对话从哪一家开始来补齐。因失败处于冷却、并发数已满(max_concurrent)、或服务不了某个请求的上游不参与这一次分配,其余成员按各自的权重分。新的 WebSocket 连接也这样分配,算作一个请求;之后在这条连接上发的都交给它连上的那一家。其他类型的策略组不用权重。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | 字符串 | 必填 | 上游的名字。只写名字的成员权重为 1。 |
weight | 整数 | 1 | 成员在 load-balance 组中分到的请求份额,与其他成员的权重成比例。取值 1 到 100。其他类型的策略组只能写 1。 |
groups:
- name: pool
type: load-balance
providers:
- { name: anthropic, weight: 7 }
- relay
无论哪种类型,一段对话都留在上次回答它的那一家上游,让上游缓存着的那部分被再次读取,而不是换一家全价重算。同一轮之内(客户端正在回传工具结果)一律不换;跨轮时,上一次回答读或写了至少 1024 个 token 的 prompt cache、且距今不到五分钟,才继续留下。上游因失败进入冷却时,对话随之放开;故障转移之后接下回答的那一家,就是之后留下的那一家。一轮开始时命中的规则也沿用到这一轮结束:按输入大小或图片分流的规则不会让一轮半路换家,除非输入已经超出规则所指模型的上下文窗口。因此 load-balance 的权重是长期看各家分到的请求的比例:进行中的对话留在原来的上游,也算进那一家的份额。
带着上游加密内容的对话另当别论。OpenAI Responses 把下一轮还要用的内容加密交给客户端,每一轮原样带回(encrypted_content:推理、压缩后的前文、Codex 子代理之间传递的消息),只有加密它的那个账号读得出来。这样的对话一律送回上次回答它的那一家,不论规则现在选中哪一家,配置改过、缓存已凉或隔了一天也一样(记 30 天)。加密的不只是推理时,候选只有那一家:不做故障转移,那一家已从配置中删除时请求被拒绝并说明原因。只加密了推理时,推理可以去掉,其余上游仍作为故障转移的备选。twcore 重启之后不再知道对话由哪一家加密;送到别家而解不开时,失败说明会写明原因,这段对话需要改回原来的上游,或者重新开始。
balance_by 让 load-balance 组再看各上游最近的表现:每个成员的权重乘上一个系数,组内请求按乘出来的结果照上文的方式分。
weights(默认):只按权重。latency:越快的上游分得越多。快慢看典型的从发出请求到回答第一段内容的时间,与url-test使用同一份测量。比组内居中者快一倍的上游,权重乘以四;最多乘以十,最少乘以十分之一。health:越少失败的上游分得越多。依据是最近 30 分钟内的最近 50 次请求:服务器错误、额度或余额用尽、凭据被拒、超时和连接失败算作失败;请求本身导致的错误不算,限流(429)、客户端取消、手动中止、因并发数满了(max_concurrent)或到了用量上限而跳过也不算;超过failover.idle_timeout_secs仍没有内容算作超时。经常失败的上游至少保留权重的二十分之一,仍会偶尔分到请求,以便发现它已经恢复;完全失败的上游照旧由failover暂停。latency-health:两个系数相乘。
快慢只在流式回答上测,从请求发给这家上游的那一刻算起:之前的等待、之前失败的上游都不算在内。因超过 failover.idle_timeout_secs 没有内容而被放弃的上游,按等满的那段时间计。Responses 的 WebSocket 连接上,每个 response.create 在快慢和成败上都算一个请求,快慢从上游开始回答它的那一刻算起。
测量还不够的上游按中等对待。与只按权重时一样,进行中的对话留在原来的上游,差额由新对话补齐。
groups:
- name: 均摊
type: load-balance
balance_by: latency-health
providers:
- { name: 官方, weight: 3 }
- 中转
routes#
一条路由是一组自上而下求值的规则。每把密钥使用其 route 指定的路由;没有指定时用 default_route;再没有时用名为 default 的路由;一条路由都没有时,请求按上游的声明顺序故障转移。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | 字符串 | 必填 | 路由的名字,不能重复。default 是密钥默认使用的那条。 |
rules | 对象列表,见 routes[].rules[] | [] | 自上而下求值;第一条匹配且带有 to 或 deny 的规则决定请求去向。 |
routes[].rules#
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | 字符串 | 必填 | 日志和流量详情中显示的名字。 |
when | 对象,见 routes[].rules[].when | — | 条件,须全部满足。不写:匹配所有请求。 |
to | 字符串,或对象列表,见 routes[].rules[].to[] | — | 上游或策略组的名字;__all__ 表示按声明顺序的全部上游。也可以指定模型:列出上游及发给它的模型,按顺序备用。不能与 when.provider_would_be 同时写。 |
set | 对象,见 routes[].rules[].set | — | 改写请求参数。从所有匹配的规则累积,不只第一条。 |
deny | 字符串 | — | 以这句原因拒绝请求。 |
routes[].rules[].to#
to 写上游或策略组的名称,或者指定模型:一组上游,每家写明发给它的模型,按顺序备用。指定模型原样发出,不经过别名,也不受 set.model 影响;所以即使同名别名指向别处,规则仍能把某把密钥的请求发到某家上游的这个模型。
routes:
- name: default
rules:
- name: Opus 走 Bedrock
when: { model: claude-opus-5 }
to:
- { provider: bedrock, model: us.anthropic.claude-opus-5-v1:0 }
- { provider: anthropic, model: claude-opus-5 }
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
provider | 字符串 | 必填 | 上游的名字,不能是策略组。同一个上游在列表中只出现一次。 |
model | 字符串 | 必填 | 发给这个上游的模型名,原样发出:不经过别名,也不受 set.model 改写。同一条规则里不能再写 set.model。 |
routes[].rules[].when#
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
model | 字符串 | — | 请求的模型,可用通配(claude-opus-*)。写上游模型名,也匹配请求列有它的别名的请求;写别名只匹配请求这个别名的。 |
client | 字符串 | — | 请求所用网关密钥的名字,精确匹配。 |
dialect | 字符串 | — | 客户端使用的接口格式:anthropic、openai-chat、openai-responses、gemini。 |
input_tokens | 比较式(>200k、<=4k、==3) | — | 估算的输入 token 数。 |
max_tokens | 比较式(>200k、<=4k、==3) | — | 请求中的 max_tokens。未写该参数的请求不匹配。 |
tool_count | 比较式(>200k、<=4k、==3) | — | 请求中提供的工具数量。 |
cache | 布尔 | — | 请求是否使用 prompt cache。 |
tools | 布尔 | — | 请求是否带工具。 |
image | 布尔 | — | 请求是否包含图片。 |
thinking | 布尔 | — | 是否开启扩展思考。 |
stream | 布尔 | — | 是否流式返回。 |
intent | 字符串或字符串列表 | — | 客户端的辅助请求:assistant_internal 表示任意一类,也可以写具体的一类(titling)。在 client_probes 中设为 intercept 的类别由本地应答,不会进入路由。 |
time | 字符串或字符串列表 | — | core 所在机器的本地时间落在窗口 [days ]HH:MM-HH:MM 里:mon-fri 09:00-18:00、sat,sun 00:00-24:00、22:00-06:00。写几个窗口满足其一即可。见下文。 |
provider_would_be | 字符串或字符串列表 | — | 路由选中的上游。这类规则在路由完成后求值,只能 set 或 deny,不能写 to。 |
比较式以 >、>=、<、<= 或 == 开头,数字可以带 k 或 m 后缀:">200k"、"<=4k"。不带运算符是错误,不当作相等:单写 "200k" 会被拒绝。
时间窗口写成 [<days> ]<HH:MM>-<HH:MM>,按 core 所在机器在路由那一刻的本地时间求值。<days> 是用逗号分隔的 mon、tue、wed、thu、fri、sat、sun,也可以写 mon-fri、fri-mon(跨过周日绕回去)这样的一段;不写就是每天。大小写不论。时刻是 24 小时制:起点含、终点不含,终点可以写 24:00。终点早于起点的是过夜的窗口,天指窗口开始的那一天:fri 22:00-06:00 从周五 22:00 到周六 05:59。不合这个写法的值在读配置时就被拒绝,并说明是哪条规则、哪个值。
routes[].rules[].set#
set.model 可以写别名,每家上游收到各自对它的叫法。和别名一样,回答里的模型名写成客户端请求的名称。
set.reasoning 按客户端的格式写推理强度:output_config.effort、reasoning_effort、reasoning.effort、Gemini 的 thinkingLevel;客户端给的是思考预算时改预算。转换成另一种格式发给上游的请求按那种格式的写法写:off 发给 OpenAI Chat 或 Responses 上游时写 none,发给 Gemini 2.5 Flash 时写思考预算 0。
上游因为推理强度回 400 时(无论这一档是客户端写的还是规则改的),请求在同一家上游再发一次:改用上游原话里列出的、离原来那一档最近的一档,原话给了上限的用上限,一档都没列的去掉推理强度。被拒的是 none 时改用原话里列出的最低一档,推理保持在上游允许的最低。重发在请求详情里是新的一跳,不算重试。重发成功后,这一档按上游和模型记 7 天,存在数据目录的 effort-memory.json 里,之后的请求直接发可用的那一档。上游的地址、密钥或协议变了,或者上游被删除,它的记录随之作废。只给了思考预算的请求不重发。WebSocket 连接(Codex)上,一轮因推理强度被拒时不重发、也不记录,拒绝原样交给客户端。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
model | 字符串 | — | 换成另一个模型发送。该会话的 prompt cache 随之失效。 |
max_tokens | 整数 | — | 替换 max_tokens。 |
reasoning | off | low | medium | high | xhigh | max | — | 推理。off 关闭推理:去掉推理设置和推理强度,OpenAI 的格式改为写 none。写一档则改为该档强度。只改写已开启推理的请求,未开启推理的请求(如生成标题)保持不变。 |
only_at_session_start | 布尔 | false | 只在会话开始时应用。目前只记录和显示,尚未生效。 |
groups:
- name: fast
type: url-test
providers: [anthropic, relay]
routes:
- name: default
rules:
- name: 长上下文走官方
when: { input_tokens: ">200k" }
to: anthropic
- name: 标题用便宜模型
when: { intent: titling }
set: { model: claude-haiku-4-5 }
- name: 其余
to: fast
default_route: default
plugins#
脚本插件在请求发往上游之前改写请求,在回答到达客户端之前改写回答。插件运行在 core 内部的沙箱中,无法访问文件、网络,也看不到密钥的真实值。插件由应用安装:代码写入本文件旁边的 plugins/<id>.js,批准过的代码另存一份在 plugins/.approved/<id>.js,代码的 SHA-256 写入 sha256。
插件的设置也在它自己的文件里。文件开头的 manifest 写着插件出错时怎么办(on_error)、处理哪些请求(match)和每个设置项的值(settings.<名称>.value)。在应用里改这几项时,应用只改写文件里的 manifest,并同时更新 sha256。本列表只记录插件本身、批准的哈希和是否启用。core 0.58 写下的条目里还有 on_error、scope 和 settings:这些字段不再生效,下一次在应用里改动插件时会被去掉。
只有文件的哈希与批准时一致,插件才会运行。磁盘上的文件被改动或删除后,插件会在几秒内停止运行,应用里会列出改动供审阅。批准之前,按批准过的文件里写的,插件覆盖的请求会被拒绝(on_error: "reject",默认),或者跳过这个插件照常发出(on_error: "skip")。加载失败的插件按同样的方式处理。两种情况都不影响配置其余部分生效。
插件按本列表的顺序运行。
match 里的 clients、models 和 upstreams 都是名字或通配(* 可以写在任意位置)的列表,不区分大小写;列表为空或不写表示全部。clients 是客户端应用(claude-code、codex 等),认不出应用的请求只有空列表才算在内。models 按发给上游的模型匹配:路由规则改了模型名的,按改名之后的匹配。upstreams 对请求和回答都适用。
插件在路由之后改写请求,请求每发往一个上游改写一次。故障转移到另一个上游时,从客户端发来的原样重新开始;插件看得到这一次发往哪个上游、用哪个模型名。路由、模型准入和会话归组看的都是客户端发来的原样。插件改了模型名,只是换掉发给这个上游的名字:不会重新路由,新的名字仍要在这把密钥可用的模型之内(clients[].allow),否则请求不发出。
插件处理它在代码里声明的那几种请求:对话(Anthropic Messages、OpenAI Chat Completions 和 Responses、Gemini,连同它们的数 token 和压缩)、嵌入(/v1/embeddings、Gemini 的 :embedContent 和 :batchEmbedContents)和旧版补全(/v1/completions)。没有声明的插件只处理对话。插件不处理的那种请求不经过它,不论 on_error 怎么设。其他接口(图片、音频等)不经过任何插件。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
id | 字符串 | 必填 | 小写字母、数字和连字符,1 到 40 个字符,不能重复。 |
file | 字符串 | 必填 | 插件的代码,相对本文件所在的目录。只能是 plugins/<id>.js,由应用写入。 |
sha256 | 字符串 | 必填 | 批准过的代码的 SHA-256,64 个小写十六进制字符。文件的哈希与它不符时插件停止运行,直到在应用里批准这次改动。批准过的代码另存在 plugins/.approved/<id>.js。 |
enabled | 布尔 | true | 是否运行这个插件。false:插件保留,不参与任何请求。 |
plugins:
- id: add-date
file: plugins/add-date.js
sha256: 9f2b6c0e4a1d8f3b7c5e2a9d6f1b4c8e3a7d0f5b2c9e6a1d4f8b3c7e0a5d2f9b
enabled: true
plugins/add-date.js 的开头:
export const manifest = {
name: "Add date",
api: 1,
permissions: ["system"],
match: { clients: ["claude-code"], models: ["claude-*"], upstreams: [] },
on_error: "reject",
settings: {
note: { type: "string", label: "Note", value: "用中文回答。" },
},
};
sync#
多台设备(这台 Mac、一台笔记本、一台运行远程 core 的服务器)可以通过自选的同步位置保持同一份配置:由云盘在设备之间传送的文件夹、WebDAV 服务器或 S3 兼容存储。每次改动都按对象与其他设备自上次同步以来的改动合并;只有两台设备把同一对象的同一部分改成不同内容时才构成冲突,冲突在每台设备上显示,任一设备处理之后随之清除。开启同步、加入已有的同步和处理冲突在应用里进行(设置 → 同步与备份),服务器上用 twcore sync enable;本节记录的是结果。
同步的内容即配置包带的内容:上游、出站代理、网关密钥、别名、分组、路由、价目表、安全规则、插件和全局设置,包括密钥。listen、retention 和 sync 本身留在本机,ChatGPT 账号的登录、OAuth 的令牌也一样。别的设备上登录着的上游在这台设备上停用着,在这台登录之后才启用;这不会让它在别的设备上停用。
已有配置的设备加入时逐项合并,不一样的项目逐项选择;默认网关密钥例外:每个安装都会生成一把,加入的设备采用同步数据的值,本机已接管的客户端随之更新。
开着加密时,不加密的版本一概不读。keyring 不见了、被换成更早的那一份,都不会关掉加密:应用会问要不要放回这台设备记着的那一份。同步位置读起来是空的时,要再看几次才提示,停不停止同步由你决定。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
device_id | 字符串 | 必填 | 开启同步时生成。同步位置上的文件名里出现的是它的前 8 个字符。 |
device_name | 字符串 | 必填 | 在每台参与同步的设备的设备列表里显示的名字。 |
encrypt | 布尔 | true | 以同步口令加密存到同步位置的内容。同一同步位置上的所有设备采用同一设置;在应用里更改,应用会重新上传最新版本。 |
passphrase | 字符串 | — | 同步口令,encrypt 开着时必填;关闭加密之后也留着:同步位置上写着「已关闭」的 keyring 要用它核对。和本文件里的其他密钥一样以明文保存。 |
exclude | 字符串列表 | [] | 不同步的上游,按名字:不上传,也不被其他设备的同名上游覆盖。引用它们的路由、别名、分组随之不同步。 |
target | 对象,见 sync.target | 必填 | 同步位置。keyring、versions/、devices/ 直接放在它里面。 |
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type | folder | webdav | s3 | 必填 | 同步位置的种类;其余字段随之不同,见下面三张表。 |
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type | 字符串 | 必填 | folder |
path | 字符串 | 必填 | core 所在机器上的绝对路径:由 iCloud Drive、Dropbox、OneDrive、Syncthing 或 NAS 共享在设备之间传送的文件夹。 |
proxy | 字符串 | direct | 文件夹用不到。 |
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type | 字符串 | 必填 | webdav |
url | 字符串 | 必填 | 文件夹的 WebDAV 地址。https://,校验证书;http:// 只用于本机和局域网。 |
user | 字符串 | '' | 用户名。 |
pass | 字符串 | '' | 密码,或者服务为 WebDAV 签发的应用密码。 |
proxy | 字符串 | direct | 访问同步位置的请求从哪里出去:direct(直连)、system(跟随系统代理),或者 proxies 里一个代理的名字。本机、内网的 http:// 地址只能是 direct。 |
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type | 字符串 | 必填 | s3 |
endpoint | 字符串 | 必填 | S3 端点。主机以 amazonaws.com、aliyuncs.com、myqcloud.com 结尾的,存储桶名放进域名;其余端点(Cloudflare R2、MinIO、IP 地址)放进路径。http:// 只用于本机和局域网。 |
region | 字符串 | 必填 | 签名用的区域;Cloudflare R2 填 auto。 |
bucket | 字符串 | 必填 | 存储桶,建议设为私有。 |
prefix | 字符串 | '' | 存储桶里的一个前缀(文件夹)。不能有 ..,不以 / 开头。 |
access_key_id | 字符串 | 必填 | Access Key ID。 |
secret_access_key | 字符串 | 必填 | Secret Access Key。 |
proxy | 字符串 | direct | 访问同步位置的请求从哪里出去:direct(直连)、system(跟随系统代理),或者 proxies 里一个代理的名字。本机、内网的 http:// 地址只能是 direct。 |
sync:
device_id: 3f9a2c1e-0b1d-4e2f-9a3b-5c6d7e8f9a0b
device_name: Mac mini
encrypt: true
passphrase: "correct horse battery staple"
exclude: [本机 Ollama]
target:
type: webdav
url: https://dav.example.com/dav/ThinkWatch
user: name@example.com
pass: "应用密码"
环境变量#
| 变量 | 作用 |
|---|---|
THINKWATCH_HOME | 数据目录,替代 ~/.thinkwatch(Windows 上为 %APPDATA%\ThinkWatch)。 |
TWCORE_LOG | 日志过滤,tracing 语法(info、debug、tw_gateway=debug)。 |
HTTPS_PROXY、HTTP_PROXY、ALL_PROXY、NO_PROXY | 供 proxy: system 的上游使用。 |
| 其他 | 配置中写 ${NAME} 的位置读取。 |
联网工具#
在 Lite 的 路由 → 辅助请求 中配置搜索、网页读取和页内查找。core 直接处理 Claude Code 的独立搜索子请求,省去搜索助手模型调用;Anthropic Messages 和 OpenAI Responses 对话中的联网工具由 Core 执行后交回模型继续处理,主模型仍按实际用量计费。客户端直接抓取网页的行为不变。联网工具响应收齐后按原生 JSON 或 SSE 返回,等待期间保持心跳。支持公开 HTTP/HTTPS 文本网页;指定地理位置或仅使用厂商缓存的搜索模式需要沿用上游。
搜索直接连接 Google Docs 网页检索、DuckDuckGo 和 Bing,无需 API Key 或浏览器运行时。自动顺序为 Google (Docs)、DuckDuckGo、Bing。Google (Docs) 通过旧版接口搜索公开网页,依赖仍可用的公开文档上下文,Google 调整服务后可能失效;不会读取或修改这些文档,不支持地区偏好,请求间隔至少 6 秒。文档访问失败可选择备用上下文,限流或服务器错误则冷却该引擎并切换其他搜索源。验证码和无法识别的页面按失败处理,配合请求间隔、冷却和其他引擎重试,不会当作“没有结果”。HTTP、HTTPS 和 SOCKS 代理连接 Core 已校验的公开 IP,TLS 和 HTTP 保留原始域名。Responses WebSocket 使用同一套受保护的执行流程。只有独立搜索辅助请求可以按显式配置回退上游。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
mode | upstream | core | upstream | upstream 沿用上游;core 执行已适配的联网工具。 |
engines | 字符串列表 | [] | 空列表依次尝试 google_docs、duckduckgo、bing;也可手动按优先顺序填写这些引擎 ID。 |
proxy | 字符串 | system | system、direct 或已定义的代理名称。 |
language | 字符串 | '' | BCP 47 语言标签。空值跟随运行 Core 的主机系统语言(包括远程 Core),无法识别时由引擎决定。Lite 中通过语言列表选择。 |
region | 字符串 | '' | 两字母国家或地区代码。空值跟随 Core 主机系统语言中的地区,无法识别时由引擎决定。搜索引擎按支持范围尽量应用偏好。 |
allowed_domains | 字符串列表 | [] | 仅允许这些域名及子域名,也约束网页读取;空列表允许所有公开域名。 |
blocked_domains | 字符串列表 | [] | 排除的域名及子域名,排除优先。 |
max_results | 整数 | 8 | 搜索结果数,1–20。 |
read_pages | 整数 | 2 | 摘要不足时读取 0–5 个网页;设为 0 不影响模型明确调用网页读取。 |
max_page_chars | 整数 | 12000 | 每页返回字符上限,1000–50000。 |
timeout_secs | 整数 | 30 | 包括排队在内的单次操作超时,1–120 秒。 |
max_concurrent | 整数 | 4 | 联网操作并发数,1–16。 |
interval_ms | 整数 | 1000 | 同一搜索引擎的最小请求间隔,250–60000 毫秒。搜索源可要求更长间隔(google_docs:6000)。 |
cache_secs | 整数 | 600 | 成功结果缓存时间,0–86400 秒;0 关闭缓存。 |
max_tool_calls | 整数 | 8 | 每个模型请求最多执行联网工具次数,1–32。 |
fallback_to_upstream | 布尔 | false | 独立搜索返回结果之前失败时允许回退上游,可能产生上游费用。 |
本页取自 ThinkWatch Core 仓库 docs/config.zh-CN.md (v0.99.0)。