OpenClaw Zero Token 的 Web 模型架构:Cookie 认证如何驱动 13 个免 API Key 大模型

原创2026-10-15 16:44:431,951 阅读
文章标签:人工智能大模型AI 应用后端LLM 网关即时通讯AI Agent插件系统本地部署MCP Clients

OpenClaw Zero Token 的 Web 模型架构:Cookie 认证如何驱动 13 个免 API Key 大模型

本文基于仓库内的 web-models-architecture 文档 与 src/zero-token/、src/agents/ 下的真实实现展开,讲解 OpenClaw "Zero Token"(Web 模型)架构的设计原则、授权流程、模型目录注入链路与消息发送的完整调用链。读完本文后,你能理解为什么 Web 模型刻意绕开 OpenClaw 的插件体系,并能定位到 StreamFn 工厂映射、凭证存储、白名单门控等每一环的具体源码位置,从而完成 Web 模型的接入、排错与扩展。

什么是 Zero Token(Web 模型)

Web 模型(又称 "Zero Token" 模型)指通过浏览器 Cookie/Session 认证而非 API Key 调用的大模型服务,代表包括 DeepSeek Web、Claude Web、ChatGPT Web 等。其核心特征是"零 Token 成本"——复用用户已登录的网页账号会话,向官方 Web 站点发起与浏览器一致的 HTTP/SSE 请求,从而绕过官方 API 计费。

当前仓库中,Zero Token 相关实现集中在 src/zero-token/README.md 描述的三个目录:

  • providers/ — 各站点的客户端与登录助手(*-web-client*.ts、*-web-auth.ts),负责打开浏览器、捕获 Cookie;
  • streams/ — 各模型的 StreamFn 工厂实现,以及 model.api → 工厂 的映射表 web-stream-factories.ts;
  • extensions/askonce/ — 附带打包的 AskOnce 插件(多模型"问一次" CLI,工作区包 @openclaw/askonce)。

四条核心设计原则

原文档给出的四条设计原则,均可在源码中找到对应物证:

  1. 非插件架构:Web 模型不是 OpenClaw Plugin,不走 ProviderPlugin.createStreamFn() 插件体系。在 provider-stream.ts 的 fallback 注释中明确写道:"Web models are not bundled as plugins, so resolveProviderStreamFn returns undefined";
  2. 独立 Stream 工厂:每个 web provider 拥有独立的 createXXXWebStreamFn 工厂函数。web-stream-factories.ts 中维护了 13 个 model.api → 工厂 的映射(deepseek-web、claude-web、chatgpt-web、doubao-web、qwen-web、qwen-cn-web、kimi-web、gemini-web、grok-web、glm-web、glm-intl-web、perplexity-web、xiaomimo-web),并用 satisfies Record<string, (cookie: string) => StreamFn> 做类型约束;
  3. 凭证独立存储:Cookie/Session 存储在 auth-profiles.json,不经过 OpenClaw upstream config。凭证读写经由 auth-profiles.ts 导出的一组 store/profile 函数完成(ensureAuthProfileStore、saveAuthProfileStore、listProfilesForProvider 等);
  4. 白名单门控:用户可见性由 agents.defaults.models 白名单控制,目录注入逻辑实现在 model-catalog.ts 的 mergeWhitelistedWebModels() 中。

授权流程:从 onboard-web-auth 到 auth-profiles.json

13 个 Web 模型的登录函数注册

onboard-web-auth.ts 中的 WEB_MODEL_PROVIDERS 列表把每个 provider 与其 loginFn 绑定,共 13 项:

const WEB_MODEL_PROVIDERS: WebModelProvider[] = [
  { id: "claude-web", name: "Claude Web", loginFn: loginClaudeWeb },
  { id: "chatgpt-web", name: "ChatGPT Web", loginFn: loginChatGPTWeb },
  { id: "deepseek-web", name: "DeepSeek Web", loginFn: loginDeepseekWeb },
  { id: "doubao-web", name: "Doubao Web", loginFn: loginDoubaoWeb },
  { id: "gemini-web", name: "Gemini Web", loginFn: loginGeminiWeb },
  { id: "glm-web", name: "GLM Web (国内)", loginFn: loginZWeb },
  { id: "glm-intl-web", name: "GLM Web (国际)", loginFn: loginGlmIntlWeb },
  { id: "grok-web", name: "Grok Web", loginFn: loginGrokWeb },
  { id: "kimi-web", name: "Kimi Web", loginFn: loginKimiWeb },
  { id: "perplexity-web", name: "Perplexity Web", loginFn: loginPerplexityWeb },
  { id: "qwen-web", name: "Qwen Web (阿里国内)", loginFn: loginQwenWeb },
  { id: "qwen-cn-web", name: "Qwen Web (阿里国际)", loginFn: loginQwenCNWeb },
  { id: "xiaomimo-web", name: "Xiaomi Mimo Web", loginFn: loginXiaomiMimoWeb },
];

每个 provider 对应的可选模型 ID 也在同文件(providerModelIds 映射,第 277-291 行)中登记,例如 deepseek-web → ["deepseek-chat", "deepseek-reasoner"]、claude-web → ["claude-sonnet-4-6", "claude-opus-4-6", "claude-haiku-4-6"]。

授权向导的实际执行步骤

runOnboardWebAuth()(onboard-web-auth.ts 第 207-329 行)的执行序列:

  1. 读取 auth-profiles store,筛出已授权模型(profile id 以 -web 结尾或含 -web:),列出并打上 "✓ 已授权" 标记;
  2. 交互式选择:支持编号多选(逗号分隔)、a 授权全部、0 退出;
  3. 对每个选中的 provider 调用 provider.loginFn({ onProgress, openUrl }),成功后执行两件事:
    • 保存凭证:saveWebModelCredentials(providerId, result) 将凭证以 type: "token" 写入 profile id 为 {providerId}:default 的条目,token 字段是凭证对象的 JSON 序列化(第 34-46 行);
    • 更新白名单:addModelToWhitelist(providerId, modelIds) 把每个 providerId/modelId 以 { alias } 形式写入 openclaw.json 的 agents.defaults.models(第 49-111 行);
  4. 最后调用 syncModelsProvidersToConfig(),把 agent 目录 models.json 中的 providers 同步进 openclaw.json,且显式过滤掉所有 web provider(第 136-141 行),避免它们进入 upstream 配置触发 schema 校验错误。

这与原文档中描述的授权流程图完全一致:

用户执行 onboard-web-auth 命令
  ├─► Wizard 展示 13 个可选 Web 模型
  │     └─► WEB_MODEL_PROVIDERS 列表定义各模型的 loginFn
  ├─► 调用 provider.loginFn()
  │     └─► 各 provider 的 login 函数 (loginDeepseekWeb 等)
  │           ├─► 打开浏览器登录页 (Puppeteer/手动)
  │           └─► 提取 cookies / session token
  ├─► 保存凭证到 auth-profiles.json
  │     路径: {OPENCLAW_STATE_DIR}/auth-profiles.json
  │     格式: { profiles: { "deepseek-web:default": { type: "token", token: "..." } } }
  └─► 添加模型到白名单
        openclaw.json: agents.defaults.models: { "deepseek-web/deepseek-chat": { alias: "DeepSeek V3" } }

以 loginDeepseekWeb 为例看凭证捕获实现

以 deepseek-web-auth.ts 的 loginDeepseekWebAttachOnly() 为例,可以看清 login 函数"提取 cookies / session token"的具体机制:

  • 读取 browser 配置,解析出浏览器 profile 与其 CDP 调试端口,通过 chromium.connectOverCDP() 附加到已运行的 Chrome(attach 模式,而非启动新浏览器);
  • 在已有页面中查找 deepseek.com / chat.deepseek.com 标签页,若无则新开一页;
  • 通过 context.cookies() 读取 https://chat.deepseek.com 与 https://deepseek.com 两个域下的 Cookie,拼成 name=value; ... 字符串;
  • 检查会话有效性标志:d_id=、ds_session_id=、HWSID= / uuid= 等 Cookie,必要时再扫描页面 localStorage 寻找 bearer token。

最终返回 { cookie, bearer, userAgent } 结构,由向导序列化为 JSON 存入 auth-profiles。其余 12 个 provider 的 *-web-auth.ts 实现遵循同样的"浏览器附加 + Cookie 捕获"模式(各自捕获对应站点的会话标识)。

模型目录加载链路:白名单如何把 Web 模型注入 UI

原文档给出的四段式加载链路,对应 model-catalog.ts 中 loadModelCatalog()(第 171-305 行)的真实执行顺序:

loadModelCatalog()
  ├─1─► pi-sdk ModelRegistry        读取 agentDir/models.json,仅含 upstream 模型(不含 web 模型)
  ├─2─► mergeConfiguredOptInProviderModels()   读取 models.providers
  │          NON_PI_NATIVE_MODEL_PROVIDERS = {deepseek, kilocode},不读白名单
  ├─3─► mergeWhitelistedWebModels()  ← ZERO TOKEN 新增,读 agents.defaults.models 白名单
  └─4─► augmentModelCatalogWithProviderPlugins()  读取插件提供的模型(web 模型不在此)

源码中每一步都有对应的 logStage 埋点(registry-read、configured-models-merged、whitelisted-web-models-merged、plugin-models-merged、complete,开启 OPENCLAW_DEBUG_INGRESS_TIMING=1 时输出耗时),原文档"验证结果"一节中的 781 → 779 → 796 → 798 条目数变化即来自这些埋点。

isWebProvider 与 KNOWN_WEB_PROVIDER_IDS

isWebProvider()(model-catalog.ts 第 39-64 行)采用"静态名单 + 后缀启发式"双重判定:provider id 命中 KNOWN_WEB_PROVIDER_IDS(13 个 *-web id 的 Set),或 id 以 -web 结尾且不含空格。这为将来新增 web provider 保留了扩展余地——只要 id 以 -web 结尾即会被识别,但目录元数据仍需在静态表中登记。

mergeWhitelistedWebModels:白名单即目录

mergeWhitelistedWebModels()(第 383-424 行)的逻辑:

  1. 读取 config.agents.defaults.models 白名单,跳过不含 / 的键;
  2. 对每个 provider/modelId,先经 isWebProvider(providerId) 过滤,非 web provider 直接跳过;
  3. 以 provider::modelId(小写)为去重键,目录中已存在的条目不重复注入;
  4. 到静态表 KNOWN_WEB_MODEL_ENTRIES(第 326-375 行)中查找 provider + modelId 的元数据(显示名、contextWindow、是否 reasoning 等),查不到则跳过——静态表是白名单条目"能出现在目录里"的必要条件;
  5. 找到后合成条目推入目录,显示名优先取白名单中用户配置的 alias,否则回落到静态表名称。

静态表登记的代表性条目包括:deepseek-web/deepseek-chat(DeepSeek V3,64k 上下文)、deepseek-web/deepseek-reasoner(DeepSeek R1,reasoning: true)、claude-web/claude-sonnet-4-6(200k)、glm-intl-web/glm-4-think(reasoning)等,与 onboard 向导的 modelAliases 表(onboard-web-auth.ts 第 58-100 行)互为呼应。

消息发送核心链路:StreamFn 的 fallback 机制

这是 Zero Token 架构中最关键的机制——plugin 系统对 web 模型不可见,因此必须有一条 fallback 通道。完整链路如下:

用户选择 deepseek-web/deepseek-chat,发消息
  ▼
resolveConfiguredModelRef(cfg, "deepseek-web/deepseek-chat")
  ├─► 查 agents.defaults.models 白名单 ✓ (alias: "DeepSeek V3")
  └─► 查 models.providers → 找到 baseUrl=https://chat.deepseek.com
  → 返回 ModelRef { provider, modelId, baseUrl }
  ▼
attempt.ts: resolveEmbeddedAgentStreamFn()
  └─► registerProviderStreamForModel({ model, cfg, agentDir })
        ├─► resolveProviderStreamFn(provider) → 插件系统 → undefined (web 模型非插件)
        └─► fallback: getWebStreamFactory(model.api) → 工厂 → StreamFn
  ▼
StreamFn(model, context) 被调用
  ├─► client.init() — 用 cookie 初始化 HTTP client
  ├─► client.createChatSession() — 创建服务端会话 → sessionId
  ├─► client.sendMessage(sessionId, prompt) — 返回 SSE 流
  └─► SSE → pi-ai AssistantMessageEvent(thinking / text / tool_result)
  ▼
attempt.ts 处理事件 → 转发给前端 WebSocket → Web UI 渲染

registerProviderStreamForModel:先插件、后 Web 工厂

provider-stream.ts 的 registerProviderStreamForModel()(全文 78 行)实现了"两级解析":

  1. 第一级:调用插件系统的 resolveProviderStreamFn({ provider, config, ... });web 模型不是插件,此处返回 undefined;
  2. 第二级(fallback):getWebStreamFactory(params.model.api) 按 model.api 查工厂映射表;查不到同样返回 undefined;
  3. 凭证加载:ensureAuthProfileStore(agentDir) 打开凭证库,listProfilesForProvider(store, provider) 取该 provider 的 profile 列表,为空时打印 no auth profile found for provider=... 并跳过;
  4. 凭证解包:按 profile 类型分支提取 credential 字符串——type: "token" 取 profile.token;type: "api_key" 取 profile.key;type: "oauth" 将整个 profile JSON.stringify 后传入;其他类型打警告并放弃(第 57-70 行);
  5. 最终 webFactory(credential) 生成 StreamFn,经 ensureCustomApiRegistered() 注册后返回,并输出 using web stream factory for provider=... model=... api=... 日志便于排错。

getWebStreamFactory() 还有一个细节:返回的工厂会在内部用 wrapWithToolCalling() 包一层(web-stream-factories.ts 第 36-42 行),为所有 web 流统一叠加仓库自研的文本协议工具调用中间件(src/zero-token/tool-calling/ 下的 web-stream-middleware.ts、web-tool-parser.ts 等),使 web 模型也能参与 OpenClaw 的工具调用循环。

稳定 import 路径:桥接模块

agents/web-stream-factories.ts 仅 16 行,作用是桥接:attempt.ts / compact.ts 从该稳定路径 re-export getWebStreamFactory / listWebStreamApiIds,与 src/zero-token/ 目录结构变化解耦。src/zero-token/streams/web-stream-factories.ts 是 source of truth,桥接层不承载任何逻辑——这正是原文档"本地工程适配情况"中"web-stream-factories.ts — 桥接模块已存在"的含义。

DeepSeek Web StreamFn 的内部机制

以 deepseek-web-stream.ts(743 行)为样本,可以看到 StreamFn 工厂的典型实现:

  • 凭证多态解析:createDeepseekWebStreamFn(cookieOrJson) 先尝试 JSON.parse 入参——解析出对象则作为 DeepSeekWebClientOptions,解析出字符串则当作纯 cookie,解析失败也按 cookie 处理(第 34-46 行)。这与 onboard 侧"凭证对象 JSON 序列化后存 token 字段"的写法闭环;
  • session 复用:模块级 sessionMap: Map<string, string> 按 context.sessionId 缓存 chat_session_id,首次请求才 client.createChatSession(),后续轮次复用同一服务端会话,避免为每条消息创建新会话(第 21-23、56-64 行)——对应原文档注意事项第 4 条;
  • 历史聚合:首轮(无 parentId)把 system prompt、工具清单、全量历史(含 toolResult、thinking、toolCall 内容块)聚合成单条文本 prompt 发送;
  • SSE → pi-ai 事件转换:以有状态标签解析器把服务端流切分为 text / thinking / tool_call 三种模式,分别推送 text_start/text_delta、thinking_start/thinking_delta、toolcall_start/toolcall_delta 等 pi-ai AssistantMessageEvent,并在出现工具调用时把 stopReason 置为 "toolUse"(第 200-320 行),使下游 attempt.ts 能像处理原生 API 模型一样处理 web 模型的流式输出。

工厂注册完备性的测试保障

web-stream-factories.test.ts 用三条测试锁定了注册表行为:listWebStreamApiIds() 必须恰好返回 13 个 id;每个 id 都能取到工厂函数;非 web 的 api(如 "openai")返回 undefined。这保证了目录侧 KNOWN_WEB_PROVIDER_IDS、工厂侧 WEB_STREAM_FACTORIES、onboard 侧 WEB_MODEL_PROVIDERS 三处名单的一致性有测试背书。

关键文件清单

文件 职责
src/zero-token/providers/*-web-auth.ts 各模型的 login 函数(浏览器附加、Cookie/Session 捕获)
src/agents/auth-profiles.ts 凭证读写门面(auth-profiles.json,store/profile/cooldown 等子模块聚合导出)
src/zero-token/streams/*-web-stream.ts 各模型的 StreamFn 实现(SSE → pi-ai 事件转换、session 复用)
src/zero-token/streams/web-stream-factories.ts model.api → StreamFn 工厂的映射表(source of truth)
src/agents/web-stream-factories.ts 桥接模块(稳定 import 路径,供 attempt.ts / compact.ts)
src/agents/provider-stream.ts 核心:registerProviderStreamForModel = 插件解析 + web fallback
src/agents/model-catalog.ts isWebProvider()、KNOWN_WEB_MODEL_ENTRIES、mergeWhitelistedWebModels() 白名单注入
src/commands/onboard-web-auth.ts CLI 授权向导(13 模型 loginFn 注册、凭证保存、白名单写入)

补充两个仓库内的扩展入口:docs/zero-token/index.md 是 Zero Token 产品文档目录(含浏览器模式说明 web-models-browser-modes.md、模型支持 web-models-support.md、工具调用 web-tool-calling.md);src/zero-token/bridge/web-providers.ts 则提供 web 模型的 baseUrl / 默认 model id 导出与 build*WebProvider 实现,供 models-config.providers.ts 的隐式 provider 解析使用。

本地工程适配情况与验证结果

已修复 ✅

  1. provider-stream.ts — 添加了 fallback 分支,从 getWebStreamFactory() + auth-profiles 获取 web 模型 StreamFn(见上文第 35-77 行实现);
  2. web-stream-factories.ts — 桥接模块已存在,13 个 provider 的工厂函数全部注册;
  3. model-catalog.ts — 添加了 KNOWN_WEB_PROVIDER_IDS、isWebProvider()、mergeWhitelistedWebModels() 及静态元数据表 KNOWN_WEB_MODEL_ENTRIES;
  4. 配置 — 从 models.providers 移除了无效 api 类型的 web provider 条目(避免 schema 报错),onboard 流程中的 syncModelsProvidersToConfig() 也会主动过滤 web provider 以防其回流。

依赖前提 ✅

  1. auth-profiles.json — 各 web provider 的凭证(type: "token",token 为凭证对象 JSON);
  2. openclaw.json — agents.defaults.models 白名单包含 web 模型(如 {"deepseek-web/deepseek-chat": {"alias": "DeepSeek V3"}});
  3. web-stream-factories.ts — 所有 13 个 provider 的工厂函数已注册(有测试锁定)。

验证结果

stage=registry-read entries=781          ← pi-sdk 原生模型
stage=configured-models-merged entries=779  ← 过滤 deepseek (NON_PI_NATIVE)
stage=whitelisted-web-models-merged entries=796  ← +17 web 模型
stage=plugin-models-merged entries=798
stage=complete entries=798

这些阶段日志对应 loadModelCatalog() 内的 logStage 埋点,可通过 OPENCLAW_DEBUG_INGRESS_TIMING=1 复现观察。

注意事项

  1. 不要在 models.providers 中注册 web provider — schema 验证会拒绝无效的 api 值,web provider 应只经 zero-token 桥接链路处理;
  2. 避免频繁发消息 — web 模型使用真实账号会话,频繁请求可能导致账号被封,建议控制使用频率;
  3. StreamFn 的 fallback 是 zero-token 核心机制 — plugin 系统对 web 模型完全不可见,一旦 getWebStreamFactory 查不到对应 model.api,该模型将无法获得 StreamFn,日志中会体现为 provider-stream 的跳过/警告输出;
  4. session 复用 — deepseek-web-stream 等使用 sessionMap 复用 chat session,避免创建过多会话;排查"上下文断裂"类问题时,先确认 context.sessionId 是否稳定传入。
登录后查看全文
openclaw-zero-token