OpenClaw Zero Token 的 Web 模型架构:Cookie 认证如何驱动 13 个免 API Key 大模型
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)。
四条核心设计原则
原文档给出的四条设计原则,均可在源码中找到对应物证:
- 非插件架构:Web 模型不是 OpenClaw Plugin,不走
ProviderPlugin.createStreamFn()插件体系。在 provider-stream.ts 的 fallback 注释中明确写道:"Web models are not bundled as plugins, so resolveProviderStreamFn returns undefined"; - 独立 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>做类型约束; - 凭证独立存储:Cookie/Session 存储在
auth-profiles.json,不经过 OpenClaw upstream config。凭证读写经由 auth-profiles.ts 导出的一组 store/profile 函数完成(ensureAuthProfileStore、saveAuthProfileStore、listProfilesForProvider等); - 白名单门控:用户可见性由
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 行)的执行序列:
- 读取
auth-profilesstore,筛出已授权模型(profile id 以-web结尾或含-web:),列出并打上 "✓ 已授权" 标记; - 交互式选择:支持编号多选(逗号分隔)、
a授权全部、0退出; - 对每个选中的 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 行);
- 保存凭证:
- 最后调用
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 行)的逻辑:
- 读取
config.agents.defaults.models白名单,跳过不含/的键; - 对每个
provider/modelId,先经isWebProvider(providerId)过滤,非 web provider 直接跳过; - 以
provider::modelId(小写)为去重键,目录中已存在的条目不重复注入; - 到静态表
KNOWN_WEB_MODEL_ENTRIES(第 326-375 行)中查找provider + modelId的元数据(显示名、contextWindow、是否 reasoning 等),查不到则跳过——静态表是白名单条目"能出现在目录里"的必要条件; - 找到后合成条目推入目录,显示名优先取白名单中用户配置的
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 行)实现了"两级解析":
- 第一级:调用插件系统的
resolveProviderStreamFn({ provider, config, ... });web 模型不是插件,此处返回undefined; - 第二级(fallback):
getWebStreamFactory(params.model.api)按model.api查工厂映射表;查不到同样返回undefined; - 凭证加载:
ensureAuthProfileStore(agentDir)打开凭证库,listProfilesForProvider(store, provider)取该 provider 的 profile 列表,为空时打印no auth profile found for provider=...并跳过; - 凭证解包:按 profile 类型分支提取 credential 字符串——
type: "token"取profile.token;type: "api_key"取profile.key;type: "oauth"将整个 profileJSON.stringify后传入;其他类型打警告并放弃(第 57-70 行); - 最终
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-aiAssistantMessageEvent,并在出现工具调用时把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 解析使用。
本地工程适配情况与验证结果
已修复 ✅
provider-stream.ts— 添加了 fallback 分支,从getWebStreamFactory()+ auth-profiles 获取 web 模型 StreamFn(见上文第 35-77 行实现);web-stream-factories.ts— 桥接模块已存在,13 个 provider 的工厂函数全部注册;model-catalog.ts— 添加了KNOWN_WEB_PROVIDER_IDS、isWebProvider()、mergeWhitelistedWebModels()及静态元数据表KNOWN_WEB_MODEL_ENTRIES;- 配置 — 从
models.providers移除了无效api类型的 web provider 条目(避免 schema 报错),onboard 流程中的syncModelsProvidersToConfig()也会主动过滤 web provider 以防其回流。
依赖前提 ✅
- auth-profiles.json — 各 web provider 的凭证(
type: "token",token 为凭证对象 JSON); - openclaw.json —
agents.defaults.models白名单包含 web 模型(如{"deepseek-web/deepseek-chat": {"alias": "DeepSeek V3"}}); - 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 复现观察。
注意事项
- 不要在
models.providers中注册 web provider — schema 验证会拒绝无效的api值,web provider 应只经 zero-token 桥接链路处理; - 避免频繁发消息 — web 模型使用真实账号会话,频繁请求可能导致账号被封,建议控制使用频率;
- StreamFn 的 fallback 是 zero-token 核心机制 — plugin 系统对 web 模型完全不可见,一旦
getWebStreamFactory查不到对应model.api,该模型将无法获得 StreamFn,日志中会体现为 provider-stream 的跳过/警告输出; - session 复用 — deepseek-web-stream 等使用
sessionMap复用 chat session,避免创建过多会话;排查"上下文断裂"类问题时,先确认context.sessionId是否稳定传入。