38+ Provider

接上你的 LLM

所有配置存在 ~/.makerclaw/config.json 的 model_list[] 数组里，
API Key 单独存放在 .security.yml，不混进主配置。

三处持久化文件

所有路径的默认值都在 pkg/env.go 与 pkg/config/envkeys.go 里。

config.json 主配置
~/.makerclaw/config.json
.security.yml 密钥
~/.makerclaw/.security.yml
.env 仅 dev 参考
.env.example 只用于本地开发（代码不强制读）

model_list[] 的真实字段

从 pkg/config/config.go:738 的 ModelConfig struct 原样提取。

{ "version": 6, "model_list": [ { // ── 必填三项 ────────────────── "model_name": "gpt-main", // 在其他字段里引用的别名（必须唯一） "provider": "openai", // 路由时选择的协议名 "model": "gpt-5.4", // provider 不填时按 "provider/model" 解析 // ── HTTP 类必填 ──────────────── "api_base": "https://api.openai.com/v1", "api_keys": ["sk-xxx"], // 数组：多 key 时自动轮询 failover // ── 可选：路由与容灾 ────────── "fallbacks": ["claude-fallback"], // 主模型失败时按 model_name 顺序降级 "proxy": "http://127.0.0.1:7890", "rpm": 60, "request_timeout": 60, // ── 可选：高级 ────────────── "thinking_level": "medium", // off / low / medium / high / xhigh / adaptive "max_tokens_field": "max_completion_tokens", "tool_schema_transform": "simple", "extra_body": { "stream": true }, "custom_headers":{ "X-Trace-Id": "req-001" }, "enabled": true, "user_agent": "my-makerclaw/1.0" } ], "agents": { "defaults": { "model_name": "gpt-main" // 默认走 model_name 引用，不是裸字符串 } } }

38+ Provider

全部从 pkg/providers/factory_provider.go:25 protocolMetaByName + pkg/providers/provider_catalog.go:31 attachedModelProviderMetaByName 提取。

国外主流（13）

openai HTTP
api.openai.com/v1
anthropic HTTP
api.anthropic.com/v1
anthropic-messages HTTP
api.anthropic.com/v1 (messages 端点)
gemini Native
generativelanguage.googleapis.com/v1beta
openrouter 聚合
openrouter.ai/api/v1
groq HTTP
api.groq.com/openai/v1
mistral HTTP
api.mistral.ai/v1
cerebras HTTP
api.cerebras.ai/v1
nvidia NIM
integrate.api.nvidia.com/v1
venice HTTP
api.venice.ai/api/v1
vivgrid HTTP
api.vivgrid.com/v1
novita HTTP
api.novita.ai/openai
longcat HTTP
api.longcat.chat/openai
avian HTTP
api.avian.io/v1

国产 / 区域（13）

zhipu HTTP
open.bigmodel.cn/api/paas/v4
moonshot HTTP
api.moonshot.cn/v1
deepseek HTTP
api.deepseek.com/v1
qwen HTTP
dashscope.aliyuncs.com/compatible-mode/v1
qwen-intl 国际
dashscope-intl.aliyuncs.com/...
qwen-us 美西
dashscope-us.aliyuncs.com/...
coding-plan / alibaba-coding 编程
coding-intl.dashscope.aliyuncs.com/v1
coding-plan-anthropic 兼容
coding-intl.dashscope.aliyuncs.com/apps/anthropic
volcengine HTTP
ark.cn-beijing.volces.com/api/v3
modelscope HTTP
api-inference.modelscope.cn/v1
mimo HTTP
api.xiaomimimo.com/v1
zai Z.AI
api.z.ai/api/coding/paas/v4
minimax HTTP
api.minimaxi.com/v1
shengsuanyun HTTP
router.shengsuanyun.com/api/v1

本地 & 自定义（5）

ollama 零 key
localhost:11434/v1
lmstudio 零 key
localhost:1234/v1
vllm 零 key
localhost:8000/v1
litellm 代理
localhost:4000/v1
任意 OpenAI-兼容 自填
填 api_base + api_keys

另外有 7 个附件型 provider（认证方式特殊，不走普通 API key）：
azure · bedrock · antigravity（OAuth）· claude-cli · codex-cli · github-copilot · elevenlabs（仅 ASR，不可作 chat 主模型）。
详见 pkg/providers/provider_catalog.go:31 attachedModelProviderMetaByName。

两套路由，分开配置

代码里 pkg/routing/route.go + pkg/config/config.go RoutingConfig，两套完全独立。

①

Agent 路由 —— 消息分给哪个 Agent

配置在 agents.dispatch.rules[]。when 字段只有 7 个，从 pkg/routing/route.go:151 dispatchView struct 原样提取：

{ "agents": { "list": [ { "id": "main", "default": true }, { "id": "support" } ], "dispatch": { "rules": [ { "name": "telegram vip in support group", "agent": "support", "when": { // 以下 7 个字段是合法全集： // channel account space chat topic sender mentioned "channel": "telegram", // 渠道名 "account": "default", // 账号 ID "space": "workspace:t001", // workspace / guild "chat": "group:-1001234567890", // direct:user / group:-100 / channel:c "topic": "topic:42", // 主题/线程 "sender": "12345", // 标准化发送者 "mentioned": true // 是否被 @ }, "session_dimensions": ["chat", "sender"] // 覆盖全局 session.dimensions } ] } } }

规则自上而下匹配，第一条命中即胜出。不存在 tokens_gt / has_tool / hash 等字段 —— 这些是文档里可能写的，但代码里没有。

②

Model 路由 —— 复杂查询自动切轻量模型

配置在 agents.defaults.routing，三字段从 pkg/config/config.go RoutingConfig struct 原样提取：

{ "model_list": [ { "model_name": "gpt-main", "provider": "openai", "model": "gpt-5.4", "api_keys": ["sk-main"] }, { "model_name": "flash-light", "provider": "gemini", "model": "gemini-2.0-flash-exp", "api_keys": ["sk-light"] } ], "agents": { "defaults": { "model_name": "gpt-main", "routing": { "enabled": true, // 关掉则全部走 model_name "light_model": "flash-light", // 必须是 model_list 里已存在的 model_name "threshold": 0.35 // 复杂度 [0,1]，≥ 阈值走主模型 } } } }

复杂度评估的内部信号（pkg/agent/instance.go）：消息长度、代码块数量、近期工具调用频次、对话深度、媒体附件。一次回合内只切一次，中途跨工具调用不切换。如 light_model 在启动时验证失败，整个路由被自动关闭。

API Key 安全存储

源码里 SecureStrings 类型 + SecureString 字段标记。让密钥不进 git 仓库。

方式 A · 内联
直接写到 model_list[].api_keys[]
方式 B · 分文件（推荐）
config.json 只写非敏感，密钥放 .security.yml
# ~/.makerclaw/config.json —— 主配置 { "model_list": [ { "model_name": "gpt-main", "provider": "openai", "model": "gpt-5.4" } // 注意：无 api_keys 字段 ], "agents": { "defaults": { "model_name": "gpt-main" } } } # ~/.makerclaw/.security.yml —— 单独存放密钥（建议 chmod 600） model_list: gpt-main: api_keys: - "sk-proj-your-actual-key-1" - "sk-proj-your-actual-key-2" # 多 key 自动轮询 failover

CLI 命令

主二进制 makerclaw，启动器 makerclaw-launcher。

# 验证配置 + 健康检查 makerclaw doctor # OAuth 类 provider 登录（antigravity / claude-cli / codex-cli） makerclaw auth login --provider anthropic makerclaw auth login --provider openai # 启动 Gateway（默认 127.0.0.1:18790，源自 pkg/config/defaults.go） makerclaw gateway # 同二进制多实例 / 远端访问时改 Gateway 主机 MAKERCLAW_GATEWAY_HOST=0.0.0.0 makerclaw gateway // 全接口监听 # 启动 WebUI 控制台（端口 18800，源自 web/README.md） makerclaw-launcher # 暴露到所有接口（Docker / VM 场景） makerclaw-launcher -public # 不自动打开浏览器（无头服务器） makerclaw-launcher -no-browser

接任意 OpenAI 兼容服务

没有列出的 provider？provider 填已有协议名 + api_base 自己指向新端点。

{ "model_list": [ { "model_name": "my-proxy", "provider": "openai", // 协议族名（决定 HTTP 格式） "model": "custom-model-v1", "api_base": "https://your-proxy.example.com/v1", "api_keys": ["sk-your-key"] } ] }

全局环境变量（5 个常量）

从 pkg/config/envkeys.go 提取，这是代码里全部 MAKERCLAW_* 开头的全局 env var。其余 MAKERCLAW_* 都来自 struct 的 env: tag，主要是 channels 子模块（MAKERCLAW_CHANNELS_*）。

运行时目录
MAKERCLAW_HOME
配置文件
MAKERCLAW_CONFIG
Gateway 主机
MAKERCLAW_GATEWAY_HOST
内置 Skills
MAKERCLAW_BUILTIN_SKILLS
主二进制路径
MAKERCLAW_BINARY

下一步

← 回到快速开始 返回概览