picoclaw/docs/zh/providers.md

🔌 提供商与模型配置

返回 README

提供商 (Providers)

Note

Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，任意渠道的音频消息都将在 Agent 层面自动转录为文字。

提供商	用途	获取 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
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

模型配置 (model_list)

新功能！ PicoClaw 现在采用以模型为中心的配置方式。只需使用 厂商/模型 格式（如 zhipu/glm-4.7）即可添加新的 provider——无需修改任何代码！

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

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

📋 所有支持的厂商

厂商	model 前缀	默认 API Base	协议	获取 API Key
OpenAI	openai/	https://api.openai.com/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	OpenAI	获取密钥
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	本地（无需密钥）
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
Antigravity	antigravity/	Google Cloud	自定义	仅 OAuth
GitHub Copilot	github-copilot/	localhost:4321	gRPC	-

基础配置示例

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

各厂商配置示例

OpenAI

{
  "model_name": "gpt-5.4",
  "model": "openai/gpt-5.4",
  "api_key": "sk-..."
}

火山引擎（Doubao）

{
  "model_name": "ark-code-latest",
  "model": "volcengine/ark-code-latest",
  "api_key": "sk-..."
}

智谱 AI (GLM)

{
  "model_name": "glm-4.7",
  "model": "zhipu/glm-4.7",
  "api_key": "your-key"
}

DeepSeek

{
  "model_name": "deepseek-chat",
  "model": "deepseek/deepseek-chat",
  "api_key": "sk-..."
}

Anthropic (使用 OAuth)

{
  "model_name": "claude-sonnet-4.6",
  "model": "anthropic/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",
  "model": "anthropic-messages/claude-opus-4-6",
  "api_key": "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",
  "model": "ollama/llama3"
}

自定义代理/API

{
  "model_name": "my-custom-model",
  "model": "openai/custom-model",
  "api_base": "https://my-proxy.com/v1",
  "api_key": "sk-...",
  "request_timeout": 300
}

LiteLLM Proxy

{
  "model_name": "lite-gpt4",
  "model": "litellm/lite-gpt4",
  "api_base": "http://localhost:4000/v1",
  "api_key": "sk-..."
}

PicoClaw 在发送请求前仅去除外层 litellm/ 前缀，因此 litellm/lite-gpt4 会发送 lite-gpt4，而 litellm/openai/gpt-4o 会发送 openai/gpt-4o。

负载均衡

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

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

从旧的 providers 配置迁移

旧的 providers 配置格式已弃用，但为向后兼容仍支持。

旧配置（已弃用）：

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

新配置（推荐）：

{
  "model_list": [
    {
      "model_name": "glm-4.7",
      "model": "zhipu/glm-4.7",
      "api_key": "your-key"
    }
  ],
  "agents": {
    "defaults": {
      "model_name": "glm-4.7"
    }
  }
}

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

Provider 架构

PicoClaw 按协议族路由 Provider：

• OpenAI 兼容协议：OpenRouter、OpenAI 兼容网关、Groq、智谱、vLLM 风格端点。
• Anthropic 协议：Claude 原生 API 行为。
• Codex/OAuth 路径：OpenAI OAuth/Token 认证路由。

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

智谱 (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": "anthropic/claude-opus-4-5"
    }
  },
  "session": {
    "dm_scope": "per-channel-peer"
  },
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-xxx"
    },
    "groq": {
      "api_key": "gsk_xxx"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "123456:ABC...",
      "allow_from": ["123456789"]
    },
    "discord": {
      "enabled": true,
      "token": "",
      "allow_from": [""]
    },
    "whatsapp": {
      "enabled": false,
      "bridge_url": "ws://localhost:3001",
      "use_native": false,
      "session_store_path": "",
      "allow_from": []
    },
    "feishu": {
      "enabled": false,
      "app_id": "cli_xxx",
      "app_secret": "xxx",
      "encrypt_key": "",
      "verification_token": "",
      "allow_from": []
    },
    "qq": {
      "enabled": false,
      "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 等)