mirror of
https://github.com/sipeed/picoclaw.git
synced 2026-06-12 18:08:54 +00:00
BeaconCat
363861c917
Restructure all 6 README files (en, zh, ja, fr, pt-br, vi) from
~1200-1580 lines down to ~250 lines each. Long sections (Chat Apps,
Providers, Configuration, Docker, Spawn Tasks, Troubleshooting, Tools)
are extracted into dedicated docs under docs/{lang}/ subdirectories.
Changes:
- Split README content into 7 sub-documents per language (42 new files)
- Update News section with v0.2.3/v0.2.1/v0.2.0/20K milestones
- Add 3 new Features (MCP Support, Vision Pipeline, Smart Routing)
- Complete CLI reference (14 commands, was 7)
- Fix Go badge 1.21+ -> 1.25+ (matches go.mod)
- Add LoongArch to architecture badge
- Fix Install section: hardcoded v0.1.1 -> latest/download URL
- Add Termux GitHub links
- Fix currency symbol placement ($599 not 599$)
- Add missing channels (Feishu, Slack, IRC, OneBot, MaixCam, Pico)
- Add missing providers (Kimi, Minimax, Avian, Mistral, Longcat, ModelScope)
- Add missing security docs (allow_read/write_paths, allow_remote, symlink)
- Remove incorrect azure from Providers table (azure uses model_list only)
- Cross-verified all claims against source code
Co-authored-by: BeaconCat <BeaconCat@users.noreply.github.com>
429 lines
15 KiB
Markdown
429 lines
15 KiB
Markdown
# 🔌 提供商与模型配置
|
||
|
||
> 返回 [README](../../README.zh.md)
|
||
|
||
### 提供商 (Providers)
|
||
|
||
> [!NOTE]
|
||
> Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，任意渠道的音频消息都将在 Agent 层面自动转录为文字。
|
||
|
||
| 提供商 | 用途 | 获取 API Key |
|
||
| -------------------- | ---------------------------- | -------------------------------------------------------------------- |
|
||
| `gemini` | LLM (Gemini 直连) | [aistudio.google.com](https://aistudio.google.com) |
|
||
| `zhipu` | LLM (智谱直连) | [bigmodel.cn](https://bigmodel.cn) |
|
||
| `volcengine` | LLM (火山引擎直连) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||
| `openrouter` | LLM (推荐，可访问所有模型) | [openrouter.ai](https://openrouter.ai) |
|
||
| `anthropic` | LLM (Claude 直连) | [console.anthropic.com](https://console.anthropic.com) |
|
||
| `openai` | LLM (GPT 直连) | [platform.openai.com](https://platform.openai.com) |
|
||
| `deepseek` | LLM (DeepSeek 直连) | [platform.deepseek.com](https://platform.deepseek.com) |
|
||
| `qwen` | LLM (通义千问) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
|
||
| `groq` | LLM + **语音转录** (Whisper) | [console.groq.com](https://console.groq.com) |
|
||
| `cerebras` | LLM (Cerebras 直连) | [cerebras.ai](https://cerebras.ai) |
|
||
| `vivgrid` | LLM (Vivgrid 直连) | [vivgrid.com](https://vivgrid.com) |
|
||
| `moonshot` | LLM (Kimi/Moonshot 直连) | [platform.moonshot.cn](https://platform.moonshot.cn) |
|
||
| `minimax` | LLM (Minimax 直连) | [platform.minimaxi.com](https://platform.minimaxi.com) |
|
||
| `avian` | LLM (Avian 直连) | [avian.io](https://avian.io) |
|
||
| `mistral` | LLM (Mistral 直连) | [console.mistral.ai](https://console.mistral.ai) |
|
||
| `longcat` | LLM (Longcat 直连) | [longcat.ai](https://longcat.ai) |
|
||
| `modelscope` | LLM (ModelScope 直连) | [modelscope.cn](https://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 | [获取密钥](https://platform.openai.com) |
|
||
| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [获取密钥](https://console.anthropic.com) |
|
||
| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [获取密钥](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
|
||
| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [获取密钥](https://platform.deepseek.com) |
|
||
| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [获取密钥](https://aistudio.google.com/api-keys) |
|
||
| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [获取密钥](https://console.groq.com) |
|
||
| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [获取密钥](https://platform.moonshot.cn) |
|
||
| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [获取密钥](https://dashscope.console.aliyun.com) |
|
||
| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [获取密钥](https://build.nvidia.com) |
|
||
| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | 本地（无需密钥） |
|
||
| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [获取密钥](https://openrouter.ai/keys) |
|
||
| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | 你的 LiteLLM 代理密钥 |
|
||
| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | 本地 |
|
||
| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [获取密钥](https://cerebras.ai) |
|
||
| **火山引擎（Doubao）** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [获取密钥](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
|
||
| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |
|
||
| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [获取密钥](https://www.byteplus.com) |
|
||
| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [获取密钥](https://vivgrid.com) |
|
||
| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [获取密钥](https://longcat.chat/platform) |
|
||
| **ModelScope (魔搭)**| `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [获取 Token](https://modelscope.cn/my/tokens) |
|
||
| **Antigravity** | `antigravity/` | Google Cloud | 自定义 | 仅 OAuth |
|
||
| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |
|
||
|
||
#### 基础配置示例
|
||
|
||
```json
|
||
{
|
||
"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": "gpt-5.4"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 各厂商配置示例
|
||
|
||
**OpenAI**
|
||
|
||
```json
|
||
{
|
||
"model_name": "gpt-5.4",
|
||
"model": "openai/gpt-5.4",
|
||
"api_key": "sk-..."
|
||
}
|
||
```
|
||
|
||
**火山引擎（Doubao）**
|
||
|
||
```json
|
||
{
|
||
"model_name": "ark-code-latest",
|
||
"model": "volcengine/ark-code-latest",
|
||
"api_key": "sk-..."
|
||
}
|
||
```
|
||
|
||
**智谱 AI (GLM)**
|
||
|
||
```json
|
||
{
|
||
"model_name": "glm-4.7",
|
||
"model": "zhipu/glm-4.7",
|
||
"api_key": "your-key"
|
||
}
|
||
```
|
||
|
||
**DeepSeek**
|
||
|
||
```json
|
||
{
|
||
"model_name": "deepseek-chat",
|
||
"model": "deepseek/deepseek-chat",
|
||
"api_key": "sk-..."
|
||
}
|
||
```
|
||
|
||
**Anthropic (使用 OAuth)**
|
||
|
||
```json
|
||
{
|
||
"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 原生消息格式的自定义端点：
|
||
|
||
```json
|
||
{
|
||
"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 (本地)**
|
||
|
||
```json
|
||
{
|
||
"model_name": "llama3",
|
||
"model": "ollama/llama3"
|
||
}
|
||
```
|
||
|
||
**自定义代理/API**
|
||
|
||
```json
|
||
{
|
||
"model_name": "my-custom-model",
|
||
"model": "openai/custom-model",
|
||
"api_base": "https://my-proxy.com/v1",
|
||
"api_key": "sk-...",
|
||
"request_timeout": 300
|
||
}
|
||
```
|
||
|
||
**LiteLLM Proxy**
|
||
|
||
```json
|
||
{
|
||
"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 会自动在它们之间轮询：
|
||
|
||
```json
|
||
{
|
||
"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` 配置格式**已弃用**，但为向后兼容仍支持。
|
||
|
||
**旧配置（已弃用）：**
|
||
|
||
```json
|
||
{
|
||
"providers": {
|
||
"zhipu": {
|
||
"api_key": "your-key",
|
||
"api_base": "https://open.bigmodel.cn/api/paas/v4"
|
||
}
|
||
},
|
||
"agents": {
|
||
"defaults": {
|
||
"provider": "zhipu",
|
||
"model": "glm-4.7"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**新配置（推荐）：**
|
||
|
||
```json
|
||
{
|
||
"model_list": [
|
||
{
|
||
"model_name": "glm-4.7",
|
||
"model": "zhipu/glm-4.7",
|
||
"api_key": "your-key"
|
||
}
|
||
],
|
||
"agents": {
|
||
"defaults": {
|
||
"model": "glm-4.7"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
详细的迁移指南请参考 [docs/migration/model-list-migration.md](../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`）。
|
||
|
||
<details>
|
||
<summary><b>智谱 (Zhipu) 配置示例</b></summary>
|
||
|
||
**1. 获取 API key 和 base URL**
|
||
|
||
- 获取 [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
|
||
|
||
**2. 配置**
|
||
|
||
```json
|
||
{
|
||
"agents": {
|
||
"defaults": {
|
||
"workspace": "~/.picoclaw/workspace",
|
||
"model": "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. 运行**
|
||
|
||
```bash
|
||
picoclaw agent -m "你好"
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>完整配置示例</b></summary>
|
||
|
||
```json
|
||
{
|
||
"agents": {
|
||
"defaults": {
|
||
"model": "anthropic/claude-opus-4-5"
|
||
}
|
||
},
|
||
"session": {
|
||
"dm_scope": "per-channel-peer",
|
||
"backlog_limit": 20
|
||
},
|
||
"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
|
||
}
|
||
}
|
||
```
|
||
|
||
</details>
|
||
|
||
---
|
||
|
||
## 📝 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 等) |
|