9Rebels/relay-mask

relay-mask

让带「官方客户端校验」的 AI 中转 API 在任何客户端可用 —— 零服务、零代理、纯配置。

一些中转 API 会校验请求是否来自官方客户端（检查 User-Agent / originator 等 HTTP 指纹头），普通程序直接调用会得到：

{"error":{"message":"unauthorized client detected, ..."},"type":"unauthorized_client_error"}

relay-mask 不做代理、不起服务，它做两件事：

1. probe —— 自动诊断目标中转到底校验什么、哪种伪装能过；
2. snippet —— 为你的客户端生成放行所需的配置片段。

原理

请求头是「发起请求的程序」写上去的。所谓绕过，就是在客户端自己的配置口子里把指纹头补上——大多数场景根本不需要中间层：

| 校验方式 | 典型放行条件 |
|---|---|
| originator 头 | originator: codex_cli_rs |
| User-Agent | codex_cli_rs/x.y.z (...) 或 claude-cli/x.y.z (external, cli) |
| 二选一 | 任一命中即放行（多数中转的实现） |

安装 / 使用

无需安装依赖（零依赖，Node ≥ 18）：

直接运行
node src/cli.js --help
或全局安装后使用 relay-mask 命令
npm i -g github:9Rebels/relay-mask

诊断一个中转

relay-mask probe https://your-relay.example.com/v1 sk-your-key --model gpt-5.6-sol

真实输出示例：

probing https://ps.air-outer.com/v1  (model: gpt-5.6-sol)

bare (no disguise)         -> 401  unauthorized client detected, ...
originator=codex_cli_rs    -> 200  ok
UA=codex_cli_rs only       -> 200  ok
both (codex)               -> 200  ok
UA=claude-cli              -> 200  ok

verdict: 存在客户端校验；「originator=codex_cli_rs」可放行。
fix: 在你的客户端加上对应请求头即可（relay-mask snippet 生成配置）。

生成修复配置

relay-mask snippet --client dsh --url https://ps.example.com/v1 \
--name ps --key-name PS_API_KEY --models gpt-5.6-sol,claude-opus-5

各客户端修复片段

DeepSeek Harness（settings.yaml，热加载免重启）

在 ~/.dsh/settings.yaml 的 llm-pi-ai.providers 下加入（关键就是 headers: 两行）：

llm-pi-ai:
providers:
my-relay:
displayName: My Relay
apiKeyEnv: MY_RELAY_API_KEY
api: openai-completions        # 中转支持 Responses 协议可改 openai-responses
baseURL: https://your-relay.example.com/v1
headers:
originator: codex_cli_rs     # ← 绕过客户端校验的关键
models:
- id: gpt-5.6-sol
input: []
compat: {}

API Key 二选一存放：

- DSH Web GUI → Models 页面添加 MY_RELAY_API_KEY；
- 或编辑 ~/.dsh/.credentials.yaml：
refs:
MY_RELAY_API_KEY: sk-xxxx

注意：DSH 会强制覆盖 user-agent（保留头，配置无效），但 originator 等其他头可通过 headers 自由添加——实测多数中转认 originator 就放行。

Codex CLI（原生指纹直连）

Codex CLI 天然携带 codex 指纹，指向中转即可，~/.codex/config.toml：

[model_providers.my-relay]
name = "my-relay"
base_url = "https://your-relay.example.com/v1"
env_key = "RELAY_API_KEY"
wire_api = "responses"   # 中转只支持 chat 协议时改为 "chat"

Claude Code（原生指纹直连）

export ANTHROPIC_BASE_URL=https://your-relay.example.com
export ANTHROPIC_AUTH_TOKEN=$RELAY_API_KEY
中转额外要求特定请求头时：
export ANTHROPIC_CUSTOM_HEADERS="x-app: cli"

OpenAI SDK（自己写代码）

import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://your-relay.example.com/v1",
apiKey: process.env.RELAY_API_KEY,
defaultHeaders: { originator: "codex_cli_rs" },
});

from openai import OpenAI
client = OpenAI(
base_url="https://your-relay.example.com/v1",
api_key=os.environ["RELAY_API_KEY"],
default_headers={"originator": "codex_cli_rs"},
)

curl

curl https://your-relay.example.com/v1/chat/completions \
-H "Authorization: Bearer $RELAY_API_KEY" \
-H "Content-Type: application/json" \
-H "originator: codex_cli_rs" \
-d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"hi"}]}'

实测记录（2026-08，ps.air-outer.com）

| 请求姿势 | 结果 |
|---|---|
| 无伪装 | 401 unauthorized client detected |
| 仅 originator: codex_cli_rs | ✅ 200 |
| 仅 codex UA | ✅ 200 |
| claude-cli UA | ✅ 200 |
| claude 系模型走 /responses | ❌ 500 → 改走 /chat/completions |

FAQ

为什么不做成代理服务？
请求头由发起方写入，浏览器外的桌面程序无法在程序外改头。凡是客户端自带自定义头/base_url 配置的（DSH、Claude Code、Codex、各 SDK），加头即可，不需要任何常驻进程。只有「既不支持自定义头又非浏览器」的场景才需要本地代理——那是最后手段。

probe 全部 401？
先确认 key 有效；再试 --model 换成中转实际提供的模型名；仍不行说明该中转校验更严（如 IP 绑定、指令特征），欢迎提 issue 附上脱敏 probe 输出。

安全吗？会不会泄露 key？
本工具不收集任何数据；probe 只向你指定的 baseURL 发请求。请勿把真实 key 写进 issue。

免责声明

本项目仅用于让你有权使用的中转服务在你自己的客户端中正常工作。请遵守你与服务商之间的约定，勿用于滥用或转售场景。

License

MIT © 9Rebels