配置手册#

ThinkWatch Core 只读一个文件：config.yaml。本文逐项说明其中每个字段的作用、默认值、可选值，以及改动如何进入正在运行的进程。在服务器上运行 core、由桌面应用远程管理，见在服务器上运行 core。

本文的字段表由代码生成，与代码不一致时测试失败。表中列出的字段，就是程序实际读取的字段。

文件位置#

THINKWATCH_HOME 替换整个目录；--config <路径> 为单条命令指定文件。core 的其余数据也在这个目录里：请求数据库（data.db）、配置历史（history/）、下载的价目表（model_prices.json），以及本地控制通道的 socket 文件（twcore.sock；Windows 上是回环端口，记录在 control.port 中）。目录只有所有者可访问（0700），配置文件权限为 0600：其中以明文保存密钥。

没有配置文件时，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/ 目录中，并记录来源（应用、命令行、外部编辑、回滚、凭据轮换）。保留最近 50 个版本。

twcore check                      # 只校验配置，不启动任何服务
twcore config show                # 打印当前配置及其版本
twcore config history             # 列出历史版本，最新的在前
twcore config rollback 3f9a2c     # 回滚到某个版本（写前几位即可）
twcore config set /listen/gateway/port 8790 --int

这些命令直接操作文件，因此 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。只改这几个值，注释和排版保持原样。

字段参考#

每张表列出一节的全部字段。「默认值」一栏为「—」表示不写就没有这个字段，其含义见说明。

顶层#

listen#

core 在哪里接受连接。连接分两种：客户端发送请求的 AI 网关，以及桌面应用和 twcore 命令使用的控制通道。

listen.gateway#

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 缺失时，由 twcore serve 在控制通道开始监听之前写入；twcore init 生成的配置也带有它。凡是显示配置或写入配置历史的地方，这个字段一律打码；把打码值原样存回时保留原值。密钥缺失或格式不对（不是 64 个十六进制字符）时整份配置无效，因此无法把它换成一把容易猜到的短密钥。

twcore control-key            # 显示密钥，用于粘贴到桌面应用
twcore control-key --rotate   # 更换密钥；已连接的应用需要重新连接

两条命令都在运行 core 的机器上执行。

listen.control.remote#

供另一台机器上的桌面应用连接的网络端口。它在本地通道之外额外开启，因此这里写错（端口被占用、allow_from 把自己挡在外面）也不会把本机锁在门外：twcore config 和本机应用照常可用。

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 等客户端向网关发送的密钥。密钥即身份：并发上限、模型范围、路由都按密钥设置。

clients:
  - name: default
    key: tw-a3f9c8d1e5b2h7k4m6n8p2q4
  - name: build-server
    key: tw-q8r2s4t6u8v2w4x6y8z2a4b6
    max_concurrent: 4
    allow: [claude-sonnet-*]
    route: cheap

providers#

上游，即请求被转发到的接口。

凭据有四种写法：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

  - name: local
    base_url: http://127.0.0.1:11434/v1
    protocol: openai-chat
    billing: free

每个请求只带请求本身和上游需要的请求头，客户端的其他信息一律不发：凭据和 headers 中写的请求头、ThinkWatch 自己的 User-Agent，以及客户端请求中该上游协议使用的请求头（Anthropic 为 anthropic-*，OpenAI 为 Idempotency-Key 和 X-Client-Request-Id，Gemini 没有）。客户端自动填写的身份字段（如 Claude Code 的 metadata.user_id）从请求体中去掉。只接受特定客户端的上游，打开 forward_client_identity。

ChatGPT 账号上游（protocol: chatgpt）只接受桌面应用登录得到的凭据，不能手写。不支持 Claude 和 Google 的订阅登录，请使用 API 密钥。

providers[].oauth#

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#

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 中写区域；模型清单也向该地址获取。

proxies#

出站代理。不同上游需要的代理往往不同，因此没有全局开关：由每个上游用 proxy 选择。

proxies[].auth#

proxies:
  - name: office
    type: http
    addr: proxy.example.com:3128
    auth:
      user: alice
      pass: ${PROXY_PASSWORD}

on_proxy_fail 默认为 fail：静默改为直连会让请求走一条意料之外的路径，而使用者仍以为请求经过了代理。

pricing#

一次请求的费用为用量乘以模型单价。单价来自默认价目表（LiteLLM 的公开数据集，程序内置一份，每天联网刷新），或来自上游选用的自定义价目表。单价变动只影响此后的请求，不改变已记录请求的费用。

pricing.sheets#

pricing.sheets[].models#

单价以每百万 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，不向上游发送任何内容）、原样放行（passthrough），或交给路由规则（route，由 when.intent 匹配）。默认只拦下拦了也不会少任何东西的那几类。

security#

五项防护，对所有上游一视同仁。每一项都有 mode：off、observe（检测并记录，不改变任何行为）、enforce（处置）。出厂时除输出长度为 off 外，其余都是 observe。各项在 enforce 下的处置不同，分别见下文。

security.redact#

请求发出前查找其中的凭据。enforce 下将其替换。

内置规则：

security.inspect_tools#

按规则检查模型返回的工具调用。enforce 下命中处置为 cut 的规则时切断响应，客户端拿不到可执行的完整调用。

内置规则：

security.hidden_text#

调用方发送的内容中（包括工具结果）人看不见、模型读得到的字符。enforce 下拒绝请求。

security.content#

调用方发送的内容中出现的词或写法。enforce 下命中处置为 block 的规则时拒绝请求。

内置规则：

security.output_limit#

security:
  redact:
    mode: enforce
    enable: [internal-ip]
    custom:
      - name: employee-id
        pattern: 'EMP-\d{6}'
  inspect_tools:
    mode: enforce
  output_limit:
    mode: enforce
    max_chars: 200000

retention#

设两个期限，是因为两类数据的体积相差三个数量级：一条请求的正文有几十 KB，一条请求记录只有几百字节。字节上限用于应对用量突增。

failover#

上游失败后会停用一段时间，接下来的请求直接交给下一个候选。停用多久取决于上游 给出的原因：余额不足要等充值，额度用完要等到上游说的重置时刻，限流通常几秒钟就 过去。只有一个候选的请求不受影响。

流式回答在第一段内容交给客户端之前，上游在流里报的错误和错误状态码一样，会把 请求换到下一个候选。

groups#

策略组让多个上游合用一个名字。规则用 to 把请求交给策略组。

默认类型为 fallback：单个使用者的机器上没有需要分散的负载。

无论哪种类型，一段对话都留在上次回答它的那一家上游，让上游缓存着的那部分被再次读取，而不是换一家全价重算。同一轮之内（客户端正在回传工具结果）一律不换；跨轮时，上一次回答读或写了至少 1024 个 token 的 prompt cache、且距今不到五分钟，才继续留下。上游因失败进入冷却时，对话随之放开；故障转移之后接下回答的那一家，就是之后留下的那一家。一轮开始时命中的规则也沿用到这一轮结束：按输入大小或图片分流的规则不会让一轮半路换家，除非输入已经超出规则所指模型的上下文窗口。因此 load-balance 轮流的是新对话。

routes#

一条路由是一组自上而下求值的规则。每把密钥使用其 route 指定的路由；没有指定时用 default_route；再没有时用名为 default 的路由；一条路由都没有时，请求按上游的声明顺序故障转移。

routes[].rules#

routes[].rules[].when#

比较式以 >、>=、<、<= 或 == 开头，数字可以带 k 或 m 后缀：">200k"、"<=4k"。不带运算符是错误，不当作相等：单写 "200k" 会被拒绝。

routes[].rules[].set#

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

环境变量#