跳转到正文
ThinkWatch
开始输入以搜索文档。
ThinkWatch Core · 配置手册

配置手册#

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 监视配置文件,保存后一秒内重新加载,无需重启。

新版本要通过以下每一关才会换入:

  1. 能按 YAML 解析。
  2. 符合结构:字段名已知,类型正确。
  3. 自洽:名字不重复、引用都能找到、正则能编译、CIDR 写法正确。
  4. 能据此建立运行时对象。

任何一关失败,原有配置继续服务,错误信息说明失败在哪一关、哪个位置。写错一个字不会让网关停下。在保存出合法版本之前,桌面应用会一直显示这次拒绝。

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#

字段类型默认值说明
bindloopback | all | 网卡名 | IP 地址loopbackloopback 只有本机;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 在一秒内跟上。
bindloopback | 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 和费用在 断开时计入。

字段类型默认值说明
perminute | 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)二选一。
protocolanthropic | openai-chat | openai-responses | gemini | chatgpt | bedrock—上游的接口格式。不写:官方地址按 base_url 识别(Bedrock 的推理地址是 bedrock),其余按 anthropic 处理。
reasoning_historyauto | reasoning-content | reasoning | content-blocks | disabledautoChat 请求的思考历史格式: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字符串directdirect;system,即 core 进程环境变量 HTTPS_PROXY、HTTP_PROXY、ALL_PROXY 中的代理;或 proxies 中某一项的名字。
on_proxy_failfail | directfail代理不可用时:请求失败(fail),或改为直连(direct)。
models字符串列表[]手动添加的模型,写确切的 ID:上游能服务、却没有列进清单的模型。它们和上游列出的模型一起算作这家提供的模型,上游不提供清单时就是全部:出现在 /v1/models 里,相应的请求也会路由到这家。models_only 照样适用。不支持通配,不能重复,每项最多 256 个字符。
models_only字符串列表—只使用这家的这些模型,写 ID 或通配。范围外的模型不出现在模型列表里,也不会路由到这家。不写:全部。写空列表会被拒绝,暂停使用请用 disabled。
billingper-token | freeper-tokenper-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不参与路由,模型也不出现在模型列表里;配置原样保留。
balanceauto | off | openrouter | deepseek | moonshot | sub2api | newapi | thinkwatchauto从哪里读这家上游的余额,用它自己的密钥、走它自己的代理: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_inzai | 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 要留够那一期,和密钥的一样;分钟、小时的窗口从空的开始。

字段类型默认值说明
perminute | 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_historyauto | 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_levelminimal | 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 是内置的。
typesocks5 | socks5h | http | httpssocks5hsocks5h 把域名交给代理解析;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_checkintercept | forwardintercept连通性检查(max_tokens: 1)。默认在本地应答,不影响任何功能。
warmupintercept | forwardintercept预热请求。默认在本地应答。
titlingintercept | forwardforward为会话起标题的请求。默认转发:拦下后所有会话都会是同一个标题。
topic_detectintercept | forwardforward话题检测。默认转发。
suggestionintercept | forwardforward建议。默认转发。

security#

三项防护,对所有上游一视同仁。每一项都有 mode:off、observe(检测并记录,不改变任何行为)、enforce(按每条规则的动作处理)。出厂时三项都是 observe。每条规则各有动作:出站脱敏替换为占位符或只记录,工具调用审查切断响应或只记录,内容过滤拒绝、删除、替换或只记录。

字段类型默认值说明
redact对象,见 security.redact—出站脱敏(应用里叫「密钥与隐私」):请求发出前,按每条规则把其中正文(消息、系统提示、推理、工具调用的参数和结果、工具说明)里的凭据和个人信息替换为占位符,或只记录;id、模型名等协议字段原样发出。
inspect_tools对象,见 security.inspect_tools—工具调用审查(应用里叫「危险命令」):模型返回的工具调用中出现危险命令时切断响应。
content对象,见 security.content—内容过滤:调用方发送的内容中、或模型回答的正文中出现指定的词、写法或字符(包括隐藏字符)时,按规则拒绝请求、删除或替换命中的内容,或只记录。

security.redact#

请求发出前,在请求中写出的正文里查找凭据和个人信息:系统提示、各角色的消息(包括之前的回答)、推理、工具调用的参数、工具结果和工具说明。enforce 下将规则找到的内容替换为占位符,回答中重复出现时再换回原值;action: record 的规则找到的内容原样发送,只作记录。协议要求原样保留的值(如 id、类型、角色、工具名、模型名、签名)一律不查,字段名、图片、文件、配置项以及网关不认作正文的部分也不查。

字段类型默认值说明
modeoff | observe | enforceobserveoff 不检测(应用里叫「关闭」);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 时为正则表达式。
matchcontains | regexcontainscontains:按原样查找 pattern,.、* 等字符没有特殊含义。regex:pattern 是正则表达式。
case_sensitive布尔false区分大小写。默认不区分:ABC 和 abc 都会匹配。
label字符串SECRET占位符名称:匹配到的内容替换为 <<TW_名称_序号>>,每个名称各自编号。只能使用大写字母、数字和下划线,以字母开头,最多 24 个字符。
actionplaceholder | recordplaceholderenforce 下将匹配到的内容替换为占位符(placeholder),或只记录、原样发送(record)。
disabled布尔false停用这条规则,规则本身留在文件里。

内置规则:

id名称出厂
anthropic-api-keyAnthropic API 密钥开
openai-project-keyOpenAI 项目密钥开
openai-api-keyOpenAI API 密钥开
github-personal-tokenGitHub 个人令牌开
github-oauth-tokenGitHub OAuth 令牌开
github-server-tokenGitHub 服务器令牌开
github-user-tokenGitHub 用户令牌开
github-fine-grained-tokenGitHub 细粒度令牌开
slack-bot-tokenSlack 机器人令牌开
slack-user-tokenSlack 用户令牌开
slack-app-tokenSlack 应用令牌开
aws-access-key-idAWS 访问密钥 ID开
aws-temporary-key-idAWS 临时访问密钥 ID开
google-api-keyGoogle API 密钥开
google-oauth-tokenGoogle OAuth 令牌开
gitlab-tokenGitLab 令牌开
stripe-live-keyStripe 生产密钥开
stripe-restricted-keyStripe 受限密钥开
npm-tokennpm 令牌开
digitalocean-tokenDigitalOcean 令牌开
sendgrid-keySendGrid 密钥开
private-key私钥开
jwtJWT开
conn-string-password连接串口令开
cn-resident-id居民身份证号开
bank-card银行卡号开
email邮箱地址关
cn-mobile-phone中国大陆手机号关
internal-ip内网地址关
internal-domain内部域名关
thinkwatch-saved-secretThinkWatch 中保存的密钥开
openai-service-keyOpenAI 服务账号与管理密钥开
openrouter-keyOpenRouter API 密钥开
xai-keyxAI API 密钥开
groq-keyGroq API 密钥开
huggingface-tokenHugging Face 令牌开
replicate-tokenReplicate 令牌开
perplexity-keyPerplexity API 密钥开
bedrock-api-keyAmazon Bedrock API 密钥开
fireworks-keyFireworks AI API 密钥开
cerebras-keyCerebras API 密钥开
langsmith-keyLangSmith API 密钥开
langfuse-secret-keyLangfuse 私密密钥开
pinecone-keyPinecone API 密钥开
tavily-keyTavily API 密钥开
minimax-keyMiniMax API 密钥开
zhipu-api-key智谱 API 密钥开
qianfan-api-key百度千帆 API 密钥开
sk-compat-keyOpenAI 兼容格式 API 密钥开
github-refresh-tokenGitHub 刷新令牌开
gitlab-other-tokenGitLab 其他令牌开
pypi-tokenPyPI 令牌开
rubygems-tokenRubyGems 令牌开
clojars-tokenClojars 令牌开
docker-hub-tokenDocker Hub 令牌开
artifactory-keyJFrog Artifactory 密钥开
databricks-tokenDatabricks 令牌开
sentry-tokenSentry 令牌开
grafana-tokenGrafana 令牌开
postman-keyPostman API 密钥开
aws-other-key-idAWS 其他访问密钥 ID开
alibaba-access-key-id阿里云 AccessKey ID开
tencent-secret-id腾讯云 SecretId开
volcengine-access-key-id火山引擎 AccessKey ID开
azure-ad-client-secretAzure AD 客户端密码开
digitalocean-other-tokenDigitalOcean 其他令牌开
cloudflare-origin-ca-keyCloudflare Origin CA 密钥开
vault-tokenHashiCorp Vault 令牌开
terraform-tokenTerraform Cloud 令牌开
doppler-tokenDoppler 令牌开
pulumi-tokenPulumi 令牌开
heroku-keyHeroku API 密钥开
flyio-tokenFly.io 令牌开
supabase-keySupabase 密钥开
age-secret-keyage 私钥开
onepassword-token1Password 服务账号令牌开
stripe-webhook-secretStripe Webhook 签名密钥开
shopify-tokenShopify 令牌开
twilio-api-keyTwilio API 密钥开
brevo-keyBrevo API 密钥开
slack-other-tokenSlack 其他令牌开
linear-keyLinear API 密钥开
notion-tokenNotion 令牌开
atlassian-tokenAtlassian API 令牌开
auth-header-credential请求头中的凭据开
command-line-password命令行中的口令开
url-tokenURL 中的令牌开
bot-webhook机器人 Webhook开
telegram-bot-tokenTelegram 机器人令牌开
config-assignment配置文件中的密钥赋值开
crypto-mnemonic助记词开
crypto-wif-keyWIF 私钥开
crypto-extended-key扩展私钥开
uuidUUID/紧凑标识符开
crypto-hex-key裸钱包私钥/32 字节哈希开
crypto-solana-keySolana 密钥对开
crypto-sui-keySui 私钥开
crypto-stellar-keyStellar 私密种子开
crypto-xrp-seedXRP 账户种子开
crypto-address区块链账户/扩展公钥开
crypto-secret-field字段中的钱包机密开
exchange-credential交易 API/签名鉴权凭证开
crypto-keystore钱包密钥库/密文开
crypto-rpc-key区块链 RPC 地址凭证开
cn-resident-id-1515 位旧身份证号关
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)关
imeiIMEI关
mac-addressMAC 地址关
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 的规则时切断响应,客户端拿不到可执行的完整调用。

字段类型默认值说明
modeoff | observe | enforceobserveoff 不检测(应用里叫「关闭」);observe 检测并记录,不改变任何行为(「监控」);enforce 检测并按每条规则的动作处理(「开启」)。
enable字符串列表[]打开出厂时关着的内置规则,按 id。
disable字符串列表[]关掉内置规则,按 id。
actions映射: 内置规则 id → cut | record{}内置规则在 enforce 下的处置,只写与出厂不同的(rm-rf-root: record)。
custom对象列表,见 security.inspect_tools.custom[][]自定义规则,按工具调用的参数匹配。

字段类型默认值说明
name字符串必填日志和应用里显示的名字,也是规则的标识;同一项防护里不能重名。
pattern字符串必填正则表达式。
actioncut | recordrecordenforce 下切断响应(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 只记录。请求中删除或替换之后会再检查一遍:被隐藏字符拆开的关键词,删掉隐藏字符后照样命中;替换上去的文字不再检查。回答中删除或替换的内容不会送达客户端,请求记录中保存客户端实际收到的回答。

字段类型默认值说明
modeoff | observe | enforceobserveoff 不检测(应用里叫「关闭」);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 匹配。
matchcontains | regex | codepointscontainscontains:正文按原样包含 pattern,.、* 等字符没有特殊含义。regex:pattern 是正则表达式。codepoints:正文中出现 pattern 所列码位或码位范围内的字符,多个之间用逗号分隔;仅用于请求。
case_sensitive布尔false区分大小写。默认不区分:ABC 和 abc 都会匹配。码位不受此项影响。
actionblock | strip | replace | recordrecordenforce 下拒绝请求(block,仅用于请求)、删除命中的内容后发出(strip)、将命中的内容替换为 replacement 后发出(replace),或只记录(record)。删除处前后拼接成的文字重新检查,直到不再有命中;替换上的文字不再检查;回答中锚定正文或行首尾的正则(^、$、\A、\z)只检查一次。替换不可还原,回答中不换回原文。
replacement字符串"***"动作为 replace 时替换成的文字。
disabled布尔false停用这条规则,规则本身留在文件里。

内置规则:

id名称分组出厂enforce 下出厂处置
unicode-tagsUnicode 标签字符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
danDANinjection关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长串 Base64persona关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字符串必填策略组的名字,不能重复,也不能和上游同名。
typefallback | select | load-balance | url-test | cheapestfallbackfallback:按顺序取第一个健康的。select:取 selected 指定的那个。load-balance:请求按成员的权重分;进行中的对话留在原来那一家。url-test:按实测从发出请求到回答第一段内容的时间取最快的。cheapest:取输入单价最低的。
providers列表,每项是字符串或对象,对象见 groups[].providers[]必填成员上游的名字,不能是策略组。同一个上游在一个策略组中只出现一次。load-balance 组的成员可以写成 {name, weight}。
selected字符串—select 类型选中的成员。
balance_byweights | latency | health | latency-healthweightsload-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。
reasoningoff | 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/ 直接放在它里面。

字段类型默认值说明
typefolder | 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 使用同一套受保护的执行流程。只有独立搜索辅助请求可以按显式配置回退上游。

字段类型默认值说明
modeupstream | coreupstreamupstream 沿用上游;core 执行已适配的联网工具。
engines字符串列表[]空列表依次尝试 google_docs、duckduckgo、bing;也可手动按优先顺序填写这些引擎 ID。
proxy字符串systemsystem、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)。

最后更新于 2026-10-25 在 GitHub 上编辑