planet/docs/plans/ai-provider-openclaw-style-routing-plan.md

AI Provider OpenClaw-Style Routing Plan

Last updated: 2026-05-20

Summary

Planet 的 AI Provider 路由要从“运行时识别特殊 provider / 特殊模型”收敛到 OpenClaw 风格的配置驱动模型：模型引用、协议、鉴权、轻量探测、真实调用和模型级例外都由 provider catalog / preset / runtime metadata 描述，运行时只解释这些元数据，不再散落 if provider == ... and model == ... 这类硬编码。

这份计划覆盖 Admin Next 的 Provider 配置体验、backend settings API、aiprovider 适配服务和未来模型目录同步方式。目标是让 OpenCode Go、MiniMax、DeepSeek、OpenAI-compatible、Anthropic-compatible、Ollama、OpenRouter / One API 类代理都能用同一套规则扩展。

Background

当前实现已经完成了两步临时修正：

• OpenCode Go 模型目录不再使用普通 Zen free 列表，而是使用 https://opencode.ai/zen/go/v1/models。
• minimax-m2.7 / minimax-m2.5 的协议例外已从 aiprovider 运行逻辑移到 model_provider_apis 元数据中。

但整体还没有完全达到 OpenClaw 式结构。OpenClaw 的关键思想是：

• 模型引用使用 provider/model，由 provider 前缀确定 runtime provider。
• provider 插件或 catalog 拥有 normalizeModelId、normalizeTransport、normalizeConfig、prepareRuntimeAuth、createStreamFn 等 provider 行为。
• 主推理循环不认识具体模型名，只使用解析后的 provider config、transport 和 request adapter。
• 上游网关能自己路由时，尽量透传 provider routing metadata，不在本地复制上游逻辑。

Planet 不需要完整复制 OpenClaw 插件系统，但需要学习它的边界划分。

Design Principles

• Provider catalog 是路由事实来源，runtime 不是。
• 模型级协议例外必须是 metadata，例如 model_provider_apis，不能是 Python set / if 分支。
• 轻量连通性测试只验证网络、鉴权和模型目录，不发真实 prompt。
• 真实模型调用只发生在 Playground、AI brief、分析任务等明确需要生成的路径。
• 保存配置不自动设为默认，不自动触发连接测试；保存、设默认、测试三种按钮职责分离。
• 目录刷新使用增量合并语义：发现新模型，标记旧模型 stale，不直接删除用户选择或自定义模型。
• 如果 provider 不提供可靠 /models，可以用内置 preset 确认已知模型，但 UI 必须说清楚这是 preset confirmation，不是假装 provider 返回了目录。

Target Data Model

Provider preset / runtime config 应逐步收敛为类似结构：

{
  "provider": "opencode-go",
  "label": "OpenCode Go",
  "default_transport": "openai-completions",
  "base_url": "https://opencode.ai/zen/go/v1",
  "auth": {
    "type": "bearer",
    "api_key_env": "OPENCODE_GO_API_KEY"
  },
  "models": [
    {
      "id": "glm-5.1",
      "label": "GLM 5.1",
      "transport": "openai-completions",
      "context_window": null,
      "capabilities": ["text"]
    },
    {
      "id": "minimax-m2.7",
      "label": "MiniMax M2.7",
      "transport": "anthropic-messages",
      "capabilities": ["text", "reasoning"]
    }
  ],
  "discovery": {
    "type": "openai-models",
    "url": "https://opencode.ai/zen/go/v1/models",
    "auth": "provider-api-key"
  }
}

Runtime 选择规则：

1. 解析 provider。
2. 解析 model。
3. 从 models[].transport 找模型级 transport。
4. 若没有模型级 transport，使用 provider default_transport。
5. 将解析结果传给 aiprovider。
6. aiprovider 只按 transport 组装请求，不认识 provider 专属模型名。

Implementation Plan

Phase 1: Stabilize Current Metadata Path

• Keep model_provider_apis as the immediate compatibility bridge.
• Ensure _provider_defaults() includes provider metadata such as model_provider_apis.
• Ensure _runtime_config_from_ai_payload() sends the resolved metadata through AIProviderClient.
• Ensure AIProviderClient forwards metadata to aiprovider with a structured header.
• Ensure aiprovider.ProviderService reads model metadata and resolves provider_api = model_provider_apis[model] ?? provider_api.
• Add tests proving aiprovider does not contain provider/model-specific literals for routing decisions.

Phase 2: Replace model_provider_apis With Structured Model Catalog

• Extend backend/app/services/llm_provider_catalog.py preset shape with models_metadata.
• Preserve old models as a compatibility list for the UI.
• Add helpers:
  • get_provider_model_metadata(provider, model)
  • resolve_provider_transport(provider_config, model)
  • merge_discovered_models(existing, discovered)
• Return both models and models_metadata from refresh endpoints.
• Admin Next should render model labels, capabilities and transport hints from metadata.

Phase 3: Provider Discovery And Incremental Sync

• Add provider discovery descriptors:
  • OpenAI-compatible /models
  • Anthropic-compatible no-models / preset-confirmed path
  • Ollama /api/tags
  • OpenCode Go /zen/go/v1/models
  • OpenRouter / One API passthrough model discovery
• Add incremental merge behavior:
  • New discovered model: add.
  • Existing discovered model: update last_seen_at, metadata.
  • Missing discovered model: mark stale, do not delete.
  • User custom model: keep unless explicitly removed.
• Surface discovery source in Admin Next: 实时发现 / 内置预设 / 用户自定义 / 已过期.

Phase 4: Transport Adapters

• Replace provider-specific request decisions with adapter descriptors:
  • openai-completions
  • anthropic-messages
  • ollama-generate
  • future openai-responses
  • future gemini-generate-content
• Each adapter owns:
  • path
  • auth header format
  • request body transform
  • response text extraction
  • reasoning/thinking block extraction
  • models endpoint strategy
• ProviderService.analyze() should select adapter by resolved transport and call the adapter.

Phase 5: Admin Next UX

• Model provider page should show:
  • provider status tag
  • default model tag
  • source tag: env / runtime / preset / discovered
  • model list with transport/capability hint
  • separate buttons for save, set default, refresh model catalog, lightweight test
• The connect plug button remains lightweight.
• Full generation test lives only in Playground or a clearly named “试运行” action.
• If lightweight test falls back to preset confirmation, toast must say so explicitly.

TODO

• Add models_metadata to provider presets and refresh responses.
• Add runtime resolver helper for provider/model transport selection.
• Remove any remaining provider/model-specific literals from aiprovider runtime routing.
• Add tests that opencode-go/minimax-m2.7 resolves through metadata, not through runtime hardcode.
• Add tests for lightweight connectivity:
  • 401 / 403 fail as auth error.
  • 404 with known preset model passes as preset-confirmed.
  • /models missing alias passes only when preset contains the alias.
  • unknown model fails.
• Add discovery descriptors for OpenCode Go, OpenAI-compatible, Anthropic-compatible, Ollama, OpenRouter / One API.
• Add incremental model catalog merge semantics with stale marking.
• Update Admin Next model list to show model source, transport and capability.
• Keep save / set default / lightweight test / full test as separate actions.
• Document the final provider catalog schema in technical docs after implementation.

Current Acceptance Criteria

• No runtime routing branch may depend on concrete model names like minimax-m2.7.
• OpenCode Go model refresh must not use the ordinary Zen free-model endpoint.
• Lightweight connect must not call analyze() or consume generation quota.
• Saving a provider must not automatically set it as default.
• Provider UI must distinguish configured key, fallback key, preset model and live-discovered model.

Related Files

• backend/app/services/llm_provider_catalog.py
• backend/app/api/v1/settings.py
• backend/app/services/ai_client.py
• aiprovider/main.py
• aiprovider/provider_service.py
• frontend/src/admin/pages/PlainResourcePages.tsx
• docs/deprecated/admin-next-parity-audit-closeout-plan.md