Skip to content

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

Open
Open
[opencode 请求流程分析] OpenCode 请求流程与请求 Header 分析(2026-07-22)#15
Labels
analysisautomated

Description

@github-actions
github-actions
bot
opened on Jul 22, 2026

本次变更提示

近期同步提交中与请求流程相关:

  • 3033afb fix(provider): normalize Mistral family tool call IDs — 工具调用 ID 规范化
  • 5a8ee27 fix(provider): update muse-spark reasoning default and system prompt — provider 选项调整

1. 请求流程(时序)

opencode 存在两条并行路径:

路径 适用范围
AI SDK 主路径 大多数 provider(通过 Vercel AI SDK)
Native LLM 路径 OpenAI / Anthropic / opencode 自有

Native LLM 路径时序

sequenceDiagram
    participant S as Session/Prompt
    participant P as LLMRequestPrep.prepare<br/>(session/llm/request.ts)
    participant N as LLMNative.request<br/>(native-request.ts)
    participant C as LLMClient.compile<br/>(llm/route/client.ts)
    participant A as Auth.apply<br/>(route/auth.ts)
    participant T as HttpTransport.jsonRequestParts<br/>(transport/http.ts)
    participant E as RequestExecutor<br/>(executor.ts)

    S->>P: prepare(input)
    Note over P: 1.合并system/params<br/>2.插件触发chat.headers<br/>3.注入User-Agent/session头
    P-->>S: Prepared{headers,params,...}
    S->>N: LLMNative.request(model,messages,headers)
    N-->>S: LLMRequest(含model/route对象)
    S->>C: compile(LLMRequest)
    Note over C: resolveRequestOptions<br/>合并 RouteDefaults/ModelDefaults
    C->>C: route.body.from(request) → provider body
    C->>T: route.prepareTransport(body, request)
    T->>A: Auth.toEffect(auth)(authInput)
    Note over A: apiKey选项→env变量Config<br/>→设置鉴权Header
    A-->>T: Headers(含鉴权)
    T->>T: set content-type:application/json
    T-->>C: HttpPrepared{request,framing}
    C->>E: execute(HttpClientRequest)
    Note over E: 重试逻辑max 2次<br/>处理429/503/504/529
    E-->>S: SSE Stream → LLMEvent
Loading

关键步骤

步骤 文件 & 符号
1. 请求参数/Header 构造 session/llm/request.ts → LLMRequestPrep.prepare
2. 消息格式转换 session/llm/native-request.ts → LLMNative.request
3. 路由选择 & body 构造 llm/route/client.ts → compile()
4. 鉴权 Header 注入 llm/route/auth.ts → Auth.toEffect
5. HTTP 请求构造 llm/route/transport/http.ts → jsonRequestParts
6. HTTP 发送 & 重试 llm/route/executor.ts → retryStatusFailures
7. SSE 流解析 llm/route/client.ts → streamPrepared

2. 请求 Header 明细

通用 Header(所有 provider)

Header 取值 来源
content-type application/json protocols/shared.ts:322 → jsonPost()
User-Agent opencode/<version> session/llm/request.ts → USER_AGENT
x-session-affinity sessionID session/llm/request.ts headers 块
X-Session-Id sessionID 同上

Anthropic

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

Header 取值来源 说明
x-api-key apiKey选项 → ANTHROPIC_API_KEY providers/anthropic.ts:13-17
anthropic-version "2023-06-01"(硬编码) protocols/anthropic-messages.ts:852

OpenAI

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

Header 取值来源 说明
authorization Bearer <key>,apiKey→OPENAI_API_KEY route/auth-options.ts → AuthOptions.bearer

OpenAI 兼容(cerebras/deepseek/groq 等)

端点:用户配置 baseURL + /chat/completions

Header 取值来源 说明
authorization Bearer <key> providers/openai-compatible.ts → AuthOptions.bearer(input, [])

Amazon Bedrock

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

Header 取值来源 说明
authorization AWS SigV4 签名 protocols/utils/bedrock-auth.ts → AwsV4Signer
x-amz-date SigV4 时间戳 同上(aws4fetch 自动注入)
x-amz-security-token STS sessionToken 临时凭证时自动注入
content-type application/json SigV4 签名前注入(bedrock-auth.ts:32)

Google(Gemini)

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

Header 取值来源 说明
x-goog-api-key apiKey→GOOGLE_GENERATIVE_AI_API_KEY providers/google.ts:14-18

Azure OpenAI

端点:https://(resource).openai.azure.com/openai/v1/responses?api-version=v1

Header 取值来源 说明
api-key apiKey→AZURE_OPENAI_API_KEY providers/azure.ts:65-71;先移除 authorization

GitHub Copilot

端点:调用方必须显式传入 baseURL

Header 取值来源 说明
authorization Bearer (key) providers/github-copilot.ts → AuthOptions.bearer(options, [])

路由选择:GPT-5+ 走 Responses API,其余走 Chat API(shouldUseResponsesApi)

OpenRouter

端点:`(openrouter.ai/redacted)

Header 取值来源 说明
authorization Bearer <key> → OPENROUTER_API_KEY providers/openrouter.ts

xAI(Grok)

端点:`(api.x.ai/redacted)

Header 取值来源 说明
authorization Bearer (key) → XAI_API_KEY providers/xai.ts

opencode 自有路由专用

Header 取值来源
x-opencode-project project ID
x-opencode-session sessionID
x-opencode-request user.id
x-opencode-client flags.client

3. 鉴权机制

凭据解析优先级

显式 auth 对象 > apiKey 选项 > 环境变量(Config)

核心:packages/llm/src/route/auth-options.ts → AuthOptions.bearer()

Provider 鉴权方式 环境变量 Header
Anthropic API Key ANTHROPIC_API_KEY x-api-key
OpenAI Bearer OPENAI_API_KEY authorization
OpenAI Compatible Bearer 无(需显式) authorization
Amazon Bedrock AWS SigV4 需传 credentials 对象 SigV4 签名头
Google API Key GOOGLE_GENERATIVE_AI_API_KEY x-goog-api-key
Azure OpenAI API Key AZURE_OPENAI_API_KEY api-key
GitHub Copilot Bearer 无(需显式) authorization
OpenRouter Bearer OPENROUTER_API_KEY authorization
xAI Bearer XAI_API_KEY authorization

Bedrock SigV4(protocols/utils/bedrock-auth.ts):使用 aws4fetch 库对 POST body+URL+headers 整体签名,支持临时凭证(sessionToken)。若配置了 apiKey 则退化为 Bearer Token。

OAuth(OpenAI):native-runtime.ts 中通过自定义 fetch 函数注入 OAuth access token。

4. 关键代码位置索引

文件 符号 说明
packages/llm/src/route/client.ts compile, LLMClient.layer 请求编译主入口
packages/llm/src/route/executor.ts RequestExecutor, retryStatusFailures HTTP 执行与重试
packages/llm/src/route/auth.ts Auth, Credential, bearer, header 鉴权抽象层
packages/llm/src/route/auth-options.ts AuthOptions.bearer 通用 bearer 凭据解析
packages/llm/src/route/transport/http.ts httpJson, jsonRequestParts HTTP+SSE 传输层
packages/llm/src/protocols/anthropic-messages.ts:845 route Anthropic 路由(含 anthropic-version 头)
packages/llm/src/protocols/openai-chat.ts:497 route OpenAI Chat Completions 路由
packages/llm/src/protocols/openai-responses.ts:984 route, webSocketRoute OpenAI Responses API 路由
packages/llm/src/protocols/bedrock-converse.ts:658 route, sigV4Auth Bedrock Converse 路由(SigV4)
packages/llm/src/protocols/gemini.ts:500 route Google Gemini 路由
packages/llm/src/protocols/utils/bedrock-auth.ts sigV4, signRequest AWS SigV4 签名实现
packages/llm/src/protocols/shared.ts:320 jsonPost 设置 content-type: application/json
packages/llm/src/providers/azure.ts:65 auth Azure api-key header 鉴权
packages/llm/src/providers/amazon-bedrock.ts configuredRoute Bedrock SigV4 vs Bearer 选择
packages/opencode/src/session/llm/request.ts LLMRequestPrep.prepare 会话层请求构造、header 注入
packages/opencode/src/session/llm/native-request.ts LLMNative.request, model AI SDK → LLMRequest 转换
packages/opencode/src/session/llm/native-runtime.ts NativeRuntime.stream Native 路径入口,OAuth fetch 覆盖
packages/opencode/src/provider/auth.ts ProviderAuth.Service OAuth 鉴权流程(授权/回调/存储)

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    analysisautomated

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions