picoclaw/docs/guides/providers.zh.md

🔌 提供商与模型配置

返回 README

提供商 (Providers)

Note

语音转录现在可以通过 voice.model_name 指定的多模态模型完成；如果未配置语音模型，Groq Whisper 仍可作为回退方案。

提供商	用途	获取 API Key
gemini	LLM (Gemini 直连)	aistudio.google.com
zhipu	LLM (智谱直连)	bigmodel.cn
volcengine	LLM (火山引擎直连)	volcengine.com
openrouter	LLM (推荐，可访问所有模型)	openrouter.ai
anthropic	LLM (Claude 直连)	console.anthropic.com
openai	LLM (GPT 直连)	platform.openai.com
venice	LLM (Venice AI 直连)	venice.ai
deepseek	LLM (DeepSeek 直连)	platform.deepseek.com
qwen	LLM (通义千问)	dashscope.console.aliyun.com
groq	LLM + 语音转录 (Whisper)	console.groq.com
cerebras	LLM (Cerebras 直连)	cerebras.ai
vivgrid	LLM (Vivgrid 直连)	vivgrid.com
moonshot	LLM (Kimi/Moonshot 直连)	platform.moonshot.cn
minimax	LLM (Minimax 直连)	platform.minimaxi.com
avian	LLM (Avian 直连)	avian.io
mistral	LLM (Mistral 直连)	console.mistral.ai
longcat	LLM (Longcat 直连)	longcat.ai
modelscope	LLM (ModelScope 直连)	modelscope.cn
mimo	LLM (小米 MiMo 直连)	platform.xiaomimimo.com

模型配置 (model_list)

新功能！ PicoClaw 现在优先推荐显式 provider + 原生 model 的配置方式，例如 "provider": "zhipu", "model": "glm-4.7"。如果未设置 provider，旧的单字段 provider/model 写法仍然兼容。

如果你想看 agent 分发和轻量模型路由的完整示例，请看 路由使用指南。

该设计同时支持多 Agent 场景，提供灵活的 Provider 选择：

• 不同 Agent 使用不同 Provider：每个 Agent 可以使用自己的 LLM provider
• 模型回退（Fallback）：配置主模型和备用模型，提高可靠性
• 负载均衡：在多个 API 端点之间分配请求
• 集中化配置：在一个地方管理所有 provider

📋 所有支持的厂商

厂商	provider 值	默认 API Base	协议	获取 API Key
OpenAI	openai	https://api.openai.com/v1	OpenAI	获取密钥
Venice AI	venice	https://api.venice.ai/api/v1	OpenAI	获取密钥
Anthropic	anthropic	https://api.anthropic.com/v1	Anthropic	获取密钥
智谱 AI (GLM)	zhipu	https://open.bigmodel.cn/api/paas/v4	OpenAI	获取密钥
DeepSeek	deepseek	https://api.deepseek.com/v1	OpenAI	获取密钥
Google Gemini	gemini	https://generativelanguage.googleapis.com/v1beta	Gemini	获取密钥
Groq	groq	https://api.groq.com/openai/v1	OpenAI	获取密钥
Moonshot	moonshot	https://api.moonshot.cn/v1	OpenAI	获取密钥
通义千问 (Qwen)	qwen	https://dashscope.aliyuncs.com/compatible-mode/v1	OpenAI	获取密钥
NVIDIA	nvidia	https://integrate.api.nvidia.com/v1	OpenAI	获取密钥
Ollama	ollama	http://localhost:11434/v1	OpenAI	本地（无需密钥）
LM Studio	lmstudio	http://localhost:1234/v1	OpenAI	可选（本地默认无需密钥）
OpenRouter	openrouter	https://openrouter.ai/api/v1	OpenAI	获取密钥
LiteLLM Proxy	litellm	http://localhost:4000/v1	OpenAI	你的 LiteLLM 代理密钥
VLLM	vllm	http://localhost:8000/v1	OpenAI	本地
Cerebras	cerebras	https://api.cerebras.ai/v1	OpenAI	获取密钥
火山引擎（Doubao）	volcengine	https://ark.cn-beijing.volces.com/api/v3	OpenAI	获取密钥
神算云	shengsuanyun	https://router.shengsuanyun.com/api/v1	OpenAI	-
BytePlus	byteplus	https://ark.ap-southeast.bytepluses.com/api/v3	OpenAI	获取密钥
Vivgrid	vivgrid	https://api.vivgrid.com/v1	OpenAI	获取密钥
LongCat	longcat	https://api.longcat.chat/openai	OpenAI	获取密钥
ModelScope (魔搭)	modelscope	https://api-inference.modelscope.cn/v1	OpenAI	获取 Token
小米 MiMo	mimo	https://api.xiaomimimo.com/v1	OpenAI	获取密钥
Antigravity	antigravity	Google Cloud	自定义	仅 OAuth
GitHub Copilot	github-copilot	localhost:4321	gRPC	-

基础配置示例

{
  "model_list": [
    {
      "model_name": "ark-code-latest",
      "provider": "volcengine",
      "model": "ark-code-latest",
      "api_keys": ["sk-your-api-key"]
    },
    {
      "model_name": "gpt-5.4",
      "provider": "openai",
      "model": "gpt-5.4",
      "api_keys": ["sk-your-openai-key"]
    },
    {
      "model_name": "claude-sonnet-4.6",
      "provider": "anthropic",
      "model": "claude-sonnet-4.6",
      "api_keys": ["sk-ant-your-key"]
    },
    {
      "model_name": "glm-4.7",
      "provider": "zhipu",
      "model": "glm-4.7",
      "api_keys": ["your-zhipu-key"]
    }
  ],
  "agents": {
    "defaults": {
      "model_name": "gpt-5.4"
    }
  }
}

model_list 条目字段

字段	类型	必填	说明
model_name	string	是	在 agent 配置中引用此模型的唯一名称
provider	string	否	推荐的 provider 标识。设置后，PicoClaw 会将 model 原样发送给该 provider
model	string	是	当设置 provider 时，这里填写 provider 原生模型 ID。若未设置 provider，仍兼容旧的 provider/model 写法
api_keys	string[]	是*	认证密钥。多个密钥可按请求轮换。本地 provider（Ollama、LM Studio、VLLM）不需要
api_base	string	否	覆盖默认的 API 端点 URL
proxy	string	否	此模型条目的 HTTP 代理 URL
user_agent	string	否	自定义 User-Agent 请求头（支持 OpenAI 兼容、Gemini、Anthropic 和 Azure provider）
request_timeout	int	否	请求超时时间（秒），默认值因 provider 而异
streaming.enabled	bool	否	是否允许此模型条目尝试 provider 流式请求，默认 false。它只表达模型/端点能力 opt-in，实际还需要当前 channel 的 settings.streaming.enabled 同时开启
max_tokens_field	string	否	覆盖请求体中 max tokens 的字段名（如 o1 模型使用 max_completion_tokens）
thinking_level	string	否	扩展思考级别：off、low、medium、high、xhigh 或 adaptive
extra_body	object	否	注入到每个请求体中的额外字段
custom_headers	object	否	注入到每个请求中的额外 HTTP 请求头（例如 {"X-Source":"coding-plan"}）。若键名与内置请求头同名，会覆盖内置值（如 Authorization、User-Agent、Content-Type、Accept）。
rpm	int	否	每分钟请求速率限制
fallbacks	string[]	否	自动故障转移的备用模型名称
enabled	bool	否	是否启用此模型条目（默认：true）

不需要流式时请省略 streaming 配置块。写 "streaming": {"enabled": false} 是可选的，手写或生成配置时都不需要。

provider / model 解析规则

PicoClaw 按下面的规则解析 provider 和最终发给上游的模型 ID：

• 如果设置了 provider，则直接使用 model。
• 如果未设置 provider，则把 model 中第一个 / 之前的字段当作 provider，第一个 / 之后的全部内容当作最终模型 ID。

示例：

配置	解析后的 Provider	实际发送的模型 ID
"provider": "openai", "model": "gpt-5.4"	openai	gpt-5.4
"model": "openai/gpt-5.4"	openai	gpt-5.4
"provider": "openrouter", "model": "openai/gpt-5.4"	openrouter	openai/gpt-5.4
"model": "openrouter/openai/gpt-5.4"	openrouter	openai/gpt-5.4

语音转录

你可以通过 voice.model_name 为语音转录指定一个专用模型。这样可以直接复用已经配置好的、支持音频输入的多模态 provider，而不必只依赖 Groq。

如果没有配置 voice.model_name，且存在 Groq API Key，PicoClaw 会继续回退到 Groq 转录。

{
  "model_list": [
    {
      "model_name": "voice-gemini",
      "provider": "gemini",
      "model": "gemini-2.5-flash",
      "api_keys": ["your-gemini-key"]
    }
  ],
  "voice": {
    "model_name": "voice-gemini",
    "echo_transcription": false
  },
  "providers": {
    "groq": {
      "api_key": "gsk_xxx"
    }
  }
}

各厂商配置示例

OpenAI

{
  "model_name": "gpt-5.4",
  "provider": "openai",
  "model": "gpt-5.4",
  "api_keys": ["sk-..."]
}

火山引擎（Doubao）

{
  "model_name": "ark-code-latest",
  "provider": "volcengine",
  "model": "ark-code-latest",
  "api_keys": ["sk-..."]
}

智谱 AI (GLM)

{
  "model_name": "glm-4.7",
  "provider": "zhipu",
  "model": "glm-4.7",
  "api_keys": ["your-key"]
}

DeepSeek

{
  "model_name": "deepseek-chat",
  "provider": "deepseek",
  "model": "deepseek-chat",
  "api_keys": ["sk-..."]
}

Anthropic (使用 OAuth)

{
  "model_name": "claude-sonnet-4.6",
  "provider": "anthropic",
  "model": "claude-sonnet-4.6",
  "auth_method": "oauth"
}

运行 picoclaw auth login --provider anthropic 来设置 OAuth 凭证。

Anthropic Messages API（原生格式）

用于直接访问 Anthropic API 或仅支持 Anthropic 原生消息格式的自定义端点：

{
  "model_name": "claude-opus-4-6",
  "provider": "anthropic-messages",
  "model": "claude-opus-4-6",
  "api_keys": ["sk-ant-your-key"],
  "api_base": "https://api.anthropic.com"
}

使用 anthropic-messages 协议的场景：

• 使用仅支持 Anthropic 原生 /v1/messages 端点的第三方代理（不支持 OpenAI 兼容的 /v1/chat/completions）
• 连接到 MiniMax、Synthetic 等需要 Anthropic 原生消息格式的服务
• 现有的 anthropic 协议返回 404 错误（说明端点不支持 OpenAI 兼容格式）

注意： anthropic 协议使用 OpenAI 兼容格式（/v1/chat/completions），而 anthropic-messages 使用 Anthropic 原生格式（/v1/messages）。请根据端点支持的格式选择。

Ollama (本地)

{
  "model_name": "llama3",
  "provider": "ollama",
  "model": "llama3"
}

LM Studio（本地）

{
  "model_name": "lmstudio-local",
  "provider": "lmstudio",
  "model": "openai/gpt-oss-20b"
}

api_base 默认是 http://localhost:1234/v1。除非你在 LM Studio 侧启用了认证，否则不需要配置 API Key。 显式设置 provider 后，PicoClaw 会把 openai/gpt-oss-20b 原样发送给 LM Studio。旧的兼容写法 "model": "lmstudio/openai/gpt-oss-20b" 在未设置 provider 时也会解析成相同的上游模型 ID。

自定义代理/API

{
  "model_name": "my-custom-model",
  "provider": "openai",
  "model": "custom-model",
  "api_base": "https://my-proxy.com/v1",
  "api_keys": ["sk-..."],
  "user_agent": "MyApp/1.0",
  "request_timeout": 300
}

LiteLLM Proxy

{
  "model_name": "lite-gpt4",
  "provider": "litellm",
  "model": "lite-gpt4",
  "api_base": "http://localhost:4000/v1",
  "api_keys": ["sk-..."]
}

显式设置 provider 后，PicoClaw 会将 model 原样发送。因此 "provider": "litellm", "model": "lite-gpt4" 会发送 lite-gpt4，而 "provider": "litellm", "model": "openai/gpt-4o" 会发送 openai/gpt-4o。旧的兼容写法 litellm/lite-gpt4 和 litellm/openai/gpt-4o 在未设置 provider 时也会得到相同结果。

负载均衡

为同一个模型名称配置多个端点——PicoClaw 会自动在它们之间轮询：

{
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "provider": "openai",
      "model": "gpt-5.4",
      "api_base": "https://api1.example.com/v1",
      "api_keys": ["sk-key1"]
    },
    {
      "model_name": "gpt-5.4",
      "provider": "openai",
      "model": "gpt-5.4",
      "api_base": "https://api2.example.com/v1",
      "api_keys": ["sk-key2"]
    }
  ]
}

自动模型失败切换（Cascade）

当你在 Agent 的模型设置里配置 primary + fallbacks 时，PicoClaw 已经支持自动失败切换。 运行时 fallback 链会在可重试错误时切到下一个候选（例如 HTTP 429、配额/限流错误、超时错误）。 同时会对每个候选应用 cooldown，避免对刚失败的目标立即重试。

{
  "model_list": [
    {
      "model_name": "qwen-main",
      "provider": "openai",
      "model": "qwen3.5:cloud",
      "api_base": "https://api.example.com/v1",
      "api_keys": ["sk-main"]
    },
    {
      "model_name": "deepseek-backup",
      "provider": "deepseek",
      "model": "deepseek-chat",
      "api_keys": ["sk-backup-1"]
    },
    {
      "model_name": "gemini-backup",
      "provider": "gemini",
      "model": "gemini-2.5-flash",
      "api_keys": ["sk-backup-2"]
    }
  ],
  "agents": {
    "defaults": {
      "model_name": "qwen-main",
      "model_fallbacks": ["deepseek-backup", "gemini-backup"]
    }
  }
}

如果你在同一模型上启用了 key 级失败切换，PicoClaw 会先在该模型的多 key 候选间切换，再继续切到跨模型备选。

从旧的 providers 配置迁移

旧的 providers 配置格式已弃用，V2 中已移除。现有 V0/V1 配置会自动迁移。

旧配置（已弃用）：

{
  "providers": {
    "zhipu": {
      "api_key": "your-key",
      "api_base": "https://open.bigmodel.cn/api/paas/v4"
    }
  },
  "agents": {
    "defaults": {
      "provider": "zhipu",
      "model": "glm-4.7"
    }
  }
}

新配置（推荐）：

{
  "version": 3,
  "model_list": [
    {
      "model_name": "glm-4.7",
      "provider": "zhipu",
      "model": "glm-4.7",
      "api_keys": ["your-key"]
    }
  ],
  "agents": {
    "defaults": {
      "model_name": "glm-4.7"
    }
  }
}

详细的迁移指南请参考 docs/migration/model-list-migration.md。

Provider 架构

PicoClaw 按协议族路由 Provider：

• OpenAI 兼容协议：OpenRouter、OpenAI 兼容网关、Groq、智谱、vLLM 风格端点。
• Gemini 原生协议：Google Gemini 通过原生 models/*:generateContent 和 models/*:streamGenerateContent 端点接入。
• Anthropic 协议：Claude 原生 API 行为。
• Codex/OAuth 路径：OpenAI OAuth/Token 认证路由。

这使得运行时保持轻量，同时让新的 OpenAI 兼容后端基本只需配置操作（api_base + api_keys）。

智谱 (Zhipu) 配置示例

1. 获取 API key 和 base URL

• 获取 API key

2. 配置

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "glm-4.7",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "providers": {
    "zhipu": {
      "api_key": "Your API Key",
      "api_base": "https://open.bigmodel.cn/api/paas/v4"
    }
  }
}

3. 运行

picoclaw agent -m "你好"

完整配置示例

{
  "agents": {
    "defaults": {
      "model_name": "claude-opus-4-5"
    }
  },
  "session": {
    "dm_scope": "per-channel-peer"
  },
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-xxx"
    },
    "groq": {
      "api_key": "gsk_xxx"
    }
  },
  "voice": {
    "model_name": "voice-gemini",
    "echo_transcription": false
  },
  "channel_list": {
    "telegram": {
      "enabled": true,
      "type": "telegram",
      "token": "123456:ABC...",
      "allow_from": ["123456789"]
    },
    "discord": {
      "enabled": true,
      "type": "discord",
      "token": "",
      "allow_from": [""]
    },
    "whatsapp": {
      "enabled": false,
      "type": "whatsapp",
      "bridge_url": "ws://localhost:3001",
      "use_native": false,
      "session_store_path": "",
      "allow_from": []
    },
    "feishu": {
      "enabled": false,
      "type": "feishu",
      "app_id": "cli_xxx",
      "app_secret": "xxx",
      "encrypt_key": "",
      "verification_token": "",
      "allow_from": []
    },
    "qq": {
      "enabled": false,
      "type": "qq",
      "app_id": "",
      "app_secret": "",
      "allow_from": []
    }
  },
  "tools": {
    "web": {
      "brave": {
        "enabled": false,
        "api_key": "BSA...",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      },
      "perplexity": {
        "enabled": false,
        "api_key": "",
        "max_results": 5
      },
      "searxng": {
        "enabled": false,
        "base_url": "http://localhost:8888",
        "max_results": 5
      }
    },
    "cron": {
      "exec_timeout_minutes": 5
    }
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

---

📝 API Key 对比

服务	价格	适用场景
OpenRouter	免费: 200K tokens/月	多模型聚合 (Claude, GPT-4 等)
火山引擎 CodingPlan	¥9.9/首月	最适合国内用户，多种 SOTA 模型（豆包、DeepSeek 等）
智谱 (Zhipu)	免费: 200K tokens/月	适合中国用户
Brave Search	$5/1000 次查询	网络搜索功能
SearXNG	免费（自建）	隐私优先的元搜索引擎（70+ 搜索引擎）
Groq	免费额度可用	极速推理 (Llama, Mixtral)
Cerebras	免费额度可用	极速推理 (Llama, Qwen 等)
LongCat	免费: 最多 5M tokens/天	极速推理
ModelScope (魔搭)	免费: 2000 次请求/天	推理 (Qwen, GLM, DeepSeek 等)