claw-code 的 api crate 架构解析多 LLM Provider 客户端与双线协议分发机制【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code导读本文基于 rust/crates/api/AGENTS.md 展开深入解析 claw-code 仓库中apicrate 的设计一个将 Anthropic、xAI、OpenAI、DashScope通义千问与 Ollama 统一收纳的 LLM Provider 客户端层底层仅通过 Anthropic Messages 与 OpenAI Chat Completions 两套线上协议完成通信。读完本文你将掌握ProviderClient门面的模型路由规则、环境变量认证约定、MessageRequest/StreamEvent线类型设计、重试与请求体大小防护机制以及该 crate 的模块组织与测试纪律可直接对照仓库源码继续深入。一、OVERVIEW一个门面五家 Provider两套协议apicrate 是整个 claw-code 的 LLM Provider 客户端层。它的核心设计思路是上游模型千变万化但线协议只有两种——Anthropic 原生的 Messages API以及 OpenAI 的 Chat Completions 兼容格式。xAI、DashScope、Ollama 虽然品牌不同却都能讲 OpenAI 兼容的“方言”因此共享同一个兼容客户端实现。从源码结构看crate 内部模块划分如下对应 lib.rs 中的mod声明模块职责client.rsProviderClient门面枚举负责from_model(model)路由、send_message/stream_message统一入口providers/mod.rsProvidertrait、ProviderKind、ProviderMetadata、模型别名解析、token 上限、能力/诊断报告、preflight 校验providers/anthropic.rsAnthropicClient在 crate 根被重导出为ApiClientAPI Key/OAuth 双认证、SSEMessageStream、prompt cache 钩子providers/openai_compat.rsOpenAiCompatClientOpenAI 兼容翻译层、模型怪癖谓词、请求体大小估算与护栏types.rsProvider 无关的线类型MessageRequest、InputMessage、ContentBlock、StreamEvent、Usage、ToolDefinition、ToolChoicesse.rsSseParser、parse_framehttp_client.rsreqwest 构建器、ProxyConfig、TimeoutConfigerror.rsApiErrorprompt_cache.rsPromptCacheStats仅 Anthropic 使用lib.rs精选的pub use列表构成唯一公开 API 面同时重导出 telemetry crate 的部分条目二、ProviderClient 门面模型名到 Provider 的路由决策ProviderClient是一个枚举而不是 trait 对象这是本 crate 的关键取舍。它在 client.rs 中定义pub enum ProviderClient { Anthropic(AnthropicClient), Xai(OpenAiCompatClient), OpenAi(OpenAiCompatClient), }枚举变体分别是AnthropicClient与两路OpenAiCompatClientxAI 与 OpenAI 各持一份预设配置。Providertrait 虽然存在见 providers/mod.rs但整体是#![allow(dead_code)]允许死代码的并不参与实际分发——这也是 AGENTS.md 明确记录的约定。from_model的完整路由逻辑ProviderClient::from_model_with_anthropic_authclient.rs执行如下决策链先调用resolve_model_alias将别名如opus、grok解析为真实模型名再调用detect_provider_kind判定ProviderKindAnthropic / Xai / OpenAi按 kind 构造对应客户端Anthropic优先使用显式传入的AuthSource否则走AnthropicClient::from_env()XaiOpenAiCompatClient::from_env(OpenAiCompatConfig::xai())OpenAi先检查OLLAMA_HOST环境变量——一旦设置无条件路由到本地 Ollama免 API Key否则按模型元数据选择 DashScope 配置还是 OpenAI 配置。其中有一个容易被忽略的细节DashScope 的 qwen-* 系列模型返回的也是ProviderKind::OpenAi因为它们讲 OpenAI 线格式但它们必须走读取DASHSCOPE_API_KEY、指向dashscope.aliyuncs.com的 DashScope 配置。路由代码通过metadata_for_model返回的auth_env DASHSCOPE_API_KEY来区分let config match providers::metadata_for_model(resolved_model) { Some(meta) if meta.auth_env DASHSCOPE_API_KEY OpenAiCompatConfig::dashscope(), _ OpenAiCompatConfig::openai(), };detect_provider_kind的优先级模型名到 Provider 的判定在 providers/mod.rs 中遵循严格优先级OLLAMA_HOST优先只要设置所有模型一律路由到本地 OpenAI 兼容端点本地 Ollama 无需 API Key且忽略 DashScope/OpenAI 的环境变量分发模型名元数据claude*/anthropic/→ Anthropicgrok*→ Xaiopenai/、gpt-*→ OpenAIqwen/、qwen-*→ DashScopeOpenAI 协议kimi/、kimi-*→ DashScope本地模型启发式当OPENAI_BASE_URL已设置且模型名包含:或.如llama3.2、qwen2.5-coder:7b优先走 OpenAI 兼容端点避免被环境里残留的 Anthropic 凭据“抢走”凭据嗅探兜底依次检查ANTHROPIC_API_KEY/保存的 OAuth、OPENAI_API_KEY、XAI_API_KEY、OPENAI_BASE_URL最后兜底为 Anthropic。模型别名注册表MODEL_REGISTRYproviders/mod.rs内置了常用别名resolve_model_alias会做 trim 小写匹配别名解析结果opusclaude-opus-4-7sonnetclaude-sonnet-4-6haikuclaude-haiku-4-5-20251213grok/grok-3grok-3grok-mini/grok-3-minigrok-3-minigrok-2grok-2kimikimi-k2.5crate 内测试resolves_existing_and_grok_aliases与resolves_grok_aliases分别断言了这些映射见 client.rs 与 providers/mod.rs。三、ProviderMetadata 与环境变量对统一的认证约定AGENTS.md 明确约定Provider 配置遵循*_API_KEY/*_BASE_URL的环境变量对并记录在ProviderMetadata中providers/mod.rspub struct ProviderMetadata { pub provider: ProviderKind, pub auth_env: static str, pub base_url_env: static str, pub default_base_url: static str, }各 Provider 的完整环境变量对照如下来自MODEL_REGISTRY与metadata_for_model分支Provider认证环境变量Base URL 环境变量默认 Base URLAnthropicANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKENANTHROPIC_BASE_URLhttps://api.anthropic.comxAIXAI_API_KEYXAI_BASE_URLhttps://api.x.ai/v1OpenAIOPENAI_API_KEYOPENAI_BASE_URLhttps://api.openai.com/v1DashScopeDASHSCOPE_API_KEYDASHSCOPE_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1OllamaOLLAMA_HOST免 KeyOLLAMA_HOSThttp://127.0.0.1:11434/v1两个值得注意的实操细节Ollama 免认证OpenAiCompatClient::from_ollama_env用占位符ollama作为 API Key仅用于填充 Authorization 头见 openai_compat.rs.env 文件支持read_env_non_empty在真实环境变量缺失时会回退到工作目录.env文件读取parse_dotenv/load_dotenv_file/dotenv_value见 providers/mod.rs支持KEYVALUE、引号剥除与export前缀。四、AnthropicClient双认证、指数退避与 SSE 流AnthropicClientproviders/anthropic.rs在 crate 根被重导出为ApiClientlib.rs。认证模型API Key 与 OAuth 双轨AuthSource枚举providers/anthropic.rs描述四种认证形态pub enum AuthSource { None, ApiKey(String), BearerToken(String), ApiKeyAndBearer { api_key: String, bearer_token: String }, }同时设置ANTHROPIC_API_KEY与ANTHROPIC_AUTH_TOKEN时会同时发送x-api-key头与Bearer头OAuthTokenSetaccess_token / refresh_token / expires_at / scopes用于已保存的 OAuth 凭据resolve_saved_oauth_token会在 token 过期时自动用 refresh_token 换取新 token 并回写providers/anthropic.rs一个实用的错误提示若把sk-ant-*开头的 Key 误放到ANTHROPIC_AUTH_TOKEN服务端会返回 401enrich_bearer_auth_error会追加“请移到ANTHROPIC_API_KEY”的修复提示providers/anthropic.rs。重试策略默认max_retries 8、initial_backoff 1s、max_backoff 128sproviders/anthropic.rs。重试条件包括可重试 HTTP 状态码408/409/429/500/502/503/504、网络错误以及带有“no parseable body”“connection reset”等网关特征短语的 400providers/anthropic.rs。退避采用指数增长叠加 splitmix64 随机抖动抖动来源混合纳秒时钟与进程内单调计数器用于分散多客户端并发重试providers/anthropic.rs。Preflight本地字节估算 count_tokens 精算preflight_message_requestproviders/mod.rs用serde_json::to_vec的字节长度除以 4 估算输入 tokenAnthropicClient侧还会进一步调用POST /v1/messages/count_tokens精算providers/anthropic.rs任一环节检测到超出上下文窗口即返回ApiError::ContextWindowExceeded。流式接口MessageStream::next_event()通过SseParser增量消费响应分块产出StreamEvent在MessageStop时把最后一次usage记入 prompt cacheproviders/anthropic.rs。五、OpenAiCompatClient兼容翻译层与模型怪癖处理OpenAiCompatClient是工作量最大的部分被 AGENTS.md 称为“Heavy translation layer”。配置预设OpenAiCompatConfigopenai_compat.rs除 provider 名称、认证/Base URL 环境变量外还携带请求体大小上限预设provider_name请求体上限默认 Base URLxai()xAI50MB52,428,800 Bhttps://api.x.ai/v1openai()OpenAI100MB104,857,600 Bhttps://api.openai.com/v1dashscope()DashScope6MB6,291,456 Bdogfood 实测https://dashscope.aliyuncs.com/compatible-mode/v1OLLAMA_CONFIGOllama100MBhttp://127.0.0.1:11434/v1send_raw_request在发送前会执行check_request_body_size_for_base_url做预检超限即拒绝。核心翻译函数lib.rs公开导出了以下可独立复用的翻译函数lib.rsbuild_chat_completion_request把MessageRequest编译为 Chat Completions JSONtranslate_message单条消息翻译sanitize_tool_message_pairing/flatten_tool_result_content工具消息配对与 tool result 内容拍平estimate_request_body_size/check_request_body_size请求体估算与护栏is_reasoning_model推理模型谓词model_rejects_is_error_field/model_requires_reasoning_content_in_history按模型怪癖决定是否保留is_error字段、是否把历史 Thinking 块回显为reasoning_content典型如 DeepSeek V4。流式侧由StreamState维护状态机openai_compat.rs把 OpenAI 分块中的reasoning_content/reasoning/thinking.content三种字段统一归一为Thinking内容块把工具调用增量聚合成完整的ToolUse块并在流结束时补发ContentBlockStop与MessageDelta含 stop_reason——这意味着上层消费方无需关心上游是 Anthropic 还是 OpenAI 方言。六、能力矩阵与诊断报告ProviderCapabilityReportproviders/mod.rs按 Provider 声明能力用ProviderFeatureSupportSupported / Unsupported / PassthroughAsTool三态表达。测试provider_capability_matrix_snapshots_openai_compat_differencesproviders/mod.rs固化了关键差异快照Anthropic支持 prompt cache、流式不支持 streaming_usage、custom_parameters、reasoning_effortxAIgrok-3OpenAI 协议不支持 streaming_usage 与 reasoning_effort固定采样推理模型OpenAI支持 streaming_usage、custom_parameters、reasoning_effortDeepSeek V4 额外支持 reasoning_content_history所有 Provider 的web_search/web_fetch均标为PassthroughAsTool——即作为普通函数工具透传而非 Provider 原生 Web 能力。provider_diagnostics_for_requestproviders/mod.rs会针对具体请求产出带code/severity/action的诊断项例如reasoning_effort_unsupportedWarning请求携带reasoning_effort但 Provider 不支持建议移除或改路由到openai/o4-minireasoning_model_fixed_samplingInfo推理模型将省略 temperature/top_p/frequency_penalty/presence_penalty 等调参字段deepseek_v4_reasoning_historyInfoDeepSeek V4 要求把助手 Thinking 历史回显为reasoning_contentweb_search_passthrough_tool/web_fetch_passthrough_toolInfo提示 web 工具以普通函数工具暴露。七、Provider 无关的线类型与 token 管理types.rs定义了整套 Provider 无关的数据结构types.rsMessageRequest模型、max_tokens、消息、system、工具、stream标志以及可选的 OpenAI 调参字段temperature、top_p、frequency_penalty、presence_penalty、stop、reasoning_effort与extra_body自定义扩展参数字典用于web_search_options、parallel_tool_calls等网关特性核心协议键受保护不可覆盖InputContentBlockText / Thinking含 signature/ ToolUse / ToolResultToolChoiceAuto / Any / Tool{name}Usageinput / output / cache_creation / cache_read 四类 token并可通过estimated_cost_usd(model)基于 runtime 定价表估算美元成本types.rsStreamEventMessageStart / MessageDelta / ContentBlockStart / ContentBlockDelta / ContentBlockStop / MessageStop 六类事件。max_tokens_for_model采用启发式opus 系默认 32,000其余 64,000若命中model_token_limit注册表providers/mod.rs则取两者较小值。注册表覆盖Claude Opus 4.x输出 32K/上下文 200K、Sonnet 4.6 与 Haiku 4.5输出 64K/200K、Grok-3 系列64K/131K、GPT-4.1 系列32,768/1,047,576、GPT-5.4 系列128K/1M 或 400K、Kimi K2.5/K1.516,384/256K、qwen-max/qwen-plus8,192/131K。max_tokens_for_model_with_override允许插件显式覆盖。八、HTTP 客户端、代理与超时http_client.rs构建带统一 user-agentclawd-rust-tools/0.1的 reqwest 客户端ProxyConfighttp_client.rs读取HTTP_PROXY/http_proxy、HTTPS_PROXY/https_proxy、NO_PROXY/no_proxy大写优先于小写、空串视为未设置也支持通过from_proxy_url用单一proxy_url同时覆盖 HTTP 与 HTTPSTimeoutConfighttp_client.rsCLAW_API_CONNECT_TIMEOUT默认 30s与CLAW_API_REQUEST_TIMEOUT默认 300s超时错误被标记为可重试交由既有指数退避处理。九、Prompt CacheAnthropic 专属的缓存记账prompt_cache.rs提供仅针对 Anthropic 的PromptCache默认配置completion TTL 30 秒、prompt TTL 5 分钟、cache_break_min_drop2000 tokenprompt_cache.rs以会话为单位落盘session-state.json、stats.json、completions/request_hash.json通过 FNV 哈希指纹请求命中时直接返回缓存的MessageResponse响应侧记录cache_creation_input_tokens/cache_read_input_tokens并产出CacheBreakEventunexpected / reason / token_drop用于诊断缓存失效prompt_cache.rs。在ProviderClient层面with_prompt_cache/prompt_cache_stats/take_last_prompt_cache_record仅对 Anthropic 变体生效client.rs。十、模块约定与测试纪律AGENTS.md 的 CONVENTIONS 与 TESTS 小节是本 crate 的工程契约模块默认私有lib.rs的pub use列表是唯一公开 API 面lib.rs 已逐一验证纯构造函数标注#[must_use]从源码可见with_base_url、with_retry_policy、with_prompt_cache等均遵循分发走ProviderClient枚举而非 trait 对象Providertrait 被 dead-code 允许叶子文件按需允许#![allow(clippy::cast_possible_truncation)]流统一收敛到MessageStreamnext_event()产出StreamEventclient.rs 中MessageStream枚举统一了 Anthropic 与 OpenAI-compat 两种流。测试层面tests/下四个集成测试文件分工明确client_integration核心客户端行为、openai_compat_integrationOpenAI 兼容翻译路径、provider_client_integrationProviderClient分发、proxy_integration代理配置。一个重要的并发纪律是所有触碰环境变量的测试必须通过共享的env_lock()互斥锁串行化如 client.rs 所示否则并行测试会互相观察到对方尚未还原的环境变量导致偶发失败测试还普遍使用EnvVarGuard快照-还原守卫即使断言 panic 也能保证进程环境不被污染。benches/request_building.rs是工作区唯一的 Criterion 基准测试聚焦热点翻译函数该文件整体豁免严格 lint。结语apicrate 以“枚举门面 双线协议 元数据驱动路由”的方式把五家 Provider 收敛为统一、可诊断、可测试的调用面模型名路由优先级清晰环境变量约定统一请求体大小与上下文窗口有前置护栏推理模型怪癖有专门谓词处理认证错误与缓存失效均有可执行的诊断提示。对任何需要多 Provider 接入能力的 Rust 项目而言AGENTS.md 配合 client.rs、providers/mod.rs、providers/openai_compat.rs 等源码是一份现成的多 Provider 客户端架构参考。【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
claw-code 的 api crate 架构解析：多 LLM Provider 客户端与双线协议分发机制
claw-code 的 api crate 架构解析多 LLM Provider 客户端与双线协议分发机制【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code导读本文基于 rust/crates/api/AGENTS.md 展开深入解析 claw-code 仓库中apicrate 的设计一个将 Anthropic、xAI、OpenAI、DashScope通义千问与 Ollama 统一收纳的 LLM Provider 客户端层底层仅通过 Anthropic Messages 与 OpenAI Chat Completions 两套线上协议完成通信。读完本文你将掌握ProviderClient门面的模型路由规则、环境变量认证约定、MessageRequest/StreamEvent线类型设计、重试与请求体大小防护机制以及该 crate 的模块组织与测试纪律可直接对照仓库源码继续深入。一、OVERVIEW一个门面五家 Provider两套协议apicrate 是整个 claw-code 的 LLM Provider 客户端层。它的核心设计思路是上游模型千变万化但线协议只有两种——Anthropic 原生的 Messages API以及 OpenAI 的 Chat Completions 兼容格式。xAI、DashScope、Ollama 虽然品牌不同却都能讲 OpenAI 兼容的“方言”因此共享同一个兼容客户端实现。从源码结构看crate 内部模块划分如下对应 lib.rs 中的mod声明模块职责client.rsProviderClient门面枚举负责from_model(model)路由、send_message/stream_message统一入口providers/mod.rsProvidertrait、ProviderKind、ProviderMetadata、模型别名解析、token 上限、能力/诊断报告、preflight 校验providers/anthropic.rsAnthropicClient在 crate 根被重导出为ApiClientAPI Key/OAuth 双认证、SSEMessageStream、prompt cache 钩子providers/openai_compat.rsOpenAiCompatClientOpenAI 兼容翻译层、模型怪癖谓词、请求体大小估算与护栏types.rsProvider 无关的线类型MessageRequest、InputMessage、ContentBlock、StreamEvent、Usage、ToolDefinition、ToolChoicesse.rsSseParser、parse_framehttp_client.rsreqwest 构建器、ProxyConfig、TimeoutConfigerror.rsApiErrorprompt_cache.rsPromptCacheStats仅 Anthropic 使用lib.rs精选的pub use列表构成唯一公开 API 面同时重导出 telemetry crate 的部分条目二、ProviderClient 门面模型名到 Provider 的路由决策ProviderClient是一个枚举而不是 trait 对象这是本 crate 的关键取舍。它在 client.rs 中定义pub enum ProviderClient { Anthropic(AnthropicClient), Xai(OpenAiCompatClient), OpenAi(OpenAiCompatClient), }枚举变体分别是AnthropicClient与两路OpenAiCompatClientxAI 与 OpenAI 各持一份预设配置。Providertrait 虽然存在见 providers/mod.rs但整体是#![allow(dead_code)]允许死代码的并不参与实际分发——这也是 AGENTS.md 明确记录的约定。from_model的完整路由逻辑ProviderClient::from_model_with_anthropic_authclient.rs执行如下决策链先调用resolve_model_alias将别名如opus、grok解析为真实模型名再调用detect_provider_kind判定ProviderKindAnthropic / Xai / OpenAi按 kind 构造对应客户端Anthropic优先使用显式传入的AuthSource否则走AnthropicClient::from_env()XaiOpenAiCompatClient::from_env(OpenAiCompatConfig::xai())OpenAi先检查OLLAMA_HOST环境变量——一旦设置无条件路由到本地 Ollama免 API Key否则按模型元数据选择 DashScope 配置还是 OpenAI 配置。其中有一个容易被忽略的细节DashScope 的 qwen-* 系列模型返回的也是ProviderKind::OpenAi因为它们讲 OpenAI 线格式但它们必须走读取DASHSCOPE_API_KEY、指向dashscope.aliyuncs.com的 DashScope 配置。路由代码通过metadata_for_model返回的auth_env DASHSCOPE_API_KEY来区分let config match providers::metadata_for_model(resolved_model) { Some(meta) if meta.auth_env DASHSCOPE_API_KEY OpenAiCompatConfig::dashscope(), _ OpenAiCompatConfig::openai(), };detect_provider_kind的优先级模型名到 Provider 的判定在 providers/mod.rs 中遵循严格优先级OLLAMA_HOST优先只要设置所有模型一律路由到本地 OpenAI 兼容端点本地 Ollama 无需 API Key且忽略 DashScope/OpenAI 的环境变量分发模型名元数据claude*/anthropic/→ Anthropicgrok*→ Xaiopenai/、gpt-*→ OpenAIqwen/、qwen-*→ DashScopeOpenAI 协议kimi/、kimi-*→ DashScope本地模型启发式当OPENAI_BASE_URL已设置且模型名包含:或.如llama3.2、qwen2.5-coder:7b优先走 OpenAI 兼容端点避免被环境里残留的 Anthropic 凭据“抢走”凭据嗅探兜底依次检查ANTHROPIC_API_KEY/保存的 OAuth、OPENAI_API_KEY、XAI_API_KEY、OPENAI_BASE_URL最后兜底为 Anthropic。模型别名注册表MODEL_REGISTRYproviders/mod.rs内置了常用别名resolve_model_alias会做 trim 小写匹配别名解析结果opusclaude-opus-4-7sonnetclaude-sonnet-4-6haikuclaude-haiku-4-5-20251213grok/grok-3grok-3grok-mini/grok-3-minigrok-3-minigrok-2grok-2kimikimi-k2.5crate 内测试resolves_existing_and_grok_aliases与resolves_grok_aliases分别断言了这些映射见 client.rs 与 providers/mod.rs。三、ProviderMetadata 与环境变量对统一的认证约定AGENTS.md 明确约定Provider 配置遵循*_API_KEY/*_BASE_URL的环境变量对并记录在ProviderMetadata中providers/mod.rspub struct ProviderMetadata { pub provider: ProviderKind, pub auth_env: static str, pub base_url_env: static str, pub default_base_url: static str, }各 Provider 的完整环境变量对照如下来自MODEL_REGISTRY与metadata_for_model分支Provider认证环境变量Base URL 环境变量默认 Base URLAnthropicANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKENANTHROPIC_BASE_URLhttps://api.anthropic.comxAIXAI_API_KEYXAI_BASE_URLhttps://api.x.ai/v1OpenAIOPENAI_API_KEYOPENAI_BASE_URLhttps://api.openai.com/v1DashScopeDASHSCOPE_API_KEYDASHSCOPE_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1OllamaOLLAMA_HOST免 KeyOLLAMA_HOSThttp://127.0.0.1:11434/v1两个值得注意的实操细节Ollama 免认证OpenAiCompatClient::from_ollama_env用占位符ollama作为 API Key仅用于填充 Authorization 头见 openai_compat.rs.env 文件支持read_env_non_empty在真实环境变量缺失时会回退到工作目录.env文件读取parse_dotenv/load_dotenv_file/dotenv_value见 providers/mod.rs支持KEYVALUE、引号剥除与export前缀。四、AnthropicClient双认证、指数退避与 SSE 流AnthropicClientproviders/anthropic.rs在 crate 根被重导出为ApiClientlib.rs。认证模型API Key 与 OAuth 双轨AuthSource枚举providers/anthropic.rs描述四种认证形态pub enum AuthSource { None, ApiKey(String), BearerToken(String), ApiKeyAndBearer { api_key: String, bearer_token: String }, }同时设置ANTHROPIC_API_KEY与ANTHROPIC_AUTH_TOKEN时会同时发送x-api-key头与Bearer头OAuthTokenSetaccess_token / refresh_token / expires_at / scopes用于已保存的 OAuth 凭据resolve_saved_oauth_token会在 token 过期时自动用 refresh_token 换取新 token 并回写providers/anthropic.rs一个实用的错误提示若把sk-ant-*开头的 Key 误放到ANTHROPIC_AUTH_TOKEN服务端会返回 401enrich_bearer_auth_error会追加“请移到ANTHROPIC_API_KEY”的修复提示providers/anthropic.rs。重试策略默认max_retries 8、initial_backoff 1s、max_backoff 128sproviders/anthropic.rs。重试条件包括可重试 HTTP 状态码408/409/429/500/502/503/504、网络错误以及带有“no parseable body”“connection reset”等网关特征短语的 400providers/anthropic.rs。退避采用指数增长叠加 splitmix64 随机抖动抖动来源混合纳秒时钟与进程内单调计数器用于分散多客户端并发重试providers/anthropic.rs。Preflight本地字节估算 count_tokens 精算preflight_message_requestproviders/mod.rs用serde_json::to_vec的字节长度除以 4 估算输入 tokenAnthropicClient侧还会进一步调用POST /v1/messages/count_tokens精算providers/anthropic.rs任一环节检测到超出上下文窗口即返回ApiError::ContextWindowExceeded。流式接口MessageStream::next_event()通过SseParser增量消费响应分块产出StreamEvent在MessageStop时把最后一次usage记入 prompt cacheproviders/anthropic.rs。五、OpenAiCompatClient兼容翻译层与模型怪癖处理OpenAiCompatClient是工作量最大的部分被 AGENTS.md 称为“Heavy translation layer”。配置预设OpenAiCompatConfigopenai_compat.rs除 provider 名称、认证/Base URL 环境变量外还携带请求体大小上限预设provider_name请求体上限默认 Base URLxai()xAI50MB52,428,800 Bhttps://api.x.ai/v1openai()OpenAI100MB104,857,600 Bhttps://api.openai.com/v1dashscope()DashScope6MB6,291,456 Bdogfood 实测https://dashscope.aliyuncs.com/compatible-mode/v1OLLAMA_CONFIGOllama100MBhttp://127.0.0.1:11434/v1send_raw_request在发送前会执行check_request_body_size_for_base_url做预检超限即拒绝。核心翻译函数lib.rs公开导出了以下可独立复用的翻译函数lib.rsbuild_chat_completion_request把MessageRequest编译为 Chat Completions JSONtranslate_message单条消息翻译sanitize_tool_message_pairing/flatten_tool_result_content工具消息配对与 tool result 内容拍平estimate_request_body_size/check_request_body_size请求体估算与护栏is_reasoning_model推理模型谓词model_rejects_is_error_field/model_requires_reasoning_content_in_history按模型怪癖决定是否保留is_error字段、是否把历史 Thinking 块回显为reasoning_content典型如 DeepSeek V4。流式侧由StreamState维护状态机openai_compat.rs把 OpenAI 分块中的reasoning_content/reasoning/thinking.content三种字段统一归一为Thinking内容块把工具调用增量聚合成完整的ToolUse块并在流结束时补发ContentBlockStop与MessageDelta含 stop_reason——这意味着上层消费方无需关心上游是 Anthropic 还是 OpenAI 方言。六、能力矩阵与诊断报告ProviderCapabilityReportproviders/mod.rs按 Provider 声明能力用ProviderFeatureSupportSupported / Unsupported / PassthroughAsTool三态表达。测试provider_capability_matrix_snapshots_openai_compat_differencesproviders/mod.rs固化了关键差异快照Anthropic支持 prompt cache、流式不支持 streaming_usage、custom_parameters、reasoning_effortxAIgrok-3OpenAI 协议不支持 streaming_usage 与 reasoning_effort固定采样推理模型OpenAI支持 streaming_usage、custom_parameters、reasoning_effortDeepSeek V4 额外支持 reasoning_content_history所有 Provider 的web_search/web_fetch均标为PassthroughAsTool——即作为普通函数工具透传而非 Provider 原生 Web 能力。provider_diagnostics_for_requestproviders/mod.rs会针对具体请求产出带code/severity/action的诊断项例如reasoning_effort_unsupportedWarning请求携带reasoning_effort但 Provider 不支持建议移除或改路由到openai/o4-minireasoning_model_fixed_samplingInfo推理模型将省略 temperature/top_p/frequency_penalty/presence_penalty 等调参字段deepseek_v4_reasoning_historyInfoDeepSeek V4 要求把助手 Thinking 历史回显为reasoning_contentweb_search_passthrough_tool/web_fetch_passthrough_toolInfo提示 web 工具以普通函数工具暴露。七、Provider 无关的线类型与 token 管理types.rs定义了整套 Provider 无关的数据结构types.rsMessageRequest模型、max_tokens、消息、system、工具、stream标志以及可选的 OpenAI 调参字段temperature、top_p、frequency_penalty、presence_penalty、stop、reasoning_effort与extra_body自定义扩展参数字典用于web_search_options、parallel_tool_calls等网关特性核心协议键受保护不可覆盖InputContentBlockText / Thinking含 signature/ ToolUse / ToolResultToolChoiceAuto / Any / Tool{name}Usageinput / output / cache_creation / cache_read 四类 token并可通过estimated_cost_usd(model)基于 runtime 定价表估算美元成本types.rsStreamEventMessageStart / MessageDelta / ContentBlockStart / ContentBlockDelta / ContentBlockStop / MessageStop 六类事件。max_tokens_for_model采用启发式opus 系默认 32,000其余 64,000若命中model_token_limit注册表providers/mod.rs则取两者较小值。注册表覆盖Claude Opus 4.x输出 32K/上下文 200K、Sonnet 4.6 与 Haiku 4.5输出 64K/200K、Grok-3 系列64K/131K、GPT-4.1 系列32,768/1,047,576、GPT-5.4 系列128K/1M 或 400K、Kimi K2.5/K1.516,384/256K、qwen-max/qwen-plus8,192/131K。max_tokens_for_model_with_override允许插件显式覆盖。八、HTTP 客户端、代理与超时http_client.rs构建带统一 user-agentclawd-rust-tools/0.1的 reqwest 客户端ProxyConfighttp_client.rs读取HTTP_PROXY/http_proxy、HTTPS_PROXY/https_proxy、NO_PROXY/no_proxy大写优先于小写、空串视为未设置也支持通过from_proxy_url用单一proxy_url同时覆盖 HTTP 与 HTTPSTimeoutConfighttp_client.rsCLAW_API_CONNECT_TIMEOUT默认 30s与CLAW_API_REQUEST_TIMEOUT默认 300s超时错误被标记为可重试交由既有指数退避处理。九、Prompt CacheAnthropic 专属的缓存记账prompt_cache.rs提供仅针对 Anthropic 的PromptCache默认配置completion TTL 30 秒、prompt TTL 5 分钟、cache_break_min_drop2000 tokenprompt_cache.rs以会话为单位落盘session-state.json、stats.json、completions/request_hash.json通过 FNV 哈希指纹请求命中时直接返回缓存的MessageResponse响应侧记录cache_creation_input_tokens/cache_read_input_tokens并产出CacheBreakEventunexpected / reason / token_drop用于诊断缓存失效prompt_cache.rs。在ProviderClient层面with_prompt_cache/prompt_cache_stats/take_last_prompt_cache_record仅对 Anthropic 变体生效client.rs。十、模块约定与测试纪律AGENTS.md 的 CONVENTIONS 与 TESTS 小节是本 crate 的工程契约模块默认私有lib.rs的pub use列表是唯一公开 API 面lib.rs 已逐一验证纯构造函数标注#[must_use]从源码可见with_base_url、with_retry_policy、with_prompt_cache等均遵循分发走ProviderClient枚举而非 trait 对象Providertrait 被 dead-code 允许叶子文件按需允许#![allow(clippy::cast_possible_truncation)]流统一收敛到MessageStreamnext_event()产出StreamEventclient.rs 中MessageStream枚举统一了 Anthropic 与 OpenAI-compat 两种流。测试层面tests/下四个集成测试文件分工明确client_integration核心客户端行为、openai_compat_integrationOpenAI 兼容翻译路径、provider_client_integrationProviderClient分发、proxy_integration代理配置。一个重要的并发纪律是所有触碰环境变量的测试必须通过共享的env_lock()互斥锁串行化如 client.rs 所示否则并行测试会互相观察到对方尚未还原的环境变量导致偶发失败测试还普遍使用EnvVarGuard快照-还原守卫即使断言 panic 也能保证进程环境不被污染。benches/request_building.rs是工作区唯一的 Criterion 基准测试聚焦热点翻译函数该文件整体豁免严格 lint。结语apicrate 以“枚举门面 双线协议 元数据驱动路由”的方式把五家 Provider 收敛为统一、可诊断、可测试的调用面模型名路由优先级清晰环境变量约定统一请求体大小与上下文窗口有前置护栏推理模型怪癖有专门谓词处理认证错误与缓存失效均有可执行的诊断提示。对任何需要多 Provider 接入能力的 Rust 项目而言AGENTS.md 配合 client.rs、providers/mod.rs、providers/openai_compat.rs 等源码是一份现成的多 Provider 客户端架构参考。【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
