企业官网建设流程全解析

OpenClaw OpenCode Go 接入指南：共享凭据、模型目录与插件运行时原理

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

OpenCode Go 是 OpenCode 平台内独立于 Zen 的另一套付费模型目录，在 OpenClaw 中以捆绑插件的形式提供运行时 provideropencode-go。本篇基于仓库文档 docs/providers/opencode-go.md 与插件实现 extensions/opencode-go/，讲清 Go 目录的开通方式、配置文件写法、模型发现机制，以及流式请求、思考策略与会话头等运行时细节的源码级原理，读完即可在 OpenClaw 中完成 Go 模型选型、路由与故障排查。

OpenCode Go 与 Zen 的关系

OpenCode 在 OpenClaw 中暴露两套托管目录，二者共用同一套 API Key 凭据基础设施，但授权相互独立：

关键事实（与 docs/providers/opencode.md 一致）：

• Go 是 OpenCode 内的独立付费订阅，Zen 密钥不会自动包含 Go 的授权，访问 Go 目录需要在 OpenCode 控制台单独开通订阅；
• 两个目录共用OPENCODE_API_KEY（别名OPENCODE_ZEN_API_KEY）凭据，同一个 Key 可以同时为两个运行时 provider 鉴权；
• OpenClaw 刻意保留两个不同的运行时 provider id（opencode与opencode-go），以保证上游按模型路由（per-model routing）在两套目录之间保持正确。

OpenCode Go 插件已捆绑在 OpenClaw 发布包中，无需单独安装插件，完成 onboarding 或配置即可使用。插件清单 extensions/opencode-go/openclaw.plugin.json 中enabledByDefault: true、activation.onStartup: false，即插件默认启用但不随启动激活，只有配置了 OpenCode 凭据或显式选择该 provider 时才参与运行。

快速开始

交互式 onboarding

# 1. 以 Go 目录选项运行 onboarding openclaw onboard --auth-choice opencode-go # 2. 将某个 Go 模型设为默认 openclaw config set agents.defaults.model.primary "opencode-go/kimi-k3" # 3. 验证模型可用 openclaw models list --provider opencode-go

--auth-choice opencode-go对应插件清单中providerAuthChoices声明的选项：choiceId为opencode-go，归属groupId: "opencode"（与 Zen 同组），支持appGuidedSecret交互式输入密钥。

onboarding 过程中，插件还会做一次实时默认模型发现：入口文件 extensions/opencode-go/index.ts 中resolveDefaultModel调用 resolveOpencodeGoStarterModel，向模型列表端点发起带 5 秒超时的发现请求，确认首选模型opencode-go/deepseek-v4-pro（定义于 extensions/opencode-go/onboard.ts 的OPENCODE_GO_DEFAULT_MODEL_REF）确实存在于上游在线目录后才采纳，否则回退处理。

非交互式（直接传 Key）

openclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY" openclaw models list --provider opencode-go

CLI 标志--opencode-go-api-key在插件清单的providerAuthChoices中声明（cliFlag: "--opencode-go-api-key"，optionKey: "opencodeGoApiKey"），因此该标志仅属于 Go 目录的 onboarding 入口，与 Zen 的选项分离。

配置示例

最小可用配置（json5）：

{ env: { vars: { OPENCODE_API_KEY: "YOUR_API_KEY_HERE" } }, agents: { defaults: { model: { primary: "opencode-go/kimi-k3" } } }, }

要点说明：

• 凭据写在env.vars下，插件的setup.providers声明识别的环境变量为OPENCODE_API_KEY与OPENCODE_ZEN_API_KEY，二者任一存在即可通过凭据解析；
• 默认模型 ref 必须使用opencode-go/前缀（见后文“运行时 ref 约定”），路由由 OpenClaw 按前缀自动完成，无需额外 provider 配置；
• 若已为 Zen 配置过OPENCODE_API_KEY，Go 侧无需重复填写密钥，只需确认账号已开通 Go 订阅并指定opencode-go/...模型。

模型目录：种子目录 + 实时发现 + 上游元数据合并

这是 OpenCode Go 目录机制中最值得展开的部分。文档 docs/providers/opencode-go.md 指出：运行openclaw models list --provider opencode-go可获得当前模型列表；OpenClaw 会把 Go 广告的模型 ID 与https://models.opencode.ai/api.json的权威元数据合并，因此使用受支持传输协议、且走可信 OpenCode 端点的新上游模型，无需 OpenClaw 发版即可出现。上游目录的下载与缓存只在配置了 OpenCode Zen 或 Go（或使用 OpenCode 凭据显式选择）时发生，启动阶段或使用无关 provider 时绝不抓取。

从源码看，这条链路由 extensions/opencode-go/provider-catalog.ts 实现，端点与超时/缓存常量集中在文件头部：

const OPENCODE_GO_OPENAI_BASE_URL = "https://opencode.ai/zen/go/v1"; const OPENCODE_GO_ANTHROPIC_BASE_URL = "https://opencode.ai/zen/go"; const OPENCODE_GO_MODELS_ENDPOINT = "https://opencode.ai/zen/go/v1/models"; const OPENCODE_UPSTREAM_CATALOG_ENDPOINT = "https://models.opencode.ai/api.json"; const OPENCODE_GO_MODELS_TIMEOUT_MS = 5_000; const OPENCODE_GO_MODELS_CACHE_TTL_MS = 60_000;

目录构建分三层：

1. 捆绑种子目录（离线兜底）：从插件清单modelCatalog读取内置模型行，经normalizeModelCompat规范化后构建OPENCODE_GO_SEED_CATALOG（provider-catalog.ts#L33-L56）。即使上游元数据不可用，种子目录依然可用——buildOpencodeGoLiveProviderConfig对上游抓取异常采取静默降级（provider-catalog.ts#L119-L131）。
2. 实时模型 ID 发现：buildOpencodeGoLiveProviderConfig以discoveryMode: "strict"调用/zen/go/v1/models端点（5 秒超时、60 秒缓存 TTL），把上游返回的模型 ID 与本地目录快照投影合并（provider-catalog.ts#L132-L149）。
3. 上游权威元数据：getCachedUpstreamProviderCatalog拉取models.opencode.ai/api.json，经projectUpstreamProviderCatalogSnapshot投射为 provider 快照并写入模块级缓存opencodeGoCatalog；其中对 anthropic-messages 传输的qwen*模型会额外打上compat.thinkingFormat: "qwen"（provider-catalog.ts#L64-L76）。

文档中提到的两条目录语义在代码中同样可见：

• deprecated 行从活跃发现中排除，preview 行保持隐藏：种子目录保留status字段（如deprecated/preview），listStaticOpencodeGoModels会过滤已被实时目录标记状态的行（provider-catalog.ts#L58-L62）；
• 显式 ref 始终可解析：resolveOpencodeGoModel只从捆绑种子目录按模型 id 精确查找（provider-catalog.ts#L156-L159），保证配置里写死的种子模型 id 不依赖上游在线状态。

捆绑种子模型参考（来自插件清单）

以下为 extensions/opencode-go/openclaw.plugin.json 中当前内置的模型行，可作为选型参考；运行时以openclaw models list --provider opencode-go为准，示例 ref 如opencode-go/deepseek-v4-flash、opencode-go/kimi-k3、opencode-go/qwen3.8-max不应被当作完整清单。

清单同时记录了各模型的cost计费参数（如deepseek-v4-flash为 input 0.14 / output 0.28 / cacheRead 0.0028，kimi-k3为 input 3 / output 15 / cacheRead 0.3）与compat能力位（流式 usage、max_tokens字段、developer role、strict mode、code mode 等），这些字段由 OpenClaw 的模型运行时用于计费展示与请求格式适配。

传输归一化与双 baseUrl

Go 目录存在两个传输端点：OpenAI 兼容 completions 走https://opencode.ai/zen/go/v1，Anthropic messages 走https://opencode.ai/zen/go。插件通过normalizeOpencodeGoBaseUrl（provider-catalog.ts#L195-L218）在配置、已解析模型、传输三处钩子（normalizeConfig/normalizeResolvedModel/normalizeTransport，见 index.ts#L51-L83）统一做归一化，并把旧端点迁移过来：

• https://opencode.ai/go→ Anthropic baseUrl；
• https://opencode.ai/go/v1→ 按api类型分流到两个规范端点；
• 其余 baseUrl 一律不识别，避免误路由。

插件清单的providerEndpoints也声明了这两个端点属于opencode-go-native端点类，供运行时请求策略识别。

会话头x-opencode-session

docs/providers/opencode.md 说明 OpenClaw 对发往 OpenCode 的请求会携带稳定的x-opencode-session会话头（跨 Anthropic、Gemini、OpenAI Chat Completions 与 OpenAI Responses 传输），该头在关闭 prompt caching 时依然生效。Go 插件侧的实现见 index.ts#L118-L131 的resolveTransportTurnState：

• 仅当模型 baseUrl 属于规范 Go 端点时生效；
• 若调用方已显式传入x-opencode-session（任意大小写），则原样保留不覆盖；
• 否则用sessionId（缺省时退回turnId）生成会话头值。

底层 SDK 流式调用方应在 stream options 中提供sessionId以维持会话连续性。

思考（Reasoning）策略

Go 目录对“思考”能力的暴露按模型精细区分，策略集中在 extensions/opencode-go/provider-policy-api.ts：

与策略配套的请求改写逻辑在 extensions/opencode-go/stream.ts 的包装器组合中：

• Kimi 无推理模型（k2.5/k2.6/k2.7-code）的请求载荷会被清洗掉 reasoning 字段（stripOpencodeGoKimiReasoningPayload），normalizeOpencodeGoResolvedModel（provider-catalog.ts#L168-L189）同时把这些模型的运行时模型标记为reasoning: false；
• kimi-k3使用 thinking-off 包装（只允许 off/max 两档）；
• 固定推理的 Anthropic 模型会从载荷中删除thinking与output_config字段；
• DeepSeek V4 Pro / Flash 使用专用 thinking 包装器，Flash 的 effort 映射为 low→low、max→max、其余→high。

流式稳定性：provider 自有的 SSE 终止

extensions/opencode-go/stream-termination.ts 为 Go 目录实现了外层 stalled-stream 包装器：

• 空闲超时默认 120 秒（OPENCODE_GO_STREAM_IDLE_TIMEOUT_MS_DEFAULT），与运行时共享的DEFAULT_LLM_IDLE_TIMEOUT_MS对齐，交互运行行为无变化；
• 首事件超时默认 300 秒（OPENCODE_GO_STREAM_FIRST_EVENT_TIMEOUT_MS_DEFAULT）；
• 设计动机（源码注释）：cron 触发时运行时禁用空闲看门狗，原先要等到约 622 秒的 stuck-session 恢复才终止，现在 Go 请求会在 provider 自有边界直接中止底层 OpenAI SDK 请求，显著提前故障暴露；
• 仅匹配text_delta、thinking_delta、toolcall_*等实质进展事件才认为流仍活跃。

另有createOpencodeGoAttributionWrapper（stream.ts#L19-L46）专门处理 anthropic-messages 传输的请求归因头注入，确保每个请求只解析一次归因（OpenAI 传输已由中心策略消费）。

图像理解能力

插件同时注册了一个媒体理解 provider：extensions/opencode-go/media-understanding-provider.ts 声明capabilities: ["image"]，图像描述默认模型为kimi-k2.6（与清单mediaUnderstandingProviderMetadata一致），在 index.ts#L137-L139 的register钩子中通过api.registerMediaUnderstandingProvider挂入运行时。

隐私与授权边界

• 保留与训练策略因模型而异，且提供方策略会独立于 OpenClaw 变化。使用某个 Go 模型前，请查阅 OpenCode 官网上 OpenCode Go 当前的隐私对照表，不要假设策略随 OpenClaw 版本同步更新；
• 模型列表端点是通用目录，不是账号授权检查。/zen/go/v1/models返回成功不代表你的账号有权推理——实际调用仍需有效的 Go 订阅，促销模型同样如此。源码注释也明确了这一点：“Public upstream metadata does not establish another account's Go entitlement”（provider-catalog.ts#L156-L159）。

高级配置要点

• 路由行为：任何opencode-go/...模型 ref 由 OpenClaw 自动路由，无需额外 provider 配置；
• 运行时 ref 约定：opencode/...专指 Zen，opencode-go/...专指 Go。这一显式前缀约定是两套目录共享OPENCODE_API_KEY时上游按模型路由保持正确的前提，混用前缀会导致解析失败；
• 共享凭据：同一个OPENCODE_API_KEY可为两个运行时 provider 鉴权，onboarding 可能同时保存opencode:default与opencode-go:default两个 profile（见 index.ts#L32-L36 的manifestAuth.profileIds）。Go 访问仍要求在 OpenCode 控制台单独开通付费订阅。

相关文档

• OpenCode 父级文档：共享 onboarding 概览、Zen + Go 完整目录参考与会话头说明；
• 模型选择概念：provider 选择、模型 ref 与 failover 行为；
• 插件源码入口：extensions/opencode-go/index.ts、离线发现 extensions/opencode-go/provider-discovery.ts（在无凭据时为openclaw models list提供静态目录）。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw