模型网关
安全网关在编程 Agent 的模型请求发出前进行本机检查。对明确接入网关的请求，所选策略识别到的敏感内容可以被拦截或脱敏，保护结果可在 设置 → 网关 → 隐私保护统计 中查看。保护范围以经过网关的请求和所选策略为准。
网关可对支持的命中内容做可逆令牌化，并尝试还原响应中的已知令牌；当前托管配置使用占位凭据，历史配置与接管快照需单独检查。它只处理编程 Agent 的模型流量，Kaya 对话使用独立路径。
它解决什么问题#
按档位处理命中的内容：请求出本机前，按当前档位把命中内容替换为形状保持的可逆令牌，响应返回 Agent 前按可用映射还原。默认 strict 只自动处理具名 secret；需要自动处理普通邮箱、手机号等 PII 时，须显式选择 balanced 或 aggressive。
真实 key 不落 Agent 配置：配置里只有本机回环地址、per-agent 占位 token、模型别名和友好名称；真实 API Key / OAuth token 只在系统钥匙串与网关内存中。
脱敏是重要防线，但不是绝对保证。模型如果改写或拼错令牌，对应内容就无法保证自动还原。
三步开启#
在 ⚙ 设置 → 模型 配好供应商与模型。
在 ⚙ 设置 → 网关 打开「启用网关」。状态显示「运行中 · 端口」即就绪；网关只监听
127.0.0.1，不对外暴露。打开 ⚙ 设置 → 编程 Agent → 某个 Agent 详情页，在「模型网关」卡里打开「经网关接入」并选择默认模型。
新绑定默认经网关接入；网关尚未启用时会明确提示将在启用后生效。
全量目录与协议选路#
Agent 的模型选择器可以看到模型库中与其协议兼容的全部模型，也可以开启「只显示绑定模型」。
Claude Code 使用 Anthropic；Kimi Code / OpenCode 使用 OpenAI Chat；Codex 使用 OpenAI Responses。
只有 Chat 端点的供应商可为 Codex 提供 Responses→Chat 适配切片。
“OpenAI ChatGPT 订阅（Codex）”专用授权可供 Claude Code、Kimi Code、OpenCode、Codex 经网关使用 Responses 适配；不用于 Kaya 聊天。凭据只用于目录声明的目标，真实登录与刷新仍待真机验收。
请求模型名必须是可解析的
kaya/<别名>。裸上游模型名、畸形名或跨族别名会返回 HTTP 400，不会偷偷转发。/health//healthz由本机直接响应，方便探活。
接管与恢复#
Kaya 只接管 Agent 的模型面，不碰权限、hooks、MCP、插件或配置优化管理的键。
接管前逐键快照到
~/.kaya/agent-config-snapshots/（0o600）。接管后新增的用户条目保留；撤除时只补缺失，当前同名条目优先。
无法安全快照时不删除、不覆写无法恢复的用户值。
配置被外部修改时显示漂移提示，不会静默覆盖；点「重新接入」才按期望形态重写。
Codex 默认使用独立 profile；只有显式开启「全局接管」才影响裸跑 Codex 与 ChatGPT 桌面版会话，开启前有二次确认。
老版本接管且没有快照的配置无法完整自动还原，需要手动恢复旧值。
网关脱敏#
| 档位 | 行为 |
|---|---|
| strict（默认） | 只自动拦截具名 secret，普通 PII 不自动改写 |
| balanced | 具名 secret 与 PII 令牌化，高熵兜底只告警 |
| aggressive | 高熵字符串也令牌化，误伤与还原失败风险更高 |
网关档位独立于聊天。聊天用户输入恒为 aggressive，工具输出默认 aggressive，可在通用设置调整。代码、工具参数和工具结果中的 PII / 高熵内容按字段规则处理，可能只观察而不改写；不要把“启用网关”当作所有敏感内容都会被替换的保证。
**媒体与文本边界：**通过校验的 PNG / JPEG / GIF / WebP / PDF 等媒体按媒体原样转发，不经过文本规则的脱敏；不支持的媒体、声明冲突或校验失败会拒绝转发。启用网关不代表图片或文件中的全部敏感信息都已经被改写。
还可以配置：
用户令牌表：把真名、内部代号等固定替换为自定义令牌，响应再还原。
拒绝未知路径：默认透传未识别路径并记告警；开启后直接拒绝，可能影响 Agent 的辅助请求。
Claude 不由 Kaya 托管：不为 Claude Code 写托管配置，其流量也就不经网关和脱敏。
隐私保护统计#
设置 → 网关 → 隐私保护统计 可以查看令牌化、告警与还原明细：
默认展示全部规则记录：未替换的风险记录排在最前，再按规则置信度排序，已替换记录最后。未替换不直接代表已经泄露，应结合当前档位和请求结果判断。响应还原次数只统计实际记录到的还原，不把推测的还原计入数字。
按类别、动作、Agent、模型路由、规则类型和时间窗筛选，按原文或令牌搜索。
同内容命中聚合出现次数、首次与最近出现时间。
明细含命中原文与替换令牌，只存本机
~/.kaya/gateway/privacy-events.jsonl（0o600），默认遮罩，点击才展开。可经二次确认清空当前视图或全部记录。按筛选清空只删除命中明细；全量清空还会连带删除独立的请求事件。
这些明细不自动进入 LLM 上下文或诊断导出。它们与零内容的 gateway-scrub 审计事件、保存脱敏后正文的聊天审计日志是三套不同记录。
请求指标与最近事件#
另可查看请求数、改写请求数、上游 4xx、精确恢复与媒体处理。逐条请求审计默认折叠，只用于排查；请求事件只保存结构化计数、状态和诊断标识，不含正文、令牌或完整字段路径。它与包含命中原文的隐私明细是不同记录。
上游异常与用量#
流式响应连续 120 秒无数据会中止，并按 Agent 协议发送终结错误，不伪造完成。
非流式与等响应头各有 300 秒上限，超时返回结构化 504。
超时与断流只把路由标识和秒数写入 App 诊断日志，不记请求内容。
聊天与网关共用 Token 记账；详见 Token 用量。