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

[github-actions]

本次变更提示

近 20 次提交主要包含新增 DeepSeek v4 Flash 模型、app 修复等,不影响请求流程与 Header 构造核心逻辑。新增 DeepSeek 模型走 OpenAI-Compatible-Chat 协议,与现有 Header 方案一致。

---

1. 请求流程总览

opencode 存在两套并行 LLM 请求路径:

路径	入口	协议层
Native	session/llm/native-request.ts	packages/llm/src/(原生协议)
AI SDK	session/llm/ai-sdk.ts	Vercel AI SDK(OpenAI-compatible 等)

两路共用预处理层:session/llm/request.ts → LLMRequestPrep.prepare()

1.1 分步说明

用户 Prompt → session/*.ts
  ↓ 1. 组装 PrepareInput
LLMRequestPrep.prepare()  [session/llm/request.ts]
  • 解析 model/provider(Provider.list())
  • 合并 system prompt、messages
  • plugin.trigger("chat.headers") 收集插件 headers
  • 构造公共 headers(User-Agent、x-session-affinity 等)
  ↓ 2. Prepared 对象
      ┌─────────────────────┐
  AI SDK 路径          Native 路径
  ai-sdk.ts           LLMClient.stream()  [route/client.ts]
                        ↓ 3. compile()
                      route.body.from()  [Protocol 实现]
                        → provider-native JSON Body
                        ↓ 4. route.prepareTransport()
                      jsonRequestParts()  [transport/http.ts]
                        → renderEndpoint() → URL
                        → Auth.apply() → 注入鉴权 Header
                        → ProviderShared.jsonPost()
                          content-type: application/json
                        ↓ 5. RequestExecutor.execute()  [executor.ts]
                          含自动重试(最多 2 次)
                          429/503/504/529 → 指数退避
                        ↓
                      HTTP POST → Provider Endpoint
                      响应流 → Framing.sse / BedrockEventStream
                      → protocol.stream.step() → LLMEvent

---

2. 请求 Header 明细

公共 Headers(所有 provider)

Header	取值来源	说明
content-type	protocols/shared.ts:322 jsonPost()	application/json
User-Agent	session/llm/request.ts:194,200	opencode/<version>
x-session-affinity	request.ts:188	Session ID(非 opencode provider)
X-Session-Id	request.ts:189	Session ID(兼容命名)
x-parent-session-id	request.ts:190	父 Session ID(若存在)

opencode 私有 provider 额外附加:x-opencode-project、x-opencode-session、x-opencode-request、x-opencode-client(均来自 request.ts:190-193)

---

2.1 Anthropic

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

Header	取值来源	说明
anthropic-version	protocols/anthropic-messages.ts:852	固定 2023-06-01
x-api-key	providers/anthropic.ts:12-17 Auth.header("x-api-key")	优先 apiKey 选项,回退 ANTHROPIC_API_KEY

2.2 OpenAI / OpenAI-Compatible

端点: (api.openai.com/redacted),responses}

Header	取值来源	说明
Authorization	route/auth-options.ts:bearer()	Bearer (OPENAI_API_KEY)

OpenAI-Compatible 子 provider(DeepSeek/Groq/Cerebras/xAI 等)同上,各自回退对应环境变量。

2.3 Azure OpenAI

端点: https://(resourceName).openai.azure.com/openai/v1/...

Header	取值来源	说明
api-key	providers/azure.ts:67-71 Auth.header("api-key")	Azure 专用,源自 apiKey 或 AZURE_OPENAI_API_KEY
Query api-version	providers/azure.ts:35,43	URL 查询参数,默认 v1

Azure 先用 Auth.remove("authorization") 移除 Bearer,再注入 api-key(azure.ts:12)

2.4 Amazon Bedrock (SigV4)

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

Header	取值来源	说明
Authorization	protocols/utils/bedrock-auth.ts:signRequest()	AWS SigV4 签名,aws4fetch 库生成
x-amz-date	bedrock-auth.ts:AwsV4Signer.sign()	SigV4 时间戳
x-amz-security-token	bedrock-auth.ts	临时凭证 Token(有 sessionToken 时)

凭证来源优先级:1 credentials 对象 → 2 API Key(Bearer Token)→ 3 fromNodeProviderChain()(profile/IAM/Web Identity)

2.5 Google Gemini

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

Header	取值来源	说明
x-goog-api-key	providers/google.ts:14-18 Auth.header("x-goog-api-key")	优先 apiKey,回退 GOOGLE_GENERATIVE_AI_API_KEY

2.6 Google Vertex AI

Header	取值来源	说明
Authorization	provider/provider.ts:536-539 GoogleAuth.getAccessToken()	Bearer <oauth-token>,ADC 自动获取

2.7 GitHub Copilot

端点: 调用方显式配置 baseURL(无公开默认)

Header	取值来源	说明
Authorization	providers/github-copilot.ts:36,42 AuthOptions.bearer(options, [])	Bearer <token>,来自 OAuth 客户端 getAccessToken()

2.8 OpenRouter / LLMGateway / NVIDIA / Vercel(平台识别)

除 Authorization: Bearer <API_KEY> 外,via provider/provider.ts:456-496:

Header	适用 Provider	说明
`HTTP-Referer: (opencode.ai/redacted)	openrouter/llmgateway/nvidia/vercel	平台来源标识
X-Title: opencode	同上	应用名称
X-Source: opencode	llmgateway	额外来源标识
X-BILLING-INVOKE-ORIGIN: OpenCode	nvidia	计费来源

---

3. 鉴权机制

机制	适用 Provider	实现位置
API Key Bearer Token	OpenAI/xAI/OpenAI-Compatible/Copilot 等	route/auth-options.ts:bearer() → route/auth.ts:bearer()
Custom Header (x-api-key)	Anthropic	providers/anthropic.ts:12-17 → Auth.header("x-api-key")
Custom Header (x-goog-api-key)	Google Gemini	providers/google.ts:14-18
Custom Header (api-key)	Azure OpenAI	providers/azure.ts:55-72
AWS SigV4	Amazon Bedrock	protocols/utils/bedrock-auth.ts:sigV4() + aws4fetch
Google OAuth ADC	Google Vertex AI	provider/provider.ts:529-539 + google-auth-library
GitHub OAuth Token	GitHub Copilot	provider/provider.ts:535-539 + @ai-sdk/github-copilot

---

4. 关键代码位置索引

文件	关键符号	说明
packages/opencode/src/session/llm/request.ts	LLMRequestPrep.prepare()	请求预处理,公共 headers
packages/llm/src/route/client.ts	compile()	核心编译:body → transport
packages/llm/src/route/transport/http.ts	jsonRequestParts()	HTTP 组装,auth 注入
packages/llm/src/route/auth.ts	credential(), bearer(), header(), custom()	鉴权抽象
packages/llm/src/route/auth-options.ts	AuthOptions.bearer()	Bearer 鉴权工厂
packages/llm/src/route/executor.ts	RequestExecutor.layer, retryStatusFailures()	HTTP 执行 & 重试
packages/llm/src/protocols/anthropic-messages.ts:845-852	route	anthropic-version header
packages/llm/src/protocols/openai-chat.ts:497-502	route	OpenAI Chat 路由
packages/llm/src/protocols/bedrock-converse.ts:658-668	route	Bedrock 路由
packages/llm/src/protocols/utils/bedrock-auth.ts	sigV4()	AWS SigV4 签名
packages/llm/src/providers/azure.ts:55-72	auth()	Azure api-key
packages/opencode/src/provider/provider.ts:456-543	各 provider handler	Vertex OAuth、OpenRouter headers 等
packages/llm/src/protocols/shared.ts:320-322	jsonPost()	content-type: application/json

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