llm-session-proxy

解决什么问题

OpenCode Go 要求每个请求带会话标识，而多数客户端没法自定义请求头。

上游要求这样一行头：

x-opencode-session : 会话 ID，同一对话内保持稳定（用于提示词缓存与路由优化）

客户端不发，上游就直接拒绝：

400 Request is missing x-opencode-session and cannot be routed efficiently

本工具把这件事挪到本机完成：客户端只管把 Base URL 指向本地代理，剩下的事代理来办。 它不绑定任何一家上游——换掉 upstream 和 inject.headers 就能服务任意 OpenAI / Anthropic 兼容接口。

核心能力

每一项都可通过配置文件、环境变量或命令行参数调整。

快速开始

要求 Node.js ≥ 18。

# 默认配置就是 OpenCode Go，直接启动
npx llm-session-proxy

# 客户端 Base URL 填：http://127.0.0.1:9355/zen/go/v1
# 模型 ID 填：proxy- + 真实模型名，例如 proxy-glm-5.3-flash
# API Key 填：你的 OpenCode API Key

npx llm-session-proxy \
  --upstream https://api.deepseek.com \
  --port 8788 \
  --inject "x-session-id={{session.id}}" \
  --inject "x-trace-id={{uuid}}" \
  --model-map fast=deepseek-chat \
  --model-map smart=deepseek-reasoner \
  --model-prefix ""

# 客户端 Base URL 填 http://127.0.0.1:8788/v1
# 模型名可以用 fast / smart 这类短别名

# 生成带注释的示例配置
npx llm-session-proxy --init

# 按需修改后启动
npx llm-session-proxy -c llm-session-proxy.config.json

{
  // 支持 // 与 /* */ 注释、尾随逗号
  "listen": { "host": "127.0.0.1", "port": 9355 },
  "upstream": { "host": "opencode.ai" },
  "inject": {
    "headers": {
      "x-opencode-session": "{{session.id}}",
      "x-opencode-request": "{{session.requestId}}"
    }
  },
  "model": { "stripPrefixes": ["proxy-"] }
}

客户端 Base URL 怎么填

OpenCode Go 常见模型速查表

上游把模型分在三类端点上——能不能用取决于客户端发什么协议，这比模型名更关键。 下表每一行的客户端模型 ID 都能开箱解析：别名已内置在代理里， 想确认某个别名最终会变成什么，跑一次 npx llm-session-proxy --dry-run --model proxy-glm 即可。

① /zen/go/v1/chat/completions · OpenAI 兼容，绝大多数客户端走这条

② /zen/go/v1/responses · OpenAI Responses API，客户端需支持该协议

③ /zen/go/v1/messages · Anthropic 协议，客户端需能发 Anthropic 格式

配置参考

优先级：默认值 < 配置文件 < 环境变量 < 命令行参数。

upstream —— 转发目标

session —— 会话 ID

inject —— 参数注入

model —— 模型名重写

transformers —— 请求体变换（始终生效）

只能写名字：注册表是编译进代理里的固定清单，配置文件无法让它执行任意代码。

顺序会影响结果，因为每个变换都是原地改请求体：rename-fields 放在 drop-fields 前面，和反过来跑，结果不一样。名字不在上表里是启动即报错， 不会静默忽略。

router —— 分桶与规则

一个桶决定两件事：用哪个模型、挂哪些变换。enabled 默认 false，所以现有配置在你主动打开之前行为完全不变。

"router": {
  "enabled": true,
  "defaultBucket": "default",
  "buckets": {
    "think":       { "model": "glm-5.3-think" },
    "longContext": { "model": "glm-5.3-long" },
    "background":  { "model": "glm-5.3-flash", "transformers": ["clamp-max-tokens"] }
  },
  "rules": [
    { "bucket": "think",       "path": "/zen/go/v1/messages" },
    { "bucket": "longContext", "minBytes": 60000 },
    { "bucket": "background",  "modelPrefix": "proxy-haiku", "maxBytes": 4096 }
  ]
}

桶的 transformers 是追加到全局 transformers.enabled 后面的：桶只能加、不能取消全局的某个变换。桶的 model 在别名重写之后生效并 直接替换结果，所以这里应当写真实的上游模型 ID、而不是 proxy- 别名。引用 {{model}} 的请求头模板看到的是桶覆盖后的值，因为注入是最后一步。

protocol —— 协议互转

代理从请求路径推断客户端的协议（/chat/completions → chat、/messages → messages、/responses → responses），再由路由决定上游说哪套。两者不同时：请求体转发前整体转换，响应回来前转换回去——JSON 整包改写，SSE 按事件逐条转码。enabled 默认 false。

"protocol": {
  "enabled": true,
  "paths": {
    "chat": "/zen/go/v1/chat/completions",
    "messages": "/zen/go/v1/messages",
    "responses": "/zen/go/v1/responses"
  },
  "routes": [
    { "model": "minimax", "target": "messages" },
    { "model": "gpt", "target": "responses" }
  ]
}

字段归一化是内建的：max_tokens ↔ max_completion_tokens ↔ max_output_tokens；reasoning_effort ↔ thinking.budget_tokens （固定表 1024 / 8192 / 16384，反向按阈值反推）；工具声明与工具调用在三种形状间重塑； stop ↔ stop_sequences；chat 的 system 消息 ↔ Anthropic 的顶层 system ↔ Responses 的 instructions。没有等价物的字段逐个记名 丢进日志里的 dropped 列表。Anthropic 必填 max_tokens，chat 请求两个名字 都没带时补一个记入日志的 4096，而不是等上游 400。上游 4xx/5xx 错误体永不转换—— 错误是上游协议的一部分，原样回传。

模板变量

命令行参考

所有选项都能与配置文件混用，命令行优先级最高。

日志

默认就会写日志文件，因为最难查的故障——未捕获异常、进程悄无声息地消失——恰恰是终端窗口一关就什么线索都不剩的那类。 默认位置是 $LSP_HOME/logs/llm-session-proxy.log；未设置 LSP_HOME 时是 ~/.lsp/logs/llm-session-proxy.log。用 --log-file <path> / --log-dir <dir> 覆盖，用 --no-log-file 关掉。

归档。启动时、以及运行期间最多每 6 小时一次，符合命名规则 （app.log、app.log.N、app-YYYY-MM-DD.log）且 mtime 早于 log.keepDays（默认 30 天）的文件会被删除。正在写的文件永不删除；不符合命名规则的文件—— 包括同目录里其他任何文件——一律不动。

# 日志实际会落在哪儿？
llm-session-proxy --print-config | grep resolvedFile

启动前自检：--dry-run 与 --doctor

两个参数都会校验配置、把代理接下来实际会做的事打印出来，然后退出——不起服务、不写日志文件、 不向上游发任何请求。注入那张表打印的不是模板原文，而是渲染后的结果， 所以模板写错了会在这里暴露，而不是等上游回一个 400。

$ llm-session-proxy --dry-run
llm-session-proxy v0.2.2 —— 试运行

模型
  样例            proxy-glm
  剥离            前缀 "proxy-" -> glm
  映射            glm -> glm-5.3
  结果            glm-5.3  （命中映射）
  映射表          内置 27 条，覆盖 0 条

路由分桶
  启用            否
  默认桶          default
  桶 default      （无）
  桶 background   （无）
  桶 think        （无）
  桶 longContext  （无）
  规则            （无规则）
  样例路由        default（路由已关闭）

变换
  全局            （无）
  生效            （无）
  可用            noop, drop-fields, drop-empty-fields, rename-fields, clamp-max-tokens

协议互转
  启用            否（原样透传）
  路径            chat=/zen/go/v1/chat/completions，messages=/zen/go/v1/messages，responses=/zen/go/v1/responses
  规则            （无规则）
  样例转换        样例请求不发生转换

结果
  通过 —— 配置有效。

路由分桶与变换两段回答的是「这条请求会落进哪个桶、会被怎么改」。以上文 router 的配置为例：

路由分桶
  启用            是
  默认桶          default
  桶 default      （无）
  桶 background   model=glm-5.3-flash transformers=clamp-max-tokens
  桶 think        model=glm-5.3-think
  桶 longContext  model=glm-5.3-long
  #0              path^=/zen/go/v1/messages -> think
  #1              bytes>=60000 -> longContext
  #2              model~=proxy-haiku* AND bytes<=4096 -> background
  样例路由        default（默认桶，/v1/chat/completions 未命中任何规则）

变换
  全局            drop-empty-fields
  生效            drop-empty-fields
  可用            noop, drop-fields, drop-empty-fields, rename-fields, clamp-max-tokens

#0/#1/#2 就是按顺序排列的规则，path^= 表示「路径以此开头」，model~= 表示「模型前缀」。样例路由 那行是真的拿一条 POST /v1/chat/completions 跑了一遍匹配，所以它落在兜底路径上：一条规则都没命中， 请求进默认桶。--router think 会覆盖这一切：样例路由 think（由 --router 强制）。 生效 才是真正会执行的那串——全局列表在前，命中的桶往里追加。

协议互转那段回答「这条请求会不会被转换、转成什么」。加了 --protocol messages 之后，强制目标与样例转换行会变成（样例转换同时给出转换后请求要走的上游路径）： chat -> messages /zen/go/v1/messages。英文输出里这一段叫 Protocol。

--doctor 在同一份报告之上追加 DNS 解析、TCP 连接与握手耗时、协议为 https 时的 TLS 握手（证书不受信任会如实报出，但不算硬失败）、监听端口是否空闲，以及一句「代理从不注入凭据」的提醒。 它不发 HTTP 请求、不带任何凭据——连通性只问到传输层为止——所以跑体检不会消耗你的速率配额。 一切正常退出码为 0，有问题为 1，可以直接当启动闸门用：

llm-session-proxy --doctor && llm-session-proxy

本地状态端点

# 运行概览：会话数、命中率、注入的头、上游地址
curl http://127.0.0.1:9355/__llm_session_proxy__/status

# 会话明细：每个会话的 ID、请求数、最后使用时间
curl http://127.0.0.1:9355/__llm_session_proxy__/sessions

排错时很有用：如果 sessions.active 一直是 0，说明请求根本没到代理—— 多半是模型 ID 没加 proxy- 前缀，被客户端截走了。

工作原理

每个请求按固定顺序处理，会话识别的三级策略是关键。

03～06 的顺序是刻意排的：规则能同时看到客户端原始模型名和解析后的模型名；桶的模型覆盖落在 别名解析之后，所以它只可能是真实 ID；注入放在倒数第二步，请求头里的 {{model}} 反映的是最终决定；协议互转放在所有步骤之后——变换与注入针对的是客户端协议下的字段名， 等请求体定稿了才整体翻译。

会话识别的三级策略

显式标识——客户端自己发了 x-opencode-session，或请求体里有 session_id。直接复用，最准。

内容指纹——对 system + 首条 user 消息做 SHA-256。同一对话的后续轮次只是往后追加消息， 首条不变，所以指纹稳定，能落回同一个 ID。

一次性随机——两者都没有时（比如请求体不是 JSON），发一个随机 ID，只保证上游不报 400； 这类请求不进会话表，避免把表撑爆。

稳定性

单个畸形请求不会让进程退出。非法 Host 头、畸形请求行、上游返回含非法字符的状态行或响应头，都会被转成对应的 4xx / 5xx，进程继续服务。

未捕获异常会写进日志文件。兜底处理器把 uncaughtException 与 unhandledRejection 的完整栈写进日志文件。Node 默认只打 stderr 就终止进程，日志文件里一片空白——现场看起来就是「日志正常、进程凭空消失」。正因如此，文件日志默认就是开着的，详见日志一节。

限制与注意

只监听本机。代理会带上你的 API Key 转发请求，不要把监听地址改成 0.0.0.0。

response.stream: false 会破坏 SSE。除非确实需要整体缓冲，否则保持默认的 true。

bufferBody: false 时无法改写请求体。模型重写和参数注入会失效，只能注入请求头。

内置映射表是某个时间点的快照，不是实时目录。上游的模型 ID 会不作通知地变更， 而本代理刻意不通过网络去发现它们。某个别名哪天解析不出来了，那是配置里改一行的事，不是 bug—— 发真实请求之前先用 --dry-run 看一眼每个别名最终变成了什么。

协议互转在边缘处刻意有损。Anthropic 的 thinking / signature 流增量在 chat 里没有标准位置，会丢弃（日志里记名）；messages ↔ responses 经 chat 中转，不做直达转换器。保下来的是文本、工具调用、结束原因与 usage——客户端真正会用的就这些。 变换注册表依然是写死的清单：代理绝不会从某个路径加载变换。

路线图

零依赖、本地、单进程——每一项都必须符合这个形状。完整的取舍、与同类网关的对照，以及明确的非目标，见 ROADMAP.zh-CN.md。

v0.2 的性能目标由随仓库一起提供的工具测量：对本地 mock 上游的附加延迟 ≤ 1 ms（p50）与 ≤ 5 ms（p99）、100 并发连接下 ≥ 1,200 RPS、畸形输入语料下进程零退出、SSE 逐字节透传。 基准数字必须与测量口径一起发布——没有口径的基准说明不了任何问题。

刻意不放进路线图的：虚拟密钥与计费、本地跑模型、托管版本、插件市场、Kubernetes operator。它们都会和「零依赖、本地、单进程」这个形状相抵触。