★ FEATURED ARTICLE 人工智能AI Agent代码智能体自主智能体MCP ClientsCLI【免费下载链接】atomcodeClaude Code 的开源替代方案。连接任意大模型编辑代码运行命令自动验证 — 全自动执行。用 Rust 构建极致性能。 An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get Started项目地址https://gitcode.com/atomgit_atomcode/atomcode点击查看免费下载本篇技术指南以 atomcode 的《OpenRouter 免费模型一键接入》设计文档docs/superpowers/specs/2026-08-28-openrouter-quick-connect-design.md状态为 Approved design目标分支 release/v5.1.0为核心骨架结合仓库中已落地的实现源码展开。你将掌握为什么 atomcode 选择在额度用尽与新用户未领到 CodingPlan两个时刻做低摩擦漏斗、/openrouter命令的两种取 key 入口无参 OAuth PKCE 与带参直传、免费模型发现与幂等装配的下游流程、nudge 触发与去重策略以及对应的组件划分、数据流、错误处理与测试设计。一、设计目标在两个没有可用模型的时刻完成低摩擦接入OpenRouter 是汇集大量模型含众多:free免费模型的聚合网关atomcode 已是其归因合作方——真实用户流量会通过归因头标记为AtomCode应用。本设计要解决的业务问题是当用户没有可用模型时如何把用户以零成本、一键、立即可用的方式接入 OpenRouter 免费模型从而提升 OpenRouter 使用量。技术抓手有两个精确的触发时刻额度用尽——CodingPlan 的 5h/30d 窗口配额耗尽或 claim 级联到 Lite 也拿不到新用户未领到 CodingPlan——onboarding 结束时用户没有 CodingPlan 权益。设计明确划定了非目标本期不做webui / headless / ACP 接入入口免费模型 429 时的自动轮换付费模型接入。这意味着 v1 的实现范围严格收敛在交互式 TUI 内且不触碰付费模型这一点与后续的key 安全策略是一体两面。二、复用现状不重复造轮子只借集成骨架设计文档首先探明了仓库中可直接复用的部件这是整个方案低成本的根基。下表完整列出了每个部件的复用方式部件位置复用方式OpenRouter provider presetatomcode-configprovider_preset.rsid:openrouterOpenAI 兼容base_url 就绪直接复用无需新 provider 类型归因头atomcode-capabilitiesprovider/openai_compat.rs仅对 openrouter.ai 发X-OpenRouter-*/HTTP-Referer已就绪运行时加账号/模型ProviderAccountConfigModelProfileConfigatomcode-configprovider.rsreload_provider()Config::save()装配直接复用OAuth TUI 骨架atomcode-tuixevent_loop/oauth_poll.rs后台线程→事件→存盘ESC 可取消复制形状承载 OpenRouter 的本地回调额度用尽信号atomcode-codingplanRateLimitWindow.quota_exhausted/RateLimited事件 /event_loop/usage_monitor.rs触发 nudge 的现成信号命令注册atomcode-tuixcommands.rsBUILTIN_COMMANDS[]新增/openrouter一条明确不复用的部分atomgit 自家 OAuth 是 state 轮询式流程与 OpenRouter 的 localhost-callback PKCE 是不同协议只借 TUI 集成骨架后台线程→事件→存盘不共用协议代码。从源码看这些复用点均已落实OpenRouter preset 定义在 provider_preset.rsid: openrouter、provider_type: OpenAiwire 类型为openai即走 chat/completions 协议、default_base_url: Some(https://openrouter.ai/api/v1)、api_key_env: Some(OPENROUTER_API_KEY)、model_source: DiscoveryApi。测试registry_covers_the_curated_vendors明确断言preset(openrouter).is_some()。归因头实现在 openai_compat.rsOPENROUTER_ATTRIBUTION_HEADERS只含两个 OpenRouter 真正读取的头——HTTP-Referer应用的稳定标识与X-Title: AtomCode排行榜展示名。并且只在is_openrouter_url()判定目标主机为openrouter.ai时才注入openai_compat.rs避免向其他 OpenAI 兼容端点泄漏产品身份。/openrouter命令已注册进 commands.rs 的BUILTIN_COMMANDSdesc: Connect to OpenRouter free models (/openrouter reuses the saved key, or OAuth the first time; /openrouter login authorises again; /openrouter key uses that key)needs_args: false、acp: false——即不在 ACP 会话中暴露。OAuth 后台轮询骨架见 oauth_poll.rsstd::thread::spawn起后台线程避免阻塞 tokio worker通过mpsc通道把OauthEvent::Authorized / Failed推回事件循环事件循环据此关闭模态框或展示错误。三、取得 API key 的两条入口下游汇合拿到 key 之后的下游逻辑只写一份取 key 有两条并列入口用户在任一时刻可用任一方式完成接入。A./openrouter无参——OAuth PKCE 自动获取OpenRouter OAuth PKCE 流程的四个事实步骤设计文档已核实 OpenRouter 官方文档生成code_verifier随机与code_challenge base64(sha256(code_verifier))S256 方法。绑定本地任意空闲端口打开浏览器访问https://openrouter.ai/auth?callback_urlhttp://localhost:port/callbackcode_challengechallengecode_challenge_methodS256本地极小 HTTP listener后台线程接收GET /callback?codecode。ESC 随时可取消即使请求卡死最多泄漏一个线程UI 不阻塞复用了 atomgit 登录 ESC 卡死修复的教训。换取 keyPOST https://openrouter.ai/api/v1/auth/keysbody 为{code, code_verifier, code_challenge_method}返回{ key: 用户级 API key }。无需client_id是回调式流程。对应实现集中在 openrouter.rs属于atomcode-authcrate关键函数与设计一一对应generate_pkce()生成 96 字节随机数 → base64url无填充得到 128 字符 verifier满足 RFC 7636 的 43~128 长度与 unreserved 字符集要求code_challenge_s256()用base64url(sha256(verifier))计算 S256 challengeopenrouter.rs。测试用 RFC 7636 附录 B 官方向量验证verifierdBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk→ challengeE9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM。build_auth_url(callback_url, code_challenge)拼授权 URLcallback 与 challenge 均做最小 RFC3986 component 编码不为此额外引入依赖见urlencoding_component测试断言callback_urlhttp%3A%2F%2Flocalhost%3A51234%2Fcallback这类转义结果。start_local_callback()绑定127.0.0.1:0端口 0 即任意空闲端口并设为非阻塞LocalCallback::wait_for_code()循环 accept处理浏览器预检、favicon 等无 code 连接写回一个等待页后继续循环真正带code的回调返回成功页并给出 code。parse_code_from_request_line解析请求行GET /callback?codeXXXfoobar且会先 percent-decodeOAuth code 中不代表空格不能按表单规则解码。exchange_code_for_key(code, verifier)POST /auth/keysparse_key_response解析{ key: sk-or-v1-... }缺失 key 字段时报错。B./openrouter key带参——用户直接传用户把已有的 OpenRouter API key如从 openrouter.ai/keys 页面拿到的sk-or-v1-...直接跟在命令后跳过整个 OAuth 流程直接进入下游发现与装配。兜底策略YAGNI不做 OpenRouter 的 headless 粘贴一次性 code 模式。无浏览器环境 / OAuth 失败时一律回落到/openrouter key更简单、结果持久。OAuth 失败的提示语会补充一句或/openrouter 你的key直接接入。四、下游免费模型发现 配置装配两条入口共用拿到 key 后两条入口汇合到同一下游逻辑发现免费模型带 key 请求GET https://openrouter.ai/api/v1/models。free 判定模型 id 带:free后缀或pricing.prompt与pricing.completion均为 00 / 0.0 / 0.00 都算零价is_zero用parse::f64() 0.0判定。排序按context_length降序。取前5个。装配建 1 个持久ProviderAccountConfig { provider: openrouter, api_key: key }每个 top 模型建一条ModelProfileConfigaccount 引用该账号model 为该 free 模型的 wire 名幂等已存在 openrouter 账号则原地更新 key、刷新模型列表不重复添加账号reload_provider()激活第一个模型Config::save()落盘。确认文案已接入 OpenRouter添加 5 个免费模型已切到 model。/model 可切换。实现源码层面的增强细节落地实现比设计稿更进一步引入了能力门控与榜单排序值得展开能力门控只装配能用的模型select_top_free_models_ranked() 在 free 价格过滤之外还要求模型supported_parameters含toolsatomcode 首个请求就携带工具调用无 tools 的模型会 404 报 No endpoints found that support tool use并且architecture.output_modalities输出text排除 Google Lyria 这类免费但只输出音频/图片的媒体生成模型。测试 fixtureMODELS_FIXTURE中特意放了vendor/music:free256K context 但 output 为 audio与vendor/notools:free300K context 但无 tools断言它们虽然 context 最大也不会被选中。OpenRouter 官方 Free models 榜单排序实现会去抓取 OpenRouter 的 discover 页面https://openrouter.ai/discover5 秒超时、最多读 4MB解析 Next.js 页面流里的{id:free, ..., models:[...], sheetModels:[...]}结构parse_discover_free_ranking把榜单上的模型排在最前榜单外再按 context 降序dated 变体 idnvidia/x-20260604:free会被剥掉日期还原成 API 的nvidia/x:freeundated。榜单页面解析失败或结构变化时静默回退到按 context 排序绝不阻塞/openrouter正常工作。装配幂等与所有权标记provision_with_listed() 是两个前端共用同一份的装配实现账号以固定 idopenrouterOPENROUTER_ACCOUNT_ID写入provider_accounts已存在则只替换 key本次添加的免费模型通过ModelProfileConfig::origin OPENROUTER_FREE_ORIGIN标记为命令托管再次运行/openrouter时被托管的模型若已不在当前免费列表涨价、下架会被移除并刷新而用户手工添加或从面板保存过的模型绝不会被改动或删除默认模型无默认时设为第一个若默认恰好是被移除的免费模型则顺移到新列表第一个default_replaced记录被替换者若模型列表为空拉取失败只换 key不清空已有模型——空列表是没查到而不是全都下架了环境变量中已有 keyOPENROUTER_API_KEY或账号里写了$VAR引用时不把明文 key 落盘。key 校验check_key()用GET /api/v1/key带 Bearer无损校验 key 是否仍有效——401/403 判 Rejected提示重新授权网络/服务端错误判 Unknown继续使用不折腾用户重走浏览器。五、触发nudge可忽略提示绝不自动切换两个入口条件收敛到 TUI 一条可忽略提示不自动切换需用户确认额度用尽quota_exhausted/ claim 级联到 Lite 失败 /RateLimited事件新用户未领到 CodingPlanonboarding 结束且无 CodingPlan 权益。文案示意额度已用尽或尚未领取 CodingPlan—— 一键接入 OpenRouter 免费模型[Enter 接入 / Esc 忽略]去重策略每会话只弹一次用户忽略后本会话不再弹呼应对 nudge/todo 不打扰的既有偏好。nudge 的接入动作默认触发 A无参 OAuthOAuth 失败时提示回落到 B。额度信号在 types.rs 中有对应数据结构RateLimitWindow含window_hours如 5h 滚动窗口与 30d 月度窗口可同时存在、call_limit、calls_used、usage_percent、quota_exhausted、reset_at_display等字段StatusResponse兼容新旧两套 schema新rate_limit_windows数组 旧current_usage/window_quota_exhausted兜底为 nudge 谓词提供了现成的触发依据。六、组件划分各自独立、可单测设计将实现拆成四个边界清晰的组件均可在不联网的情况下用 fixture 数据单测openrouter_oauth置于atomcode-authPKCE 生成 / 起手 URL 构造 / 本地回调 listener / code→key 交换。纯逻辑challenge 计算、URL 编码、{key}响应解析无需联网可测。实现即上文所述的 openrouter.rs 中generate_pkce、build_auth_url、start_local_callback/LocalCallback::wait_for_code、exchange_code_for_key。OpenRouter 发现客户端list_free_models_by_context(key) - VecModelEntryfixture JSON 可测。实现为fetch_top_free_models/fetch_free_catalogselect_top_free_models_ranked测试用MODELS_FIXTURE与DISCOVER_FIXTURE两个内嵌 fixture 覆盖排序、边界与页面解析。装配 helperkey models → 账号 profiles已有账号幂等更新调用 reload save。实现为provision/provision_with_listed对Config结构体直接可测。TUI 接线nudge 状态/openrouter [key]命令注册进BUILTIN_COMMANDSacp:false后台接入任务复用 oauth_poll 模式线程→事件→apply。七、数据流总览nudge / /openrouter[ key] │ ├─(无参)→ OAuthbrowser 本地 listener → code → 换 key ─┐ └─(带参)→ 直接用 key ───────────────────────────────────┤ ▼ GET /modelsfree 过滤 context 排序 top5 ▼ 建账号 5 模型幂等→ reload_provider Config::save ▼ UI 确认 切到首个免费模型关键约束全部网络请求都在后台线程UI 不阻塞任何等待处 ESC 均可取消。这与oauth_poll.rs的模式一致——后台线程完成取 key、拉模型列表等阻塞操作后把结果事件推回事件循环事件循环只负责 apply 配置与刷新 UI。Config::save()落盘与reload_provider()热激活分别对应 config/mod.rs 的save(self, path)经由ConfigStore::new(path).replace(self)原子替换与 event_loop/mod.rs 的RuntimeControl::reload_provider把新的CodingAgentConfig交给后台运行时。八、错误处理清单打不开浏览器 / headless→ 提示/openrouter key换 key 网络卡死→ 可取消 中文友好错误复用friendly_http_error该工具位于atomcode-capabilities的provider/mod.rs、openai_compat.rs、anthropic.rs、ollama.rs等适配器中/models返回 0 个免费模型OpenRouter 侧变动→ 回退到一个内置已知 free id或提示/model自选免费不足 5 个→ 有几个装几个select_top_free_models_ranked的truncate(limit)天然满足key 安全最重要这是能花用户 OpenRouter 账户钱的真实 key。只添加免费模型、默认切到免费模型绝不静默启用付费模型。key 持久化与现有 providerapi_key同等对待ProviderAccountConfig.api_key字段持久账号写入磁盘、ephemeral 账号仅驻内存且环境变量引用的 key 不写明文。九、持久化与范围持久保存契合提升使用量目标重启免重连账号 模型 profile 都写入持久配置重启后/openrouter可通过saved_key()读取已保存 key支持$VAR展开与OPENROUTER_API_KEY环境变量回退直接复用无需重新授权。v1 交互式 TUIwebui / headless / ACP 之后再评估。命令注册处acp: false即为此边界的显式表达。十、测试设计设计文档给出的测试矩阵在实现中均已落成单元测试见 openrouter.rs 的 tests 模块PKCEcode_verifier→ S256code_challenge用RFC 7636 附录 B 官方向量验证auth URL 参数编码callback 含:/需转义localhost 端口占位端口 0 绑定。发现fixture/modelsJSON → free 过滤 context 降序 top5边界并列 context 按 id 稳定排序、免费 5、pricing 字段缺失/非零、paid 剔除、nopricing保守剔除、audio 输出与无 tools 模型排除、榜单排序覆盖 context 排序。装配账号 profiles 结构正确已有账号幂等reload / save 被调用。nudge触发谓词quota_exhausted/ onboarding 无 CodingPlan→ 只弹一次忽略后抑制。取消等待中 ESC 不阻塞 UI镜像 atomgit ESC 测试。命令解析/openroutervs/openrouter key分派正确key 参数不落入日志。十一、风险与备注提升使用量是增长目标诚实的抓手就是在用户没有可用模型的两个时刻做低摩擦漏斗。归因头已把流量标记为 AtomCodeHTTP-RefererX-Title: AtomCode免费模型在 OpenRouter 侧对 agentic harness 有门槛归因头正是解锁该门槛的凭证。免费模型有 OpenRouter 侧自己的限流如每日请求数某 free 模型 429 时轮换到 top5 下一个——列为 v2 可选v1 不做。真机验证点浏览器回调、ESC 取消、Config::save后重启仍在、切到免费模型后可正常对话。十二、快速上手路径在 atomcode TUI 中直接输入/openrouter自动打开浏览器完成 OAuth PKCE 授权授权后自动发现 top5 免费模型并装配、切换或输入/openrouter sk-or-v1-...用已有 key 跳过 OAuth直接进入发现与装配再次运行/openrouter无参会复用已保存 key仅刷新模型列表接入完成后用/model在免费模型间切换用/provider管理供应商账号。如需深入源码可依次阅读设计文档 2026-08-28-openrouter-quick-connect-design.md、核心实现 openrouter.rs、preset 定义 provider_preset.rs、账号/模型结构 provider.rs、归因头 openai_compat.rs 与命令注册 commands.rs。赞分享人工智能AI Agent代码智能体自主智能体MCP ClientsCLI【免费下载链接】atomcodeClaude Code 的开源替代方案。连接任意大模型编辑代码运行命令自动验证 — 全自动执行。用 Rust 构建极致性能。 An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get Started项目地址https://gitcode.com/atomgit_atomcode/atomcode点击查看免费下载相关推荐AtomCode OpenRouter 免费模型一键接入PKCE 取 Key、Top5 免费模型发现与幂等装配实战AtomCode OpenRouter 免费模型一键接入PKCE 取 Key、Top5 免费模型发现与幂等装配实战 导读 当用户额度用尽或新用户未领取 Cod人工智能AI Agent代码智能体自主智能体MCP ClientsCLI2025新范式Avante.nvim中OpenRouter免费模型配置与排障指南2025新范式Avante.nvim中OpenRouter免费模型配置与排障指南 你还在为AI编程助手的高昂费用发愁吗本文将带你零成本解锁Avante.nvAI 应用AI 插件代码智能体人工智能OpenClaw 接入 OpenRouter一个 API Key 打通多模型生态的完整配置指南OpenClaw 接入 OpenRouter一个 API Key 打通多模型生态的完整配置指南 本篇指南讲解如何在 OpenClawopenclaw cn人工智能AI Agent即时通讯后端本地部署语音创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
