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

[github-actions]

近期变更提示

• 38e10eb fix(opencode): ignore unknown config fields — 配置解析更健壮
• fe82a1b chore: generate — SDK 重新生成,协议/客户端接口可能更新
• 其余提交(UI/i18n/排序)不直接影响请求流程

---

一、请求流程

sequenceDiagram
    participant Session
    participant NativeRT as native-runtime.ts
    participant NativeReq as native-request.ts
    participant LLMClient as route/client.ts
    participant Auth as route/auth.ts
    participant HTTP as transport/http.ts
    participant Endpoint as Provider HTTP Endpoint

    Session->>NativeRT: stream({ model, messages, tools })
    NativeRT->>NativeReq: LLMNative.request(input)
    NativeReq->>NativeReq: 选择 Provider Facade,绑定 apiKey/baseURL
    NativeReq-->>NativeRT: LLMRequest(含 model.route)
    NativeRT->>LLMClient: llmClient.stream(LLMRequest)
    LLMClient->>LLMClient: resolveRequestOptions + applyCachePolicy
    LLMClient->>LLMClient: route.body.from() 构造协议 Body + Schema 校验
    LLMClient->>HTTP: prepareTransport(body, request)
    HTTP->>Auth: Auth.toEffect(auth)(AuthInput)
    Auth-->>HTTP: 注入鉴权 Header
    HTTP->>Endpoint: POST(JSON body + Headers)
    Endpoint-->>HTTP: SSE / Converse-stream
    HTTP-->>Session: Stream<LLMEvent>

Loading

关键步骤

步骤	文件 & 符号	说明
1. Provider 解析	provider/provider.ts → Provider.list()	从配置/环境变量读取凭据,构造 SDK 实例
2. LLMRequest 构造	session/llm/native-request.ts → LLMNative.request()	AI SDK 消息/工具 → @opencode-ai/llm 规范对象
3. compile	route/client.ts → compile()	resolveOptions → cachePolicy → body.from() → Schema 校验
4. prepareTransport	route/transport/http.ts → jsonRequestParts()	渲染 URL、合并 headers、调用 Auth
5. Auth 注入	route/auth.ts → Auth.toEffect()	加载凭据 → 设置 Header
6. content-type	protocols/shared.ts:322 → jsonPost()	application/json
7. HTTP 发送	transport/http.ts → httpJson.frames()	POST,读取 SSE/Stream
8. 流解析	protocols/*.ts → protocol.stream.step	帧解码,提取 LLMEvent

---

二、请求 Header 明细

所有 Provider 均携带 content-type: application/json(protocols/shared.ts:322)

Anthropic

Base URL: (api.anthropic.com/redacted) | 协议: anthropic-messages` (SSE)

Header	取值来源	说明
anthropic-version	protocols/anthropic-messages.ts:852 固定	2023-06-01
x-api-key	providers/anthropic.ts:17 Auth.header("x-api-key")	API Key 鉴权

OpenAI

Base URL: (api.openai.com/redacted) | 协议: openai-responses/openai-chat`

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

Azure OpenAI

Base URL: https://<resource>.openai.azure.com/openai/v1

Header	取值来源	说明
api-key	providers/azure.ts:65 Auth.header("api-key")	Azure API Key(先移除 Authorization)

Google Gemini

Base URL: `(generativelanguage.googleapis.com/redacted)

Header	取值来源	说明
x-goog-api-key	providers/google.ts:17 Auth.header("x-goog-api-key")	Google API Key

Amazon Bedrock

Base URL: (bedrockruntime/redacted)(region).amazonaws.com/model/(modelId)/converse-stream

Header	取值来源	说明
Authorization	protocols/utils/bedrock-auth.ts AwsV4Signer.sign()	AWS SigV4 签名串
x-amz-date	AwsV4Signer 自动	请求时间戳
x-amz-security-token	AwsV4Signer 自动(STS)	临时凭据 Token

Bearer 模式(提供 apiKey 时)退化为 Authorization: Bearer (key)。

GitHub Copilot

Base URL: 调用方显式传入(无默认)

Header	取值来源	说明
Authorization	providers/github-copilot.ts:47	Bearer (copilot-token)

OpenRouter

Base URL: `(openrouter.ai/redacted)

Header	取值来源	说明
Authorization	providers/openrouter.ts:82	Bearer <OPENROUTER_API_KEY>
HTTP-Referer	provider.ts openrouter loader	`(opencode.ai/redacted)
X-Title	provider.ts openrouter loader	opencode

xAI(Grok)

Base URL: `(api.x.ai/redacted)

Header	取值来源	说明
Authorization	providers/xai.ts:25	Bearer <XAI_API_KEY>

Cloudflare AI Gateway / Workers AI

Header	取值来源	说明
Authorization	providers/cloudflare.ts	Bearer <provider-api-key>(下游鉴权)
cf-aig-authorization	providers/cloudflare.ts Auth.bearerHeader()	Bearer <CF_API_TOKEN>(AI Gateway 鉴权)
User-Agent	provider.ts:754/822	opencode/<ver> cloudflare-... (<os> <arch>)

GitLab AI Gateway

Header	取值来源	说明
Authorization	provider.ts:539	Bearer <oauth-token> 或 Bearer <PAT>
PRIVATE-TOKEN	provider.ts:669	GitLab PAT 鉴权模式
User-Agent	provider.ts:621	opencode/<ver> gitlab-ai-provider/<sdkver> (<os>)
anthropic-beta	provider.ts:623	context-1m-2025-08-07(GitLab 网关特性)

OpenAI 兼容(OpenRouter/TogetherAI/Nvidia/Vercel/Zenmux 等)

Header	取值来源	说明
Authorization	AuthOptions.bearer()	Bearer <provider-api-key>
HTTP-Referer	provider.ts loader options	`(opencode.ai/redacted)
X-Title	provider.ts loader options	opencode

---

三、鉴权机制

Provider	方式	凭据优先级	代码位置
Anthropic	x-api-key Header	apiKey → ANTHROPIC_API_KEY	providers/anthropic.ts:14–18
OpenAI	Bearer Authorization	apiKey → OPENAI_API_KEY	route/auth-options.ts
Azure	api-key Header	apiKey → AZURE_OPENAI_API_KEY	providers/azure.ts:59–77
Google Gemini	x-goog-api-key Header	apiKey → GOOGLE_GENERATIVE_AI_API_KEY	providers/google.ts:14–18
Amazon Bedrock	AWS SigV4 或 Bearer	credentials → env vars → AWS_BEARER_TOKEN_BEDROCK	protocols/utils/bedrock-auth.ts
GitHub Copilot	Bearer Authorization	显式 apiKey(无默认 env)	providers/github-copilot.ts:47
OpenRouter	Bearer Authorization	apiKey → OPENROUTER_API_KEY	providers/openrouter.ts:82
xAI	Bearer Authorization	apiKey → XAI_API_KEY	providers/xai.ts:25
Cloudflare	双层 Bearer	gatewayApiKey/CF_API_TOKEN + apiKey	providers/cloudflare.ts:48–67
GitLab	OAuth Bearer / PRIVATE-TOKEN	auth.access/auth.key/GITLAB_TOKEN	provider.ts:614–670
Google Vertex	ADC Bearer(google-auth-library)	服务账号/ADC 自动获取	provider.ts:536–541

Auth 组合子(route/auth.ts):

• Credential.orElse(fallback) — 凭据回退链
• .bearer() → Authorization: Bearer xxx
• .header(name) → 任意 Header
• Auth.andThen(that) — 串联多 Header
• Auth.remove(name) — 移除 Header(Azure 清除继承的 Authorization)
• Auth.custom(fn) — 完全自定义(Bedrock SigV4)

---

四、关键代码位置索引

文件	功能
packages/llm/src/route/client.ts	compile()、Route.make()、流式执行
packages/llm/src/route/auth.ts	Auth 组合子核心
packages/llm/src/route/auth-options.ts	AuthOptions.bearer()
packages/llm/src/route/transport/http.ts	jsonRequestParts()、httpJson()
packages/llm/src/protocols/shared.ts:322	jsonPost() → content-type
packages/llm/src/protocols/anthropic-messages.ts:852	anthropic-version 固定
packages/llm/src/protocols/utils/bedrock-auth.ts	SigV4 签名实现
packages/llm/src/providers/anthropic.ts:14–18	x-api-key 注入
packages/llm/src/providers/azure.ts:59–77	api-key + Authorization 移除
packages/llm/src/providers/cloudflare.ts:48–67	双层 Auth
packages/opencode/src/session/llm/native-request.ts	LLMNative.request()
packages/opencode/src/session/llm/native-runtime.ts	原生执行路径入口
packages/opencode/src/provider/provider.ts	各 Provider SDK 实例化、自定义 headers

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