[opencode 请求流程分析] OpenCode 请求流程与请求 Header 分析(2026-07-20)

[github-actions]

⚠️ 近期相关变更

SHA	描述
67caf89	fix(opencode): increase OpenAI header timeout (#37770) — OPENAI_HEADER_TIMEOUT_DEFAULT 从 10,000 ms → 300,000 ms(provider/provider.ts:35)
6a28842	go: support openai route — Go 客户端支持 OpenAI 路由

---

1. 请求流程(时序)

sequenceDiagram
    participant S as Session/Prompt
    participant R as LLMRequest.prepare<br/>(session/llm/request.ts)
    participant C as LLMClient.compile()<br/>(llm/route/client.ts)
    participant E as protocol.body.from()<br/>(protocols/*.ts)
    participant T as HttpTransport.prepare()<br/>(transport/http.ts)
    participant A as Auth.apply()<br/>(route/auth.ts)
    participant X as RequestExecutor<br/>(route/executor.ts)
    participant API as LLM Provider

    S->>R: PrepareInput(model, messages, tools, auth, flags)
    R->>R: 合并 system prompt / options<br/>注入 User-Agent / x-session-* header
    R->>C: LLMRequest { model, messages, http:{headers} }
    C->>C: resolveRequestOptions() 合并 routeDefaults+modelDefaults
    C->>E: route.body.from(request) 构造 provider-native body
    E-->>C: Body JSON
    C->>T: prepareTransport(body, request)
    T->>T: jsonRequestParts() 渲染 URL / body overlay
    T->>A: Auth.apply(url, body, headers)
    A-->>T: Headers(含鉴权 header)
    T->>T: jsonPost() 设置 content-type: application/json
    T-->>C: HttpPrepared { request, framing }
    C->>X: RequestExecutor.execute(httpRequest)
    X->>X: 重试 429/503/504/529,最多 2 次,指数退避
    X->>API: HTTP POST (SSE 流)
    API-->>X: SSE 事件流
    X-->>S: Stream<LLMEvent>

Loading

关键步骤:

步骤	文件 & 符号
Provider/Model 解析	packages/opencode/src/provider/provider.ts → Provider.Service
凭据获取	packages/opencode/src/provider/auth.ts → ProviderAuth.Service
请求头/参数构造	packages/opencode/src/session/llm/request.ts → prepare()
Route defaults 合并	packages/llm/src/route/client.ts → resolveRequestOptions() / compile()
Body 构造	packages/llm/src/protocols/*.ts → protocol.body.from()
Header 组装 + Auth 注入	packages/llm/src/route/transport/http.ts → jsonRequestParts()
content-type 设置	packages/llm/src/protocols/shared.ts:322 → jsonPost()
执行 + 重试	packages/llm/src/route/executor.ts → retryStatusFailures()

---

2. 请求 Header 明细

通用 Header(所有 Provider)

Header	取值来源	说明
content-type	protocols/shared.ts:322	固定 application/json
User-Agent	session/llm/request.ts:18 USER_AGENT = \opencode/\${InstallationVersion}``	客户端版本标识
x-session-affinity	request.ts:197	会话亲和(外部 provider)
X-Session-Id	request.ts:198	会话 ID(外部 provider)
x-parent-session-id	request.ts:199(可选)	父会话 ID
x-opencode-project	request.ts:190(opencode provider 专用)	项目 ID
x-opencode-session	request.ts:191(opencode provider 专用)	会话 ID
x-opencode-request	request.ts:192(opencode provider 专用)	请求 ID
x-opencode-client	request.ts:193(opencode provider 专用)	客户端类型

Anthropic

端点:`(api.anthropic.com/redacted)

Header	取值来源	说明
x-api-key	providers/anthropic.ts:13 Auth.header("x-api-key");优先级:apiKey 选项 → ANTHROPIC_API_KEY env	API 鉴权密钥
anthropic-version	protocols/anthropic-messages.ts:852 固定 "2023-06-01"	API 版本锁定

OpenAI

端点:(api.openai.com/redacted) API)/ /chat/completions`

Header	取值来源	说明
authorization	route/auth-options.ts:46 Bearer <apiKey>;优先级:apiKey 选项 → OPENAI_API_KEY env	Bearer 鉴权

OAuth 模式:provider.ts:539 自定义 fetch 注入 Bearer token,并启用 headerTimeout=300_000ms 超时保护。

Azure OpenAI

端点:https://<resource>.openai.azure.com/openai/v1/responses,Query: api-version=v1

Header	取值来源	说明
api-key	providers/azure.ts:auth() Auth.header("api-key");优先级:apiKey 选项 → AZURE_OPENAI_API_KEY env	Azure 专用鉴权 header(非 Bearer)

注意:Azure 路由主动 Auth.remove("authorization") 删除默认 Bearer header,防止冲突。

Amazon Bedrock

端点:(bedrockruntime/redacted)<region>.amazonaws.com/model/<modelId>/converse-stream

Header	取值来源	说明
authorization	protocols/utils/bedrock-auth.ts:sigV4() → AwsV4Signer 生成 AWS4-HMAC-SHA256 Credential=...	AWS SigV4 签名鉴权
x-amz-date	AwsV4Signer 自动生成	签名时间戳
x-amz-security-token	AwsV4Signer(有 sessionToken 时)	STS 临时凭据
content-type	bedrock-auth.ts:43 在 签名前 设置	必须参与 SigV4 签名计算

指定 apiKey 时退化为标准 Bearer 模式。

Google Gemini

端点:`(generativelanguage.googleapis.com/redacted)

Header	取值来源	说明
x-goog-api-key	providers/google.ts:13 Auth.header("x-goog-api-key");优先级:apiKey 选项 → GOOGLE_GENERATIVE_AI_API_KEY env	Google AI API 鉴权密钥

GitHub Copilot

端点:由调用方显式配置(无公开默认 URL);协议:openai-responses(GPT-5+)/ openai-chat

Header	取值来源	说明
authorization	providers/github-copilot.ts AuthOptions.bearer(options, []);token 来自 OAuth 流程(provider/auth.ts)	OAuth Bearer 鉴权

OpenAI 兼容(OpenRouter / xAI / Groq / DeepSeek 等)

Header	取值来源	说明
authorization	route/auth-options.ts:46 Bearer;各 provider env 变量:OPENROUTER_API_KEY / XAI_API_KEY 等	Bearer 鉴权

---

3. 鉴权机制

Provider	方式	关键代码
Anthropic	API Key → x-api-key	providers/anthropic.ts:11-17
OpenAI	Bearer;OAuth 时使用 access token	route/auth-options.ts:46;provider/provider.ts:539
Azure	API Key → api-key(非 Bearer)	providers/azure.ts:auth()
Bedrock	AWS SigV4(默认)或 Bearer(指定 apiKey)	protocols/utils/bedrock-auth.ts:sigV4()
Google	API Key → x-goog-api-key	providers/google.ts:11-16
GitHub Copilot	OAuth Bearer	providers/github-copilot.ts;provider/auth.ts
OpenRouter/xAI/兼容	Bearer	providers/openrouter.ts;providers/xai.ts

Auth 框架核心(packages/llm/src/route/auth.ts):

• Credential:封装异步加载,.orElse() 支持降级链
• Auth:封装 header 注入,.andThen() 顺序应用,.orElse() 降级
• 敏感 header 在错误日志中自动脱敏(executor.ts SENSITIVE_NAME 正则匹配 authorization|api-key|token|secret|signature...)

---

4. 关键代码位置索引

文件	关键符号	说明
packages/llm/src/route/client.ts	compile()、resolveRequestOptions()	请求编译主流程
packages/llm/src/route/auth.ts	Auth、bearer()、header()、custom()	鉴权框架
packages/llm/src/route/auth-options.ts:46	AuthOptions.bearer()	标准 Bearer 构建
packages/llm/src/route/transport/http.ts	jsonRequestParts()、httpJson()	Header 最终组装
packages/llm/src/route/executor.ts	retryStatusFailures()、SENSITIVE_NAME	HTTP 执行、重试、脱敏
packages/llm/src/protocols/shared.ts:320-322	jsonPost()	设置 content-type
packages/llm/src/protocols/anthropic-messages.ts:852	route headers	注入 anthropic-version
packages/llm/src/protocols/utils/bedrock-auth.ts	sigV4()	AWS SigV4 签名
packages/llm/src/providers/anthropic.ts:11-17	auth()	Anthropic 鉴权
packages/llm/src/providers/azure.ts	auth()、routeAuth	Azure 鉴权
packages/llm/src/providers/google.ts:11-16	auth()	Google 鉴权
packages/opencode/src/session/llm/request.ts:18,186-201	USER_AGENT、headers 构造	会话 Header 注入
packages/opencode/src/provider/provider.ts:35	OPENAI_HEADER_TIMEOUT_DEFAULT=300_000	OpenAI 首字节超时

Generated by Daily Upstream Sync + Request-Flow Analysis · 89.3 AIC · ⌖ 7.04 AIC · ⊞ 5.9K · ◷