> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/reference/template-variables · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 模板变量速查

网关在多个配置处支持 `{{变量}}` 表达式：在请求时按当前请求上下文替换为实际值，用于把动态信息（访问密钥、请求 ID、会话头、system 提示词哈希等）注入到发往上游的 header 或请求体里，驱动上游日志关联、缓存键、粘性会话绑定等场景。

## 变量总表

| 变量 | 来源 | 说明 |
|------|------|------|
| `{{request_access_key_name}}` | 认证访问密钥名 | 匹配的 `AccessKey` 条目中的名称；未认证时为空 |
| `{{request_access_key_group}}` | 访问密钥分组名 | 该密钥所属分组名（多组以逗号连接）；未认证时为空 |
| `{{request_id}}` | `z-request-id` 请求头 | 客户端 `z-request-id` 头中的唯一请求 ID |
| `{{access_key_hash}}` | 访问密钥 SHA-256 哈希 | 访问密钥原文 SHA-256 哈希的前 16 字节，base64url 编码（22 字符，确定性） |
| `{{system_prompt_hash}}` | system 提示词 SHA-256 | system 提示词内容的 sha256 小写十六进制摘要，协议无关，兼容 Anthropic `system`、OpenAI `messages[role=system]`、DashScope `input.messages[role=system]`、Google `system_instruction` 四种放置方式 |
| `{{header:Key}}` | 客户端请求头 | 客户端 `Key` 请求头的值，大小写不敏感；头值前后空白视为缺失 |

## 可用范围（哪些上下文支持哪些变量）

并非每个变量在每个配置处都可用——取决于该处是否持有对应的请求上下文。下表标明各配置处可用的变量：

| 变量 | 上游/模型 `headers`·`user_agent` | `request_payload` 的 `value` | 负载均衡器 `binding_key_template` |
|------|:---:|:---:|:---:|
| `{{request_access_key_name}}` | ✅ | ✅ | ✅ |
| `{{request_access_key_group}}` | ✅ | ✅ | ✅ |
| `{{request_id}}` | ✅ | ✅ | ✅ |
| `{{access_key_hash}}` | ✅ | ❌（恒空） | ✅ |
| `{{system_prompt_hash}}` | ✅ | ✅ | ❌（恒空） |
| `{{header:Key}}` | ✅ | ✅ | ✅ |

两个"恒空"的成因是上下文边界，不是 bug：

- **`request_payload` 的 `value` 里 `access_key_hash` 恒空**：请求体改写阶段在协议转换之后执行，出于安全不持有访问密钥原文，算不出哈希。需要缓存键兜底时改用 `system_prompt_hash`。
- **`binding_key_template` 里 `system_prompt_hash` 恒空**：绑定键解析发生在请求体可用的更早阶段（路由/LB 解析期），此时还没拿到请求体，无法提取 system 提示词。粘性会话的绑定键通常用 `access_key_hash` 或会话头。

> ⚠️ 在不支持某变量的上下文里写它，该变量解析为空字符串——若它落在回退链末端且链中其余变量也空，整条链空，该 header/写入被省略（绑定键则回退为原始 API key）。配置加载时模板校验为 warn-don't-block，不会锁死启动。

## 回退链语法 {#fallback-chain}

`{{var1|var2|var3}}` 用 `|` 分隔多个候选变量，**按顺序取第一个非空的**：前一个不可用（未认证 / 头缺失 / 上下文不支持）则试下一个；全部为空则替换为空字符串。`{{header:Name}}` 也可作为回退链的一员。未知变量（不在总表、非 `header:` 前缀）在链中被跳过而非报错。

空值处理因配置处而异：

- **header / `user_agent`**：替换值完全为空时该 header 被省略（不发送空字符串）。
- **`request_payload` 的 `value`**：链全空时本次写入被省略（不创建该字段，不写空字符串常量）。
- **`binding_key_template`**：链全空时回退为原始访问密钥作绑定键（保证每会话唯一，避免所有请求挤进同一个动态绑定会话）。模板含未解析 `{{...}}` 时同样回退。

## 典型用法

### 会话键控的上游缓存键（header，多级回退）

在控制台里：打开上游或模型 → **自定义请求头** → 新增标头 `X-Conversation-Id`，值填 `{{header:x-claude-code-session-id|access_key_hash|system_prompt_hash}}`。

逐级降级：有会话头→用头（同会话同键，命中上游缓存）；无头但已认证→用 access key 哈希（同用户共享缓存）；两者皆无→用 system 哈希（同 system 提示词同键）。三者皆空时省略该 header。

### 上游缓存字段注入（`request_payload`，body 级）

在控制台里：打开模型详情（或上游的「默认请求体规则」）→ **请求体规则** → **+ 添加规则** → 模式选 `overwrite` → 路径填 `prompt_cache_key` → 值填 `{{header:x-claude-code-session-id|system_prompt_hash}}`。

注意此处 `access_key_hash` 不可用（恒空），缓存键兜底用 `system_prompt_hash`。规则在协议转换之后应用，写入的上游私有字段不会被翻译丢弃。详见 [上游与模型字段 — 请求体修改](/zh-CN/reference/upstreams-models-fields.md)。

### 粘性会话绑定键（`binding_key_template`）

在控制台里：打开负载均衡器 → 编辑 → 开启「会话粘性」→「绑定请求头」字段填 `{{header:X-Session-Id|access_key_hash}}`。

注意此处 `system_prompt_hash` 不可用（恒空），绑定键兜底用 `access_key_hash` 或会话头。详见 [开启粘性会话](/zh-CN/howto/enable-sticky-session.md)。

## 相关章节

- 上游/模型 header 与 `user_agent` 模板：[上游与模型字段](/zh-CN/reference/upstreams-models-fields.md)
- `request_payload` value 表达式：[上游与模型字段 — 请求体修改](/zh-CN/reference/upstreams-models-fields.md)
- `binding_key_template`：[负载均衡字段](/zh-CN/reference/load-balancing-fields.md)
- 回退链解析的精确行为：见本页[回退链语法](#fallback-chain)一节
- 全部环境变量：[环境变量配置参考](/zh-CN/reference/configuration.md)