Header 修改

Header 修改是 Claude Code Hub 代理系统的核心功能，允许管理员在请求转发到上游 AI 供应商之前，以编程方式修改 HTTP 请求头。

过滤器类型

系统支持两种主要的 Header 修改操作：

绑定类型

Header 过滤器可以在不同范围应用：

执行流程

Header 修改在请求处理管道中的执行顺序：

请求到达 -> 解析 Headers -> 应用全局过滤器 -> 选择供应商 -> 应用供应商过滤器 -> 头处理器清理 -> 转发请求

1. 全局过滤器：在供应商选择前应用，按优先级排序执行
2. 供应商过滤器：在供应商选择后应用，仅对匹配的供应商生效
3. 头处理器：最终清理和标准化，添加认证信息

配置示例

移除敏感头

// 移除内部令牌
{
  name: "移除内部令牌",
  scope: "header",
  action: "remove",
  target: "x-internal-token",
  bindingType: "global",
  priority: 10,
}

设置自定义头

// 覆盖 User-Agent
{
  name: "自定义 User-Agent",
  scope: "header",
  action: "set",
  target: "user-agent",
  replacement: "MyApp/1.0",
  bindingType: "providers",
  providerIds: [1, 2],
  priority: 5,
}

分组过滤器

// 为高级用户组添加优先级头
{
  name: "高级用户优先级",
  scope: "header",
  action: "set",
  target: "x-priority",
  replacement: "high",
  bindingType: "groups",
  groupTags: ["premium"],
  priority: 20,
}

优先级系统

过滤器按优先级升序执行（数值越小越先执行）。当多个过滤器针对同一个头时：

1. 相同优先级：按 ID 升序排列，后执行的覆盖先执行的
2. 不同优先级：高优先级（数值大）的结果生效
3. 全局 vs 供应商：供应商过滤器在全局过滤器之后执行，可以覆盖全局设置

特殊行为

失败开放策略

Header 过滤器失败不会阻塞请求。系统采用失败开放策略：

try {
  await requestFilterEngine.applyGlobal(session);
} catch (error) {
  // 过滤器失败不阻塞主流程
  logger.error("Failed to apply filters", { error });
}

空值处理

使用 action: "set" 时：

• replacement 为 null 或 undefined：头设置为空字符串 ""
• replacement 为非字符串值：会被 JSON 序列化
• 要移除头，请使用 action: "remove" 而非设置空值

头名称大小写

头名称不区分大小写（符合 HTTP 规范）。配置时建议使用小写：user-agent、x-api-key。

无法修改的头

以下头由系统管理，过滤器无法有效修改：

Codex User-Agent 特殊处理

对于 Codex 类型供应商，系统会检测 User-Agent 是否被过滤器修改：

• 如果过滤器修改了 User-Agent，使用修改后的值
• 如果过滤器删除了 User-Agent，回退到原始值
• 如果无原始值，使用默认的 Codex CLI User-Agent

绑定验证

系统对绑定类型有严格约束：

• 不能混用：providers 绑定不能同时指定 groupTags
• 全局限制：global 绑定不能指定 providerIds 或 groupTags

// 错误示例
{
  bindingType: "providers",
  providerIds: [1, 2],
  groupTags: ["premium"],  // 错误：不能同时指定
}

常见用例

性能考虑

1. 早期退出：无过滤器时引擎会快速返回
2. 预排序：过滤器在初始化时按优先级预排序
3. Set 查找：供应商和分组匹配使用 Set 数据结构，O(1) 复杂度
4. 热重载：过滤器更新无需重启，通过事件发射器实时生效

安全考虑

1. ReDoS 防护：Body 过滤器中的正则表达式使用 safe-regex 验证
2. 失败开放：过滤器失败不会阻塞请求
3. 认证保护：authorization 头始终由转发器覆盖，过滤器无法泄露凭证
4. 审计追踪：头修改可通过 isHeaderModified() 检测并记录

UI 管理

在设置页面 Settings > Request Filters 中管理 Header 过滤器：

• 创建过滤器：点击添加按钮，填写名称、绑定类型、操作、目标等字段
• 编辑过滤器：点击编辑按钮修改现有配置
• 启用/禁用：使用开关切换过滤器状态
• 刷新缓存：修改后点击刷新按钮使配置立即生效

相关文档

• Body 修改 - 了解请求体修改功能
• 供应商管理 - 了解供应商配置和分组
• 智能路由 - 了解请求路由机制