1 line
146 KiB
JSON
1 line
146 KiB
JSON
{"repo": "1024xengineer/clawpet", "files": {"docs/ja/providers.md": {"0f133473014e443de79a1ee7f5121f2dbc4bb740": {"t": 1785674177.29764, "n": 15938, "h": "4d4879a402eaaa51", "c": "# 🔌 プロバイダーとモデル設定\n\n> [README](../../README.ja.md) に戻る\n\n### プロバイダー\n\n> [!NOTE]\n> Groq は Whisper による無料の音声文字起こしを提供しています。Groq を設定すると、任意のチャネルからの音声メッセージが Agent レベルで自動的にテキストに変換されます。\n\n| プロバイダー | 用途 | API Key の取得 |\n| -------------------- | ---------------------------- | -------------------------------------------------------------------- |\n| `gemini` | LLM (Gemini 直接接続) | [aistudio.google.com](https://aistudio.google.com) |\n| `zhipu` | LLM (Zhipu 直接接続) | [bigmodel.cn](https://bigmodel.cn) |\n| `volcengine` | LLM (Volcengine 直接接続) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |\n| `openrouter` | LLM (推奨、全モデルアクセス可) | [openrouter.ai](https://openrouter.ai) |\n| `anthropic` | LLM (Claude 直接接続) | [console.anthropic.com](https://console.anthropic.com) |\n| `openai` | LLM (GPT 直接接続) | [platform.openai.com](https://platform.openai.com) |\n| `deepseek` | LLM (DeepSeek 直接接続) | [platform.deepseek.com](https://platform.deepseek.com) |\n| `qwen` | LLM (Qwen 直接接続) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |\n| `groq` | LLM + **音声文字起こし** (Whisper) | [console.groq.com](https://console.groq.com) |\n| `cerebras` | LLM (Cerebras 直接接続) | [cerebras.ai](https://cerebras.ai) |\n| `vivgrid` | LLM (Vivgrid 直接接続) | [vivgrid.com](https://vivgrid.com) |\n| `moonshot` | LLM (Kimi/Moonshot 直接接続) | [platform.moonshot.cn](https://platform.moonshot.cn) |\n| `minimax` | LLM (Minimax 直接接続) | [platform.minimaxi.com](https://platform.minimaxi.com) |\n| `avian` | LLM (Avian 直接接続) | [avian.io](https://avian.io) |\n| `mistral` | LLM (Mistral 直接接続) | [console.mistral.ai](https://console.mistral.ai) |\n| `longcat` | LLM (Longcat 直接接続) | [longcat.ai](https://longcat.ai) |\n| `modelscope` | LLM (ModelScope 直接接続) | [modelscope.cn](https://modelscope.cn) |\n\n### モデル設定 (model_list)\n\n> **新機能！** PicoClaw は**モデル中心**の設定方式を採用しました。`ベンダー/モデル` 形式（例: `zhipu/glm-4.7`）を指定するだけで新しい provider を追加できます——**コード変更は一切不要です！**\n\nこの設計は**マルチ Agent シナリオ**もサポートし、柔軟な Provider 選択を提供します：\n\n- **Agent ごとに異なる Provider**: 各 Agent が独自の LLM provider を使用可能\n- **モデルフォールバック**: プライマリモデルとフォールバックモデルを設定し、信頼性を向上\n- **ロードバランシング**: 複数の API エンドポイント間でリクエストを分散\n- **一元管理**: すべての provider を一箇所で管理\n\n#### 📋 サポートされている全ベンダー\n\n| ベンダー | `model` プレフィックス | デフォルト API Base | プロトコル | API Key の取得 |\n| ------------------- | --------------------- | --------------------------------------------------- | ---------- | ----------------------------------------------------------------- |\n| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [キーを取得](https://platform.openai.com) |\n| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [キーを取得](https://console.anthropic.com) |\n| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [キーを取得](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |\n| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [キーを取得](https://platform.deepseek.com) |\n| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [キーを取得](https://aistudio.google.com/api-keys) |\n| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [キーを取得](https://console.groq.com) |\n| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [キーを取得](https://platform.moonshot.cn) |\n| **通義千問 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [キーを取得](https://dashscope.console.aliyun.com) |\n| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [キーを取得](https://build.nvidia.com) |\n| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | ローカル（キー不要） |\n| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [キーを取得](https://openrouter.ai/keys) |\n| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | LiteLLM プロキシキー |\n| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | ローカル |\n| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [キーを取得](https://cerebras.ai) |\n| **VolcEngine (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) |\n| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |\n| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [キーを取得](https://www.byteplus.com) |\n| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [キーを取得](https://vivgrid.com) |\n| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [キーを取得](https://longcat.chat/platform) |\n| **ModelScope (魔搭)**| `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [トークンを取得](https://modelscope.cn/my/tokens) |\n| **Antigravity** | `antigravity/` | Google Cloud | カスタム | OAuth のみ |\n| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |\n\n#### 基本設定\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-your-api-key\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-your-openai-key\"]\n },\n {\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"api_keys\": [\"sk-ant-your-key\"]\n },\n {\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-zhipu-key\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"gpt-5.4\"\n }\n }\n}\n```\n\n#### `model_list` エントリフィールド\n\n| フィールド | 型 | 必須 | 説明 |\n|-----------|------|------|------|\n| `model_name` | string | はい | agent 設定でこのモデルを参照するための一意の名前 |\n| `model` | string | はい | ベンダー/モデル識別子（例：`openai/gpt-5.4`、`azure/gpt-5.4`、`anthropic/claude-sonnet-4.6`） |\n| `api_keys` | string[] | はい* | 認証キー。複数キーでリクエストごとのローテーションが可能。ローカル provider（Ollama、LM Studio、VLLM）には不要 |\n| `api_base` | string | いいえ | デフォルトの API エンドポイント URL を上書き |\n| `proxy` | string | いいえ | このモデルエントリの HTTP プロキシ URL |\n| `user_agent` | string | いいえ | カスタム `User-Agent` リクエストヘッダー（OpenAI 互換、Anthropic、Azure provider で対応） |\n| `request_timeout` | int | いいえ | リクエストタイムアウト（秒）。デフォルト値は provider により異なる |\n| `max_tokens_field` | string | いいえ | リクエストボディの max tokens フィールド名を上書き（例：o1 モデルでは `max_completion_tokens`） |\n| `thinking_level` | string | いいえ | 拡張思考レベル：`off`、`low`、`medium`、`high`、`xhigh`、`adaptive` |\n| `extra_body` | object | いいえ | 各リクエストボディに注入する追加フィールド |\n| `rpm` | int | いいえ | 1 分あたりのリクエストレート制限 |\n| `fallbacks` | string[] | いいえ | 自動フェイルオーバーのフォールバックモデル名 |\n| `enabled` | bool | いいえ | このモデルエントリを有効にするかどうか（デフォルト：`true`） |\n\n#### ベンダー別設定例\n\n**OpenAI**\n\n```json\n{\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**VolcEngine (Doubao)**\n\n```json\n{\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**智谱 AI (GLM)**\n\n```json\n{\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-key\"]\n}\n```\n\n**LiteLLM Proxy**\n\n```json\n{\n \"model_name\": \"lite-gpt4\",\n \"model\": \"litellm/lite-gpt4\",\n \"api_base\": \"http://localhost:4000/v1\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**DeepSeek**\n\n```json\n{\n \"model_name\": \"deepseek-chat\",\n \"model\": \"deepseek/deepseek-chat\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**Anthropic (API キー使用)**\n\n```json\n{\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"api_keys\": [\"sk-ant-your-key\"]\n}\n```\n\n> `picoclaw auth login --provider anthropic` を実行して API トークンを設定してください。\n\n**Anthropic Messages API（ネイティブ形式）**\n\nAnthropic API への直接アクセスや、Anthropic のネイティブメッセージ形式のみをサポートするカスタムエンドポイント向け：\n\n```json\n{\n \"model_name\": \"claude-opus-4-6\",\n \"model\": \"anthropic-messages/claude-opus-4-6\",\n \"api_keys\": [\"sk-ant-your-key\"],\n \"api_base\": \"https://api.anthropic.com\"\n}\n```\n\n> `anthropic-messages` プロトコルを使用するケース：\n> - Anthropic のネイティブ `/v1/messages` エンドポイントのみをサポートするサードパーティプロキシを使用する場合（OpenAI 互換の `/v1/chat/completions` 非対応）\n> - MiniMax、Synthetic など Anthropic のネイティブメッセージ形式を必要とするサービスに接続する場合\n> - 既存の `anthropic` プロトコルが 404 エラーを返す場合（エンドポイントが OpenAI 互換形式をサポートしていないことを示す）\n>\n> **注意:** `anthropic` プロトコルは OpenAI 互換形式（`/v1/chat/completions`）を使用し、`anthropic-messages` は Anthropic のネイティブ形式（`/v1/messages`）を使用します。エンドポイントがサポートする形式に応じて選択してください。\n\n**Ollama (ローカル)**\n\n```json\n{\n \"model_name\": \"llama3\",\n \"model\": \"ollama/llama3\"\n}\n```\n\n**カスタムプロキシ/API**\n\n```json\n{\n \"model_name\": \"my-custom-model\",\n \"model\": \"openai/custom-model\",\n \"api_base\": \"https://my-proxy.com/v1\",\n \"api_keys\": [\"sk-...\"],\n \"user_agent\": \"MyApp/1.0\",\n \"request_timeout\": 300\n}\n```\n\n**LiteLLM Proxy**\n\n```json\n{\n \"model_name\": \"lite-gpt4\",\n \"model\": \"litellm/lite-gpt4\",\n \"api_base\": \"http://localhost:4000/v1\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\nPicoClaw はリクエスト送信前に外側の `litellm/` プレフィックスのみを除去するため、`litellm/lite-gpt4` は `lite-gpt4` を送信し、`litellm/openai/gpt-4o` は `openai/gpt-4o` を送信します。\n\n#### ロードバランシング\n\n同じモデル名に複数のエンドポイントを設定すると、PicoClaw が自動的にラウンドロビンで分散します：\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api1.example.com/v1\",\n \"api_keys\": [\"sk-key1\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api2.example.com/v1\",\n \"api_keys\": [\"sk-key2\"]\n }\n ]\n}\n```\n\n#### レガシー `providers` 設定からの移行\n\n旧 `providers` 設定形式は**非推奨**となり、V2 で削除されました。既存の V0/V1 設定は自動的に移行されます。\n\n**旧設定（非推奨）：**\n\n```json\n{\n \"providers\": {\n \"zhipu\": {\n \"api_key\": \"your-key\",\n \"api_base\": \"https://open.bigmodel.cn/api/paas/v4\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"provider\": \"zhipu\",\n \"model\": \"glm-4.7\"\n }\n }\n}\n```\n\n**新設定（推奨）：**\n\n```json\n{\n \"version\": 2,\n \"model_list\": [\n {\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-key\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"glm-4.7\"\n }\n }\n}\n```\n\n詳細な移行ガイドは [docs/migration/model-list-migration.md](../migration/model-list-migration.md) を参照してください。\n\n### Provider アーキテクチャ\n\nPicoClaw はプロトコルファミリーごとに Provider をルーティングします：\n\n- OpenAI 互換プロトコル：OpenRouter、OpenAI 互換ゲートウェイ、Groq、Zhipu、vLLM スタイルのエンドポイント。\n- Anthropic プロトコル：Claude ネイティブ API 動作。\n- Codex/OAuth パス：OpenAI OAuth/Token 認証ルート。\n\nこれによりランタイムを軽量に保ちつつ、新しい OpenAI 互換バックエンドの追加をほぼ設定操作（`api_base` + `api_keys`）のみで実現しています。\n\n<details>\n<summary><b>Zhipu 設定例</b></summary>\n\n**1. API key と base URL を取得**\n\n- [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) を取得\n\n**2. 設定**\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"workspace\": \"~/.picoclaw/workspace\",\n \"model_name\": \"glm-4.7\",\n \"max_tokens\": 8192,\n \"temperature\": 0.7,\n \"max_tool_iterations\": 20\n }\n },\n \"providers\": {\n \"zhipu\": {\n \"api_key\": \"Your API Key\",\n \"api_base\": \"https://open.bigmodel.cn/api/paas/v4\"\n }\n }\n}\n```\n\n**3. 実行**\n\n```bash\npicoclaw agent -m \"こんにちは\"\n```\n\n</details>\n\n<details>\n<summary><b>完全な設定例</b></summary>\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"anthropic/claude-opus-4-5\"\n }\n },\n \"session\": {\n \"dm_scope\": \"per-channel-peer\"\n },\n \"providers\": {\n \"openrouter\": {\n \"api_key\": \"sk-or-v1-xxx\"\n },\n \"groq\": {\n \"api_key\": \"gsk_xxx\"\n }\n },\n \"channels\": {\n \"telegram\": {\n \"enabled\": true,\n \"token\": \"123456:ABC...\",\n \"allow_from\": [\"123456789\"]\n },\n \"discord\": {\n \"enabled\": true,\n \"token\": \"\",\n \"allow_from\": [\"\"]\n },\n \"whatsapp\": {\n \"enabled\": false,\n \"bridge_url\": \"ws://localhost:3001\",\n \"use_native\": false,\n \"session_store_path\": \"\",\n \"allow_from\": []\n },\n \"feishu\": {\n \"enabled\": false,\n \"app_id\": \"cli_xxx\",\n \"app_secret\": \"xxx\",\n \"encrypt_key\": \"\",\n \"verification_token\": \"\",\n \"allow_from\": []\n },\n \"qq\": {\n \"enabled\": false,\n \"app_id\": \"\",\n \"app_secret\": \"\",\n \"allow_from\": []\n }\n },\n \"tools\": {\n \"web\": {\n \"brave\": {\n \"enabled\": false,\n \"api_key\": \"BSA...\",\n \"max_results\": 5\n },\n \"duckduckgo\": {\n \"enabled\": true,\n \"max_results\": 5\n },\n \"perplexity\": {\n \"enabled\": false,\n \"api_key\": \"\",\n \"max_results\": 5\n },\n \"searxng\": {\n \"enabled\": false,\n \"base_url\": \"http://localhost:8888\",\n \"max_results\": 5\n }\n },\n \"cron\": {\n \"exec_timeout_minutes\": 5\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"interval\": 30\n }\n}\n```\n\n</details>\n\n---\n\n## 📝 API Key 比較表\n\n| サービス | Pricing | ユースケース |\n| ---------------- | ------------------------ | ------------------------------------- |\n| **OpenRouter** | Free: 200K tokens/month | マルチモデル (Claude, GPT-4 など) |\n| **Volcengine CodingPlan** | ¥9.9/first month | 中国ユーザー向け、複数の SOTA モデル (Doubao, DeepSeek など) |\n| **Zhipu** | Free: 200K tokens/month | 中国ユーザー向け |\n| **Brave Search** | $5/1000 queries | Web 検索機能 |\n| **SearXNG** | Free (self-hosted) | プライバシー重視のメタ検索 (70+ engines) |\n| **Groq** | Free tier available | 高速推論 (Llama, Mixtral) |\n| **Cerebras** | Free tier available | 高速推論 (Llama, Qwen など) |\n| **LongCat** | Free: up to 5M tokens/day | 高速推論 |\n| **ModelScope** | Free: 2000 requests/day | 推論 (Qwen, GLM, DeepSeek など) |\n\n---\n\n<div align=\"center\">\n <img src=\"assets/logo.jpg\" alt=\"PicoClaw Meme\" width=\"512\">\n</div>\n"}}, "docs/vi/providers.md": {"0f133473014e443de79a1ee7f5121f2dbc4bb740": {"t": 1785674177.3636682, "n": 17193, "h": "aca42d6207866a88", "c": "# 🔌 Nhà Cung Cấp và Cấu Hình Mô Hình\n\n> Quay lại [README](../../README.vi.md)\n\n### Nhà Cung Cấp\n\n> [!NOTE]\n> Groq cung cấp chuyển đổi giọng nói miễn phí qua Whisper. Nếu được cấu hình, tin nhắn âm thanh từ bất kỳ kênh nào sẽ được tự động chuyển đổi ở cấp agent.\n\n| Provider | Purpose | Get API Key |\n| ------------ | --------------------------------------- | ------------------------------------------------------------ |\n| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) |\n| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](https://bigmodel.cn) |\n| `volcengine` | LLM(Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |\n| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) |\n| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) |\n| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) |\n| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) |\n| `qwen` | LLM (Qwen direct) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |\n| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) |\n| `cerebras` | LLM (Cerebras direct) | [cerebras.ai](https://cerebras.ai) |\n| `vivgrid` | LLM (Vivgrid direct) | [vivgrid.com](https://vivgrid.com) |\n| `moonshot` | LLM (Kimi/Moonshot direct) | [platform.moonshot.cn](https://platform.moonshot.cn) |\n| `minimax` | LLM (Minimax direct) | [platform.minimaxi.com](https://platform.minimaxi.com) |\n| `avian` | LLM (Avian direct) | [avian.io](https://avian.io) |\n| `mistral` | LLM (Mistral direct) | [console.mistral.ai](https://console.mistral.ai) |\n| `longcat` | LLM (Longcat direct) | [longcat.ai](https://longcat.ai) |\n| `modelscope` | LLM (ModelScope direct) | [modelscope.cn](https://modelscope.cn) |\n\n### Cấu Hình Mô Hình (model_list)\n\n> **Có gì mới?** PicoClaw hiện sử dụng cách tiếp cận cấu hình **tập trung vào mô hình**. Chỉ cần chỉ định định dạng `vendor/model` (ví dụ: `zhipu/glm-4.7`) để thêm provider mới — **không cần thay đổi code!**\n\nThiết kế này cũng cho phép **hỗ trợ đa agent** với lựa chọn provider linh hoạt:\n\n- **Agent khác nhau, provider khác nhau**: Mỗi agent có thể sử dụng provider LLM riêng\n- **Fallback mô hình**: Cấu hình mô hình chính và dự phòng cho khả năng phục hồi\n- **Cân bằng tải**: Phân phối yêu cầu qua nhiều endpoint\n- **Cấu hình tập trung**: Quản lý tất cả provider tại một nơi\n\n#### 📋 Tất Cả Vendor Được Hỗ Trợ\n\n| Vendor | `model` Prefix | Default API Base | Protocol | API Key |\n| ------------------- | ----------------- |-----------------------------------------------------| --------- | ---------------------------------------------------------------- |\n| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Get Key](https://platform.openai.com) |\n| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Get Key](https://console.anthropic.com) |\n| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |\n| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Get Key](https://platform.deepseek.com) |\n| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Get Key](https://aistudio.google.com/api-keys) |\n| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Get Key](https://console.groq.com) |\n| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Get Key](https://platform.moonshot.cn) |\n| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Get Key](https://dashscope.console.aliyun.com) |\n| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Get Key](https://build.nvidia.com) |\n| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (no key needed) |\n| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Get Key](https://openrouter.ai/keys) |\n| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | Your LiteLLM proxy key |\n| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local |\n| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Get Key](https://cerebras.ai) |\n| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |\n| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |\n| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [Get Key](https://www.byteplus.com) |\n| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [Get Key](https://vivgrid.com) |\n| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [Get Key](https://longcat.chat/platform) |\n| **ModelScope (魔搭)**| `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [Get Token](https://modelscope.cn/my/tokens) |\n| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth only |\n| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |\n\n#### Cấu Hình Cơ Bản\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-your-api-key\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-your-openai-key\"]\n },\n {\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"api_keys\": [\"sk-ant-your-key\"]\n },\n {\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-zhipu-key\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"gpt-5.4\"\n }\n }\n}\n```\n\n#### Các trường entry `model_list`\n\n| Trường | Kiểu | Bắt buộc | Mô tả |\n|--------|------|----------|------|\n| `model_name` | string | Có | Tên duy nhất để tham chiếu model này trong cấu hình agent |\n| `model` | string | Có | Định danh nhà cung cấp/model (ví dụ: `openai/gpt-5.4`, `azure/gpt-5.4`, `anthropic/claude-sonnet-4.6`) |\n| `api_keys` | string[] | Có* | Khóa API xác thực. Nhiều khóa cho phép xoay vòng theo yêu cầu. Không cần thiết cho provider nội bộ (Ollama, LM Studio, VLLM) |\n| `api_base` | string | Không | Ghi đè URL endpoint API mặc định |\n| `proxy` | string | Không | URL proxy HTTP cho entry model này |\n| `user_agent` | string | Không | Header `User-Agent` tùy chỉnh gửi với yêu cầu API (được hỗ trợ bởi provider OpenAI-compatible, Anthropic và Azure) |\n| `request_timeout` | int | Không | Timeout yêu cầu tính bằng giây (mặc định khác nhau tùy provider) |\n| `max_tokens_field` | string | Không | Ghi đè tên trường max tokens trong request body (ví dụ: `max_completion_tokens` cho model o1) |\n| `thinking_level` | string | Không | Mức độ tư duy mở rộng: `off`, `low`, `medium`, `high`, `xhigh` hoặc `adaptive` |\n| `extra_body` | object | Không | Các trường bổ sung để chèn vào mỗi request body |\n| `rpm` | int | Không | Giới hạn tốc độ yêu cầu mỗi phút |\n| `fallbacks` | string[] | Không | Tên model dự phòng cho failover tự động |\n| `enabled` | bool | Không | Kích hoạt hay vô hiệu hóa entry model này (mặc định: `true`) |\n\n#### Ví Dụ Theo Vendor\n\n**OpenAI**\n\n```json\n{\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**VolcEngine (Doubao)**\n\n```json\n{\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**智谱 AI (GLM)**\n\n```json\n{\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-key\"]\n}\n```\n\n**DeepSeek**\n\n```json\n{\n \"model_name\": \"deepseek-chat\",\n \"model\": \"deepseek/deepseek-chat\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**Anthropic (với API key)**\n\n```json\n{\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"api_keys\": [\"sk-ant-your-key\"]\n}\n```\n\n> Chạy `picoclaw auth login --provider anthropic` để dán API token.\n\n**Anthropic Messages API (định dạng native)**\n\nĐể truy cập trực tiếp API Anthropic hoặc endpoint tùy chỉnh chỉ hỗ trợ định dạng message native của Anthropic:\n\n```json\n{\n \"model_name\": \"claude-opus-4-6\",\n \"model\": \"anthropic-messages/claude-opus-4-6\",\n \"api_keys\": [\"sk-ant-your-key\"],\n \"api_base\": \"https://api.anthropic.com\"\n}\n```\n\n> Sử dụng giao thức `anthropic-messages` khi:\n> - Sử dụng proxy bên thứ ba chỉ hỗ trợ endpoint native `/v1/messages` của Anthropic (không tương thích OpenAI `/v1/chat/completions`)\n> - Kết nối đến dịch vụ như MiniMax, Synthetic yêu cầu định dạng message native của Anthropic\n> - Giao thức `anthropic` hiện tại trả về lỗi 404 (cho thấy endpoint không hỗ trợ định dạng tương thích OpenAI)\n>\n> **Lưu ý:** Giao thức `anthropic` sử dụng định dạng tương thích OpenAI (`/v1/chat/completions`), trong khi `anthropic-messages` sử dụng định dạng native của Anthropic (`/v1/messages`). Chọn dựa trên định dạng endpoint hỗ trợ.\n\n**Ollama (local)**\n\n```json\n{\n \"model_name\": \"llama3\",\n \"model\": \"ollama/llama3\"\n}\n```\n\n**Proxy/API Tùy Chỉnh**\n\n```json\n{\n \"model_name\": \"my-custom-model\",\n \"model\": \"openai/custom-model\",\n \"api_base\": \"https://my-proxy.com/v1\",\n \"api_keys\": [\"sk-...\"],\n \"user_agent\": \"MyApp/1.0\",\n \"request_timeout\": 300\n}\n```\n\n**LiteLLM Proxy**\n\n```json\n{\n \"model_name\": \"lite-gpt4\",\n \"model\": \"litellm/lite-gpt4\",\n \"api_base\": \"http://localhost:4000/v1\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\nPicoClaw chỉ loại bỏ tiền tố ngoài `litellm/` trước khi gửi yêu cầu, nên alias proxy như `litellm/lite-gpt4` gửi `lite-gpt4`, trong khi `litellm/openai/gpt-4o` gửi `openai/gpt-4o`.\n\n#### Cân Bằng Tải\n\nCấu hình nhiều endpoint cho cùng tên mô hình — PicoClaw sẽ tự động round-robin giữa chúng:\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api1.example.com/v1\",\n \"api_keys\": [\"sk-key1\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api2.example.com/v1\",\n \"api_keys\": [\"sk-key2\"]\n }\n ]\n}\n```\n\n#### Di Chuyển Từ Cấu Hình Legacy `providers`\n\nCấu hình `providers` cũ đã **bị deprecated** và đã được loại bỏ trong V2. Các cấu hình V0/V1 hiện có sẽ được tự động migrate.\n\n**Cấu hình cũ (ngừng hỗ trợ):**\n\n```json\n{\n \"providers\": {\n \"zhipu\": {\n \"api_key\": \"your-key\",\n \"api_base\": \"https://open.bigmodel.cn/api/paas/v4\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"provider\": \"zhipu\",\n \"model\": \"glm-4.7\"\n }\n }\n}\n```\n\n**Cấu hình mới (khuyến nghị):**\n\n```json\n{\n \"version\": 2,\n \"model_list\": [\n {\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-key\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"glm-4.7\"\n }\n }\n}\n```\n\nĐể xem hướng dẫn di chuyển chi tiết, xem [migration/model-list-migration.md](../migration/model-list-migration.md).\n\n### Kiến Trúc Provider\n\nPicoClaw định tuyến provider theo họ giao thức:\n\n- Giao thức tương thích OpenAI: OpenRouter, gateway tương thích OpenAI, Groq, Zhipu, và endpoint kiểu vLLM.\n- Giao thức Anthropic: Hành vi API native của Claude.\n- Đường dẫn Codex/OAuth: Tuyến xác thực OAuth/token của OpenAI.\n\nĐiều này giữ runtime nhẹ trong khi làm cho backend tương thích OpenAI mới chủ yếu là thao tác cấu hình (`api_base` + `api_keys`).\n\n<details>\n<summary><b>Zhipu</b></summary>\n\n**1. Lấy API key và URL base**\n\n* Lấy [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)\n\n**2. Cấu hình**\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"workspace\": \"~/.picoclaw/workspace\",\n \"model_name\": \"glm-4.7\",\n \"max_tokens\": 8192,\n \"temperature\": 0.7,\n \"max_tool_iterations\": 20\n }\n },\n \"providers\": {\n \"zhipu\": {\n \"api_key\": \"Your API Key\",\n \"api_base\": \"https://open.bigmodel.cn/api/paas/v4\"\n }\n }\n}\n```\n\n**3. Chạy**\n\n```bash\npicoclaw agent -m \"Hello\"\n```\n\n</details>\n\n<details>\n<summary><b>Ví dụ cấu hình đầy đủ</b></summary>\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"anthropic/claude-opus-4-5\"\n }\n },\n \"session\": {\n \"dm_scope\": \"per-channel-peer\"\n },\n \"providers\": {\n \"openrouter\": {\n \"api_key\": \"sk-or-v1-xxx\"\n },\n \"groq\": {\n \"api_key\": \"gsk_xxx\"\n }\n },\n \"channels\": {\n \"telegram\": {\n \"enabled\": true,\n \"token\": \"123456:ABC...\",\n \"allow_from\": [\"123456789\"]\n },\n \"discord\": {\n \"enabled\": true,\n \"token\": \"\",\n \"allow_from\": [\"\"]\n },\n \"whatsapp\": {\n \"enabled\": false,\n \"bridge_url\": \"ws://localhost:3001\",\n \"use_native\": false,\n \"session_store_path\": \"\",\n \"allow_from\": []\n },\n \"feishu\": {\n \"enabled\": false,\n \"app_id\": \"cli_xxx\",\n \"app_secret\": \"xxx\",\n \"encrypt_key\": \"\",\n \"verification_token\": \"\",\n \"allow_from\": []\n },\n \"qq\": {\n \"enabled\": false,\n \"app_id\": \"\",\n \"app_secret\": \"\",\n \"allow_from\": []\n }\n },\n \"tools\": {\n \"web\": {\n \"brave\": {\n \"enabled\": false,\n \"api_key\": \"BSA...\",\n \"max_results\": 5\n },\n \"duckduckgo\": {\n \"enabled\": true,\n \"max_results\": 5\n },\n \"perplexity\": {\n \"enabled\": false,\n \"api_key\": \"\",\n \"max_results\": 5\n },\n \"searxng\": {\n \"enabled\": false,\n \"base_url\": \"http://localhost:8888\",\n \"max_results\": 5\n }\n },\n \"cron\": {\n \"exec_timeout_minutes\": 5\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"interval\": 30\n }\n}\n```\n\n</details>\n\n---\n\n## 📝 So Sánh API Key\n\n| Service | Pricing | Use Case |\n| ---------------- | ------------------------ | ------------------------------------- |\n| **OpenRouter** | Free: 200K tokens/month | Multiple models (Claude, GPT-4, etc.) |\n| **Volcengine CodingPlan** | ¥9.9/first month | Best for Chinese users, multiple SOTA models (Doubao, DeepSeek, etc.) |\n| **Zhipu** | Free: 200K tokens/month | Suitable for Chinese users |\n| **Brave Search** | $5/1000 queries | Web search functionality |\n| **SearXNG** | Free (self-hosted) | Privacy-focused metasearch (70+ engines) |\n| **Groq** | Free tier available | Fast inference (Llama, Mixtral) |\n| **Cerebras** | Free tier available | Fast inference (Llama, Qwen, etc.) |\n| **LongCat** | Free: up to 5M tokens/day | Fast inference |\n| **ModelScope** | Free: 2000 requests/day | Inference (Qwen, GLM, DeepSeek, etc.) |\n\n---\n\n<div align=\"center\">\n <img src=\"assets/logo.jpg\" alt=\"PicoClaw Meme\" width=\"512\">\n</div>\n"}}, "docs/zh/providers.md": {"0f133473014e443de79a1ee7f5121f2dbc4bb740": {"t": 1785674177.6434138, "n": 17219, "h": "bff4114a038700a9", "c": "# 🔌 提供商与模型配置\n\n> 返回 [README](../../README.zh.md)\n\n### 提供商 (Providers)\n\n> [!NOTE]\n> 语音转录现在可以通过 `voice.model_name` 指定的多模态模型完成；如果未配置语音模型，Groq Whisper 仍可作为回退方案。\n\n| 提供商 | 用途 | 获取 API Key |\n| -------------------- | ---------------------------- | -------------------------------------------------------------------- |\n| `gemini` | LLM (Gemini 直连) | [aistudio.google.com](https://aistudio.google.com) |\n| `zhipu` | LLM (智谱直连) | [bigmodel.cn](https://bigmodel.cn) |\n| `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) |\n| `openrouter` | LLM (推荐，可访问所有模型) | [openrouter.ai](https://openrouter.ai) |\n| `anthropic` | LLM (Claude 直连) | [console.anthropic.com](https://console.anthropic.com) |\n| `openai` | LLM (GPT 直连) | [platform.openai.com](https://platform.openai.com) |\n| `venice` | LLM (Venice AI 直连) | [venice.ai](https://venice.ai) |\n| `deepseek` | LLM (DeepSeek 直连) | [platform.deepseek.com](https://platform.deepseek.com) |\n| `qwen` | LLM (通义千问) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |\n| `groq` | LLM + **语音转录** (Whisper) | [console.groq.com](https://console.groq.com) |\n| `cerebras` | LLM (Cerebras 直连) | [cerebras.ai](https://cerebras.ai) |\n| `vivgrid` | LLM (Vivgrid 直连) | [vivgrid.com](https://vivgrid.com) |\n| `moonshot` | LLM (Kimi/Moonshot 直连) | [platform.moonshot.cn](https://platform.moonshot.cn) |\n| `minimax` | LLM (Minimax 直连) | [platform.minimaxi.com](https://platform.minimaxi.com) |\n| `avian` | LLM (Avian 直连) | [avian.io](https://avian.io) |\n| `mistral` | LLM (Mistral 直连) | [console.mistral.ai](https://console.mistral.ai) |\n| `longcat` | LLM (Longcat 直连) | [longcat.ai](https://longcat.ai) |\n| `modelscope` | LLM (ModelScope 直连) | [modelscope.cn](https://modelscope.cn) |\n| `mimo` | LLM (小米 MiMo 直连) | [platform.xiaomimimo.com](https://platform.xiaomimimo.com) |\n\n### 模型配置 (model_list)\n\n> **新功能！** PicoClaw 现在采用**以模型为中心**的配置方式。只需使用 `厂商/模型` 格式（如 `zhipu/glm-4.7`）即可添加新的 provider——**无需修改任何代码！**\n\n该设计同时支持**多 Agent 场景**，提供灵活的 Provider 选择：\n\n- **不同 Agent 使用不同 Provider**：每个 Agent 可以使用自己的 LLM provider\n- **模型回退（Fallback）**：配置主模型和备用模型，提高可靠性\n- **负载均衡**：在多个 API 端点之间分配请求\n- **集中化配置**：在一个地方管理所有 provider\n\n#### 📋 所有支持的厂商\n\n| 厂商 | `model` 前缀 | 默认 API Base | 协议 | 获取 API Key |\n| ------------------- | ----------------- | --------------------------------------------------- | --------- | ----------------------------------------------------------------- |\n| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [获取密钥](https://platform.openai.com) |\n| **Venice AI** | `venice/` | `https://api.venice.ai/api/v1` | OpenAI | [获取密钥](https://venice.ai) |\n| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [获取密钥](https://console.anthropic.com) |\n| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [获取密钥](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |\n| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [获取密钥](https://platform.deepseek.com) |\n| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [获取密钥](https://aistudio.google.com/api-keys) |\n| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [获取密钥](https://console.groq.com) |\n| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [获取密钥](https://platform.moonshot.cn) |\n| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [获取密钥](https://dashscope.console.aliyun.com) |\n| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [获取密钥](https://build.nvidia.com) |\n| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | 本地（无需密钥） |\n| **LM Studio** | `lmstudio/` | `http://localhost:1234/v1` | OpenAI | 可选（本地默认无需密钥） |\n| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [获取密钥](https://openrouter.ai/keys) |\n| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | 你的 LiteLLM 代理密钥 |\n| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | 本地 |\n| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [获取密钥](https://cerebras.ai) |\n| **火山引擎（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) |\n| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |\n| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [获取密钥](https://www.byteplus.com) |\n| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [获取密钥](https://vivgrid.com) |\n| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [获取密钥](https://longcat.chat/platform) |\n| **ModelScope (魔搭)**| `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [获取 Token](https://modelscope.cn/my/tokens) |\n| **小米 MiMo** | `mimo/` | `https://api.xiaomimimo.com/v1` | OpenAI | [获取密钥](https://platform.xiaomimimo.com) |\n| **Antigravity** | `antigravity/` | Google Cloud | 自定义 | 仅 OAuth |\n| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |\n\n#### 基础配置示例\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-your-api-key\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-your-openai-key\"]\n },\n {\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"api_keys\": [\"sk-ant-your-key\"]\n },\n {\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-zhipu-key\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"gpt-5.4\"\n }\n }\n}\n```\n\n#### `model_list` 条目字段\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `model_name` | string | 是 | 在 agent 配置中引用此模型的唯一名称 |\n| `model` | string | 是 | 厂商/模型标识符（如 `openai/gpt-5.4`、`azure/gpt-5.4`、`anthropic/claude-sonnet-4.6`） |\n| `api_keys` | string[] | 是* | 认证密钥。多个密钥可按请求轮换。本地 provider（Ollama、LM Studio、VLLM）不需要 |\n| `api_base` | string | 否 | 覆盖默认的 API 端点 URL |\n| `proxy` | string | 否 | 此模型条目的 HTTP 代理 URL |\n| `user_agent` | string | 否 | 自定义 `User-Agent` 请求头（支持 OpenAI 兼容、Anthropic 和 Azure provider） |\n| `request_timeout` | int | 否 | 请求超时时间（秒），默认值因 provider 而异 |\n| `max_tokens_field` | string | 否 | 覆盖请求体中 max tokens 的字段名（如 o1 模型使用 `max_completion_tokens`） |\n| `thinking_level` | string | 否 | 扩展思考级别：`off`、`low`、`medium`、`high`、`xhigh` 或 `adaptive` |\n| `extra_body` | object | 否 | 注入到每个请求体中的额外字段 |\n| `rpm` | int | 否 | 每分钟请求速率限制 |\n| `fallbacks` | string[] | 否 | 自动故障转移的备用模型名称 |\n| `enabled` | bool | 否 | 是否启用此模型条目（默认：`true`） |\n\n#### 语音转录\n\n你可以通过 `voice.model_name` 为语音转录指定一个专用模型。这样可以直接复用已经配置好的、支持音频输入的多模态 provider，而不必只依赖 Groq。\n\n如果没有配置 `voice.model_name`，且存在 Groq API Key，PicoClaw 会继续回退到 Groq 转录。\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"voice-gemini\",\n \"model\": \"gemini/gemini-2.5-flash\",\n \"api_keys\": [\"your-gemini-key\"]\n }\n ],\n \"voice\": {\n \"model_name\": \"voice-gemini\",\n \"echo_transcription\": false\n },\n \"providers\": {\n \"groq\": {\n \"api_key\": \"gsk_xxx\"\n }\n }\n}\n```\n\n#### 各厂商配置示例\n\n**OpenAI**\n\n```json\n{\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**火山引擎（Doubao）**\n\n```json\n{\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**智谱 AI (GLM)**\n\n```json\n{\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-key\"]\n}\n```\n\n**DeepSeek**\n\n```json\n{\n \"model_name\": \"deepseek-chat\",\n \"model\": \"deepseek/deepseek-chat\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**Anthropic (使用 OAuth)**\n\n```json\n{\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"auth_method\": \"oauth\"\n}\n```\n\n> 运行 `picoclaw auth login --provider anthropic` 来设置 OAuth 凭证。\n\n**Anthropic Messages API（原生格式）**\n\n用于直接访问 Anthropic API 或仅支持 Anthropic 原生消息格式的自定义端点：\n\n```json\n{\n \"model_name\": \"claude-opus-4-6\",\n \"model\": \"anthropic-messages/claude-opus-4-6\",\n \"api_keys\": [\"sk-ant-your-key\"],\n \"api_base\": \"https://api.anthropic.com\"\n}\n```\n\n> 使用 `anthropic-messages` 协议的场景：\n> - 使用仅支持 Anthropic 原生 `/v1/messages` 端点的第三方代理（不支持 OpenAI 兼容的 `/v1/chat/completions`）\n> - 连接到 MiniMax、Synthetic 等需要 Anthropic 原生消息格式的服务\n> - 现有的 `anthropic` 协议返回 404 错误（说明端点不支持 OpenAI 兼容格式）\n>\n> **注意：** `anthropic` 协议使用 OpenAI 兼容格式（`/v1/chat/completions`），而 `anthropic-messages` 使用 Anthropic 原生格式（`/v1/messages`）。请根据端点支持的格式选择。\n\n**Ollama (本地)**\n\n```json\n{\n \"model_name\": \"llama3\",\n \"model\": \"ollama/llama3\"\n}\n```\n\n**LM Studio（本地）**\n\n```json\n{\n \"model_name\": \"lmstudio-local\",\n \"model\": \"lmstudio/openai/gpt-oss-20b\"\n}\n```\n\n`api_base` 默认是 `http://localhost:1234/v1`。除非你在 LM Studio 侧启用了认证，否则不需要配置 API Key。\nPicoClaw 向 LM Studio 的 OpenAI 兼容终结点发送请求，且将移除首个 `lmstudio/` 前缀，因此 `lmstudio/openai/gpt-oss-20b` 会发送 `openai/gpt-oss-20b`。\n\n**自定义代理/API**\n\n```json\n{\n \"model_name\": \"my-custom-model\",\n \"model\": \"openai/custom-model\",\n \"api_base\": \"https://my-proxy.com/v1\",\n \"api_keys\": [\"sk-...\"],\n \"user_agent\": \"MyApp/1.0\",\n \"request_timeout\": 300\n}\n```\n\n**LiteLLM Proxy**\n\n```json\n{\n \"model_name\": \"lite-gpt4\",\n \"model\": \"litellm/lite-gpt4\",\n \"api_base\": \"http://localhost:4000/v1\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\nPicoClaw 在发送请求前仅去除外层 `litellm/` 前缀，因此 `litellm/lite-gpt4` 会发送 `lite-gpt4`，而 `litellm/openai/gpt-4o` 会发送 `openai/gpt-4o`。\n\n#### 负载均衡\n\n为同一个模型名称配置多个端点——PicoClaw 会自动在它们之间轮询：\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api1.example.com/v1\",\n \"api_keys\": [\"sk-key1\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api2.example.com/v1\",\n \"api_keys\": [\"sk-key2\"]\n }\n ]\n}\n```\n\n#### 自动模型失败切换（Cascade）\n\n当你在 Agent 的模型设置里配置 `primary` + `fallbacks` 时，PicoClaw 已经支持自动失败切换。\n运行时 fallback 链会在可重试错误时切到下一个候选（例如 HTTP `429`、配额/限流错误、超时错误）。\n同时会对每个候选应用 cooldown，避免对刚失败的目标立即重试。\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"qwen-main\",\n \"model\": \"openai/qwen3.5:cloud\",\n \"api_base\": \"https://api.example.com/v1\",\n \"api_keys\": [\"sk-main\"]\n },\n {\n \"model_name\": \"deepseek-backup\",\n \"model\": \"deepseek/deepseek-chat\",\n \"api_keys\": [\"sk-backup-1\"]\n },\n {\n \"model_name\": \"gemini-backup\",\n \"model\": \"gemini/gemini-2.5-flash\",\n \"api_keys\": [\"sk-backup-2\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model\": {\n \"primary\": \"qwen-main\",\n \"fallbacks\": [\"deepseek-backup\", \"gemini-backup\"]\n }\n }\n }\n}\n```\n\n如果你在同一模型上启用了 key 级失败切换，PicoClaw 会先在该模型的多 key 候选间切换，再继续切到跨模型备选。\n\n#### 从旧的 `providers` 配置迁移\n\n旧的 `providers` 配置格式**已弃用**，V2 中已移除。现有 V0/V1 配置会自动迁移。\n\n**旧配置（已弃用）：**\n\n```json\n{\n \"providers\": {\n \"zhipu\": {\n \"api_key\": \"your-key\",\n \"api_base\": \"https://open.bigmodel.cn/api/paas/v4\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"provider\": \"zhipu\",\n \"model\": \"glm-4.7\"\n }\n }\n}\n```\n\n**新配置（推荐）：**\n\n```json\n{\n \"version\": 2,\n \"model_list\": [\n {\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-key\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"glm-4.7\"\n }\n }\n}\n```\n\n详细的迁移指南请参考 [docs/migration/model-list-migration.md](../migration/model-list-migration.md)。\n\n### Provider 架构\n\nPicoClaw 按协议族路由 Provider：\n\n- OpenAI 兼容协议：OpenRouter、OpenAI 兼容网关、Groq、智谱、vLLM 风格端点。\n- Anthropic 协议：Claude 原生 API 行为。\n- Codex/OAuth 路径：OpenAI OAuth/Token 认证路由。\n\n这使得运行时保持轻量，同时让新的 OpenAI 兼容后端基本只需配置操作（`api_base` + `api_key`）。\n\n<details>\n<summary><b>智谱 (Zhipu) 配置示例</b></summary>\n\n**1. 获取 API key 和 base URL**\n\n- 获取 [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)\n\n**2. 配置**\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"workspace\": \"~/.picoclaw/workspace\",\n \"model_name\": \"glm-4.7\",\n \"max_tokens\": 8192,\n \"temperature\": 0.7,\n \"max_tool_iterations\": 20\n }\n },\n \"providers\": {\n \"zhipu\": {\n \"api_key\": \"Your API Key\",\n \"api_base\": \"https://open.bigmodel.cn/api/paas/v4\"\n }\n }\n}\n```\n\n**3. 运行**\n\n```bash\npicoclaw agent -m \"你好\"\n```\n\n</details>\n\n<details>\n<summary><b>完整配置示例</b></summary>\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"anthropic/claude-opus-4-5\"\n }\n },\n \"session\": {\n \"dm_scope\": \"per-channel-peer\"\n },\n \"providers\": {\n \"openrouter\": {\n \"api_key\": \"sk-or-v1-xxx\"\n },\n \"groq\": {\n \"api_key\": \"gsk_xxx\"\n }\n },\n \"voice\": {\n \"model_name\": \"voice-gemini\",\n \"echo_transcription\": false\n },\n \"channels\": {\n \"telegram\": {\n \"enabled\": true,\n \"token\": \"123456:ABC...\",\n \"allow_from\": [\"123456789\"]\n },\n \"discord\": {\n \"enabled\": true,\n \"token\": \"\",\n \"allow_from\": [\"\"]\n },\n \"whatsapp\": {\n \"enabled\": false,\n \"bridge_url\": \"ws://localhost:3001\",\n \"use_native\": false,\n \"session_store_path\": \"\",\n \"allow_from\": []\n },\n \"feishu\": {\n \"enabled\": false,\n \"app_id\": \"cli_xxx\",\n \"app_secret\": \"xxx\",\n \"encrypt_key\": \"\",\n \"verification_token\": \"\",\n \"allow_from\": []\n },\n \"qq\": {\n \"enabled\": false,\n \"app_id\": \"\",\n \"app_secret\": \"\",\n \"allow_from\": []\n }\n },\n \"tools\": {\n \"web\": {\n \"brave\": {\n \"enabled\": false,\n \"api_key\": \"BSA...\",\n \"max_results\": 5\n },\n \"duckduckgo\": {\n \"enabled\": true,\n \"max_results\": 5\n },\n \"perplexity\": {\n \"enabled\": false,\n \"api_key\": \"\",\n \"max_results\": 5\n },\n \"searxng\": {\n \"enabled\": false,\n \"base_url\": \"http://localhost:8888\",\n \"max_results\": 5\n }\n },\n \"cron\": {\n \"exec_timeout_minutes\": 5\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"interval\": 30\n }\n}\n```\n\n</details>\n\n---\n\n## 📝 API Key 对比\n\n| 服务 | 价格 | 适用场景 |\n| --- | --- | --- |\n| **OpenRouter** | 免费: 200K tokens/月 | 多模型聚合 (Claude, GPT-4 等) |\n| **火山引擎 CodingPlan** | ¥9.9/首月 | 最适合国内用户，多种 SOTA 模型（豆包、DeepSeek 等） |\n| **智谱 (Zhipu)** | 免费: 200K tokens/月 | 适合中国用户 |\n| **Brave Search** | $5/1000 次查询 | 网络搜索功能 |\n| **SearXNG** | 免费（自建） | 隐私优先的元搜索引擎（70+ 搜索引擎） |\n| **Groq** | 免费额度可用 | 极速推理 (Llama, Mixtral) |\n| **Cerebras** | 免费额度可用 | 极速推理 (Llama, Qwen 等) |\n| **LongCat** | 免费: 最多 5M tokens/天 | 极速推理 |\n| **ModelScope (魔搭)** | 免费: 2000 次请求/天 | 推理 (Qwen, GLM, DeepSeek 等) |\n"}}, "docs/providers.md": {"0f133473014e443de79a1ee7f5121f2dbc4bb740": {"t": 1785674178.8849096, "n": 21854, "h": "8078a07ec72ba7ca", "c": "# 🔌 Providers & Model Configuration\n\n> Back to [README](../README.md)\n\n### Providers\n\n> [!NOTE]\n> Voice transcription can use a configured multimodal model via `voice.model_name`. Groq Whisper remains available as a fallback when no voice model is configured.\n\n| Provider | Purpose | Get API Key |\n| ------------ | --------------------------------------- | ------------------------------------------------------------ |\n| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) |\n| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](https://bigmodel.cn) |\n| `zai-coding` | LLM (Z.AI Coding Plan) | [z.ai](https://z.ai/manage-apikey/apikey-list) |\n| `volcengine` | LLM(Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |\n| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) |\n| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) |\n| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) |\n| `venice` | LLM (Venice AI direct) | [venice.ai](https://venice.ai) |\n| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) |\n| `qwen` | LLM (Qwen direct) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |\n| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) |\n| `cerebras` | LLM (Cerebras direct) | [cerebras.ai](https://cerebras.ai) |\n| `vivgrid` | LLM (Vivgrid direct) | [vivgrid.com](https://vivgrid.com) |\n| `nvidia` | LLM (NVIDIA NIM) | [build.nvidia.com](https://build.nvidia.com) |\n| `moonshot` | LLM (Kimi/Moonshot direct) | [platform.moonshot.cn](https://platform.moonshot.cn) |\n| `minimax` | LLM (Minimax direct) | [platform.minimaxi.com](https://platform.minimaxi.com) |\n| `avian` | LLM (Avian direct) | [avian.io](https://avian.io) |\n| `mistral` | LLM (Mistral direct) | [console.mistral.ai](https://console.mistral.ai) |\n| `longcat` | LLM (Longcat direct) | [longcat.ai](https://longcat.ai) |\n| `modelscope` | LLM (ModelScope direct) | [modelscope.cn](https://modelscope.cn) |\n| `mimo` | LLM (Xiaomi MiMo direct) | [platform.xiaomimimo.com](https://platform.xiaomimimo.com) |\n\n### Model Configuration (model_list)\n\n> **What's New?** PicoClaw now uses a **model-centric** configuration approach. Simply specify `vendor/model` format (e.g., `zhipu/glm-4.7`) to add new providers—**zero code changes required!**\n\nThis design also enables **multi-agent support** with flexible provider selection:\n\n- **Different agents, different providers**: Each agent can use its own LLM provider\n- **Model fallbacks**: Configure primary and fallback models for resilience\n- **Load balancing**: Distribute requests across multiple endpoints\n- **Centralized configuration**: Manage all providers in one place\n\n#### 📋 All Supported Vendors\n\n| Vendor | `model` Prefix | Default API Base | Protocol | API Key |\n| ------------------- | ----------------- |-----------------------------------------------------| --------- | ---------------------------------------------------------------- |\n| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Get Key](https://platform.openai.com) |\n| **Venice AI** | `venice/` | `https://api.venice.ai/api/v1` | OpenAI | [Get Key](https://venice.ai) |\n| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Get Key](https://console.anthropic.com) |\n| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |\n| **Z.AI Coding Plan** | `openai/` | `https://api.z.ai/api/coding/paas/v4` | OpenAI | [Get Key](https://z.ai/manage-apikey/apikey-list) |\n| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Get Key](https://platform.deepseek.com) |\n| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Get Key](https://aistudio.google.com/api-keys) |\n| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Get Key](https://console.groq.com) |\n| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Get Key](https://platform.moonshot.cn) |\n| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Get Key](https://dashscope.console.aliyun.com) |\n| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Get Key](https://build.nvidia.com) |\n| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (no key needed) |\n| **LM Studio** | `lmstudio/` | `http://localhost:1234/v1` | OpenAI | Optional (local default: no key) |\n| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Get Key](https://openrouter.ai/keys) |\n| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | Your LiteLLM proxy key |\n| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local |\n| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Get Key](https://cerebras.ai) |\n| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |\n| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |\n| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [Get Key](https://www.byteplus.com) |\n| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [Get Key](https://vivgrid.com) |\n| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [Get Key](https://longcat.chat/platform) |\n| **ModelScope (魔搭)**| `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [Get Token](https://modelscope.cn/my/tokens) |\n| **Xiaomi MiMo** | `mimo/` | `https://api.xiaomimimo.com/v1` | OpenAI | [Get Key](https://platform.xiaomimimo.com) |\n| **Azure OpenAI** | `azure/` | `https://{resource}.openai.azure.com` | Azure | [Get Key](https://portal.azure.com) |\n| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth only |\n| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |\n\n#### Basic Configuration\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-your-api-key\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-your-openai-key\"]\n },\n {\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"api_keys\": [\"sk-ant-your-key\"]\n },\n {\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-zhipu-key\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"gpt-5.4\"\n }\n }\n}\n```\n\n#### `model_list` Entry Fields\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `model_name` | string | Yes | Unique name used to reference this model in agent config |\n| `model` | string | Yes | Vendor/model identifier (e.g., `openai/gpt-5.4`, `azure/gpt-5.4`, `anthropic/claude-sonnet-4.6`) |\n| `api_keys` | string[] | Yes* | API key(s) for authentication. Multiple keys enable per-request rotation. Not required for local providers (Ollama, LM Studio, VLLM) |\n| `api_base` | string | No | Override the default API endpoint URL |\n| `proxy` | string | No | HTTP proxy URL for this model entry |\n| `user_agent` | string | No | Custom `User-Agent` header sent with API requests (supported by OpenAI-compatible, Anthropic, and Azure providers) |\n| `request_timeout` | int | No | Request timeout in seconds (default varies by provider) |\n| `max_tokens_field` | string | No | Override the max tokens field name in request body (e.g., `max_completion_tokens` for o1 models) |\n| `thinking_level` | string | No | Extended thinking level: `off`, `low`, `medium`, `high`, `xhigh`, or `adaptive` |\n| `extra_body` | object | No | Additional fields to inject into every request body |\n| `rpm` | int | No | Per-minute request rate limit |\n| `fallbacks` | string[] | No | Fallback model names for automatic failover |\n| `enabled` | bool | No | Whether this model entry is active (default: `true`) |\n\n#### Voice Transcription\n\nYou can configure a dedicated model for audio transcription with `voice.model_name`. This lets you reuse existing multimodal providers that support audio input instead of relying only on Groq.\n\nIf `voice.model_name` is not configured, PicoClaw will continue to fall back to Groq transcription when a Groq API key is available.\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"voice-gemini\",\n \"model\": \"gemini/gemini-2.5-flash\",\n \"api_keys\": [\"your-gemini-key\"]\n }\n ],\n \"voice\": {\n \"model_name\": \"voice-gemini\",\n \"echo_transcription\": false\n },\n \"providers\": {\n \"groq\": {\n \"api_key\": \"gsk_xxx\"\n }\n }\n}\n```\n\n#### Vendor-Specific Examples\n\n**OpenAI**\n\n```json\n{\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**VolcEngine (Doubao)**\n\n```json\n{\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**智谱 AI (GLM)**\n\n```json\n{\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-key\"]\n}\n```\n\n**Z.AI Coding Plan (GLM)**\n> Z.AI and 智谱 AI are two brands of the same provider. For the Z.AI Coding Plan use the `openai` model key and the api base as follows, rather than the zhipu config\n```json\n{\n \"model_name\": \"glm-4.7\",\n \"model\": \"openai/glm-4.7\",\n \"api_keys\": [\"your-z.ai-key\"],\n \"api_base\": \"https://api.z.ai/api/coding/paas/v4\"\n}\n```\n\n**DeepSeek**\n\n```json\n{\n \"model_name\": \"deepseek-chat\",\n \"model\": \"deepseek/deepseek-chat\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**Anthropic (with API key)**\n\n```json\n{\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"api_keys\": [\"sk-ant-your-key\"]\n}\n```\n\n> Run `picoclaw auth login --provider anthropic` to paste your API token.\n\n**Anthropic Messages API (native format)**\n\nFor direct Anthropic API access or custom endpoints that only support Anthropic's native message format:\n\n```json\n{\n \"model_name\": \"claude-opus-4-6\",\n \"model\": \"anthropic-messages/claude-opus-4-6\",\n \"api_keys\": [\"sk-ant-your-key\"],\n \"api_base\": \"https://api.anthropic.com\"\n}\n```\n\n> Use `anthropic-messages` protocol when:\n> - Using third-party proxies that only support Anthropic's native `/v1/messages` endpoint (not OpenAI-compatible `/v1/chat/completions`)\n> - Connecting to services like MiniMax, Synthetic that require Anthropic's native message format\n> - The existing `anthropic` protocol returns 404 errors (indicating the endpoint doesn't support OpenAI-compatible format)\n>\n> **Note:** The `anthropic` protocol uses OpenAI-compatible format (`/v1/chat/completions`), while `anthropic-messages` uses Anthropic's native format (`/v1/messages`). Choose based on your endpoint's supported format.\n\n**Ollama (local)**\n\n```json\n{\n \"model_name\": \"llama3\",\n \"model\": \"ollama/llama3\"\n}\n```\n\n**LM Studio (local)**\n\n```json\n{\n \"model_name\": \"lmstudio-local\",\n \"model\": \"lmstudio/openai/gpt-oss-20b\"\n}\n```\n\n`api_base` defaults to `http://localhost:1234/v1`. API key is optional unless your LM Studio server enables authentication.<br/>\nPicoClaw sends OpenAI-compatible requests to LM Studio, and strips the `lmstudio/` prefix before sending requests, so `lmstudio/openai/gpt-oss-20b` sends `openai/gpt-oss-20b` to the LM Studio server.\n\n**Custom Proxy/API**\n\n```json\n{\n \"model_name\": \"my-custom-model\",\n \"model\": \"openai/custom-model\",\n \"api_base\": \"https://my-proxy.com/v1\",\n \"api_keys\": [\"sk-...\"],\n \"user_agent\": \"MyApp/1.0\",\n \"request_timeout\": 300\n}\n```\n\n**LiteLLM Proxy**\n\n```json\n{\n \"model_name\": \"lite-gpt4\",\n \"model\": \"litellm/lite-gpt4\",\n \"api_base\": \"http://localhost:4000/v1\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\nPicoClaw strips only the outer `litellm/` prefix before sending the request, so proxy aliases like `litellm/lite-gpt4` send `lite-gpt4`, while `litellm/openai/gpt-4o` sends `openai/gpt-4o`.\n\n**Z.AI Coding Plan**\n\nIf the standard Zhipu endpoint (`https://open.bigmodel.cn/api/paas/v4`) returns 429 (code 1113: insufficient balance), try using the Z.AI Coding Plan endpoint instead:\n\n```json\n{\n \"model_name\": \"glm-4.7\",\n \"model\": \"openai/glm-4.7\",\n \"api_keys\": [\"your-zhipu-api-key\"],\n \"api_base\": \"https://api.z.ai/api/coding/paas/v4\"\n}\n```\n\n**Note:** The Z.AI Coding Plan endpoint and standard Zhipu endpoint use the same API key format but have separate billing. If you encounter 429 errors with the standard Zhipu endpoint, the Z.AI Coding Plan endpoint may have available balance.\n\n#### Load Balancing\n\nConfigure multiple endpoints for the same model name—PicoClaw will automatically round-robin between them:\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api1.example.com/v1\",\n \"api_keys\": [\"sk-key1\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api2.example.com/v1\",\n \"api_keys\": [\"sk-key2\"]\n }\n ]\n}\n```\n\n#### Automatic Model Failover (Cascade)\n\nPicoClaw already supports automatic failover when you configure `primary` + `fallbacks` in the agent model settings.\nThe runtime fallback chain retries the next candidate for retriable failures such as HTTP `429`, quota/rate-limit errors, and timeout errors.\nIt also applies cooldown tracking per candidate to avoid immediately retrying a recently failed target.\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"qwen-main\",\n \"model\": \"openai/qwen3.5:cloud\",\n \"api_base\": \"https://api.example.com/v1\",\n \"api_keys\": [\"sk-main\"]\n },\n {\n \"model_name\": \"deepseek-backup\",\n \"model\": \"deepseek/deepseek-chat\",\n \"api_keys\": [\"sk-backup-1\"]\n },\n {\n \"model_name\": \"gemini-backup\",\n \"model\": \"gemini/gemini-2.5-flash\",\n \"api_keys\": [\"sk-backup-2\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model\": {\n \"primary\": \"qwen-main\",\n \"fallbacks\": [\"deepseek-backup\", \"gemini-backup\"]\n }\n }\n }\n}\n```\n\nIf you use key-level failover for the same model, PicoClaw can chain through additional key-backed candidates before moving to cross-model backups.\n\n#### Migration from Legacy `providers` Config\n\nThe old `providers` configuration is **deprecated** and has been removed in V2. Existing V0/V1 configs are auto-migrated.\n\n**Old Config (deprecated):**\n\n```json\n{\n \"providers\": {\n \"zhipu\": {\n \"api_key\": \"your-key\",\n \"api_base\": \"https://open.bigmodel.cn/api/paas/v4\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"provider\": \"zhipu\",\n \"model\": \"glm-4.7\"\n }\n }\n}\n```\n\n**New Config (recommended):**\n\n```json\n{\n \"version\": 2,\n \"model_list\": [\n {\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-key\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"glm-4.7\"\n }\n }\n}\n```\n\nFor detailed migration guide, see [migration/model-list-migration.md](migration/model-list-migration.md).\n\n### Provider Architecture\n\nPicoClaw routes providers by protocol family:\n\n- OpenAI-compatible protocol: OpenRouter, OpenAI-compatible gateways, Groq, Zhipu, and vLLM-style endpoints.\n- Anthropic protocol: Claude-native API behavior.\n- Codex/OAuth path: OpenAI OAuth/token authentication route.\n\nThis keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_key`).\n\n<details>\n<summary><b>Zhipu</b></summary>\n\n**1. Get API key and base URL**\n\n* Get [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)\n\n**2. Configure**\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"workspace\": \"~/.picoclaw/workspace\",\n \"model_name\": \"glm-4.7\",\n \"max_tokens\": 8192,\n \"temperature\": 0.7,\n \"max_tool_iterations\": 20\n }\n },\n \"providers\": {\n \"zhipu\": {\n \"api_key\": \"Your API Key\",\n \"api_base\": \"https://open.bigmodel.cn/api/paas/v4\"\n }\n }\n}\n```\n\n**3. Run**\n\n```bash\npicoclaw agent -m \"Hello\"\n```\n\n</details>\n\n<details>\n<summary><b>Full config example</b></summary>\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"anthropic/claude-opus-4-5\"\n }\n },\n \"session\": {\n \"dm_scope\": \"per-channel-peer\"\n },\n \"providers\": {\n \"openrouter\": {\n \"api_key\": \"sk-or-v1-xxx\"\n },\n \"groq\": {\n \"api_key\": \"gsk_xxx\"\n }\n },\n \"voice\": {\n \"model_name\": \"voice-gemini\",\n \"echo_transcription\": false\n },\n \"channels\": {\n \"telegram\": {\n \"enabled\": true,\n \"token\": \"123456:ABC...\",\n \"allow_from\": [\"123456789\"]\n },\n \"discord\": {\n \"enabled\": true,\n \"token\": \"\",\n \"allow_from\": [\"\"]\n },\n \"whatsapp\": {\n \"enabled\": false,\n \"bridge_url\": \"ws://localhost:3001\",\n \"use_native\": false,\n \"session_store_path\": \"\",\n \"allow_from\": []\n },\n \"feishu\": {\n \"enabled\": false,\n \"app_id\": \"cli_xxx\",\n \"app_secret\": \"xxx\",\n \"encrypt_key\": \"\",\n \"verification_token\": \"\",\n \"allow_from\": []\n },\n \"qq\": {\n \"enabled\": false,\n \"app_id\": \"\",\n \"app_secret\": \"\",\n \"allow_from\": []\n }\n },\n \"tools\": {\n \"web\": {\n \"brave\": {\n \"enabled\": false,\n \"api_key\": \"BSA...\",\n \"max_results\": 5\n },\n \"duckduckgo\": {\n \"enabled\": true,\n \"max_results\": 5\n },\n \"perplexity\": {\n \"enabled\": false,\n \"api_key\": \"\",\n \"max_results\": 5\n },\n \"searxng\": {\n \"enabled\": false,\n \"base_url\": \"http://localhost:8888\",\n \"max_results\": 5\n }\n },\n \"cron\": {\n \"exec_timeout_minutes\": 5\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"interval\": 30\n }\n}\n```\n\n</details>\n\n---\n\n## 📝 API Key Comparison\n\n| Service | Pricing | Use Case |\n| ---------------- | ------------------------ | ------------------------------------- |\n| **OpenRouter** | Free: 200K tokens/month | Multiple models (Claude, GPT-4, etc.) |\n| **Volcengine CodingPlan** | ¥9.9/first month | Best for Chinese users, multiple SOTA models (Doubao, DeepSeek, etc.) |\n| **Zhipu** | Free: 200K tokens/month | Suitable for Chinese users |\n| **Brave Search** | $5/1000 queries | Web search functionality |\n| **SearXNG** | Free (self-hosted) | Privacy-focused metasearch (70+ engines) |\n| **Groq** | Free tier available | Fast inference (Llama, Mixtral) |\n| **Cerebras** | Free tier available | Fast inference (Llama, Qwen, etc.) |\n| **LongCat** | Free: up to 5M tokens/day | Fast inference |\n| **ModelScope** | Free: 2000 requests/day | Inference (Qwen, GLM, DeepSeek, etc.) |\n\n---\n\n<div align=\"center\">\n <img src=\"assets/logo.jpg\" alt=\"PicoClaw Meme\" width=\"512\">\n</div>\n"}}, "docs/fr/providers.md": {"0f133473014e443de79a1ee7f5121f2dbc4bb740": {"t": 1785674179.0575051, "n": 17904, "h": "e280d086430eb421", "c": "# 🔌 Fournisseurs et Configuration des Modèles\n\n> Retour au [README](../../README.fr.md)\n\n### Fournisseurs\n\n> [!NOTE]\n> Groq fournit la transcription vocale gratuite via Whisper. Si configuré, les messages audio de n'importe quel canal seront automatiquement transcrits au niveau de l'agent.\n\n| Provider | Purpose | Get API Key |\n| ------------ | --------------------------------------- | ------------------------------------------------------------ |\n| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) |\n| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](https://bigmodel.cn) |\n| `volcengine` | LLM (Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |\n| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) |\n| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) |\n| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) |\n| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) |\n| `qwen` | LLM (Qwen direct) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |\n| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) |\n| `cerebras` | LLM (Cerebras direct) | [cerebras.ai](https://cerebras.ai) |\n| `vivgrid` | LLM (Vivgrid direct) | [vivgrid.com](https://vivgrid.com) |\n| `moonshot` | LLM (Kimi/Moonshot direct) | [platform.moonshot.cn](https://platform.moonshot.cn) |\n| `minimax` | LLM (Minimax direct) | [platform.minimaxi.com](https://platform.minimaxi.com) |\n| `avian` | LLM (Avian direct) | [avian.io](https://avian.io) |\n| `mistral` | LLM (Mistral direct) | [console.mistral.ai](https://console.mistral.ai) |\n| `longcat` | LLM (Longcat direct) | [longcat.ai](https://longcat.ai) |\n| `modelscope` | LLM (ModelScope direct) | [modelscope.cn](https://modelscope.cn) |\n\n### Configuration des Modèles (model_list)\n\n> **Nouveauté** PicoClaw utilise désormais une approche de configuration **centrée sur le modèle**. Spécifiez simplement le format `vendor/model` (par ex. `zhipu/glm-4.7`) pour ajouter de nouveaux fournisseurs — **aucune modification de code requise !**\n\nCette conception permet également le **support multi-agents** avec une sélection flexible de fournisseurs :\n\n- **Différents agents, différents fournisseurs** : Chaque agent peut utiliser son propre fournisseur LLM\n- **Modèles de repli** : Configurez des modèles principaux et de repli pour la résilience\n- **Répartition de charge** : Distribuez les requêtes entre plusieurs endpoints\n- **Configuration centralisée** : Gérez tous les fournisseurs en un seul endroit\n\n#### 📋 Tous les Vendors Supportés\n\n| Vendor | `model` Prefix | Default API Base | Protocol | API Key |\n| ------------------- | ----------------- |-----------------------------------------------------| --------- | ---------------------------------------------------------------- |\n| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Get Key](https://platform.openai.com) |\n| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Get Key](https://console.anthropic.com) |\n| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |\n| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Get Key](https://platform.deepseek.com) |\n| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Get Key](https://aistudio.google.com/api-keys) |\n| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Get Key](https://console.groq.com) |\n| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Get Key](https://platform.moonshot.cn) |\n| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Get Key](https://dashscope.console.aliyun.com) |\n| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Get Key](https://build.nvidia.com) |\n| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (no key needed) |\n| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Get Key](https://openrouter.ai/keys) |\n| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | Your LiteLLM proxy key |\n| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local |\n| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Get Key](https://cerebras.ai) |\n| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |\n| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |\n| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [Get Key](https://www.byteplus.com) |\n| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [Get Key](https://vivgrid.com) |\n| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [Get Key](https://longcat.chat/platform) |\n| **ModelScope (魔搭)**| `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [Get Token](https://modelscope.cn/my/tokens) |\n| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth only |\n| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |\n\n#### Configuration de Base\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-your-api-key\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-your-openai-key\"]\n },\n {\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"api_keys\": [\"sk-ant-your-key\"]\n },\n {\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-zhipu-key\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"gpt-5.4\"\n }\n }\n}\n```\n\n#### Champs d'entrée `model_list`\n\n| Champ | Type | Requis | Description |\n|-------|------|--------|-------------|\n| `model_name` | string | Oui | Nom unique pour référencer ce modèle dans la config agent |\n| `model` | string | Oui | Identifiant fournisseur/modèle (ex : `openai/gpt-5.4`, `azure/gpt-5.4`, `anthropic/claude-sonnet-4.6`) |\n| `api_keys` | string[] | Oui* | Clé(s) API pour l'authentification. Plusieurs clés permettent la rotation par requête. Non requis pour les fournisseurs locaux (Ollama, LM Studio, VLLM) |\n| `api_base` | string | Non | Remplace l'URL de base API par défaut |\n| `proxy` | string | Non | URL du proxy HTTP pour cette entrée de modèle |\n| `user_agent` | string | Non | En-tête `User-Agent` personnalisé pour les requêtes API (supporté par les providers OpenAI-compatible, Anthropic et Azure) |\n| `request_timeout` | int | Non | Délai d'expiration de la requête en secondes (la valeur par défaut varie selon le provider) |\n| `max_tokens_field` | string | Non | Remplace le nom du champ max tokens dans le corps de la requête (ex : `max_completion_tokens` pour les modèles o1) |\n| `thinking_level` | string | Non | Niveau de pensée étendue : `off`, `low`, `medium`, `high`, `xhigh` ou `adaptive` |\n| `extra_body` | object | Non | Champs supplémentaires à injecter dans chaque corps de requête |\n| `rpm` | int | Non | Limite de requêtes par minute |\n| `fallbacks` | string[] | Non | Noms des modèles de secours pour le basculement automatique |\n| `enabled` | bool | Non | Activer ou désactiver cette entrée de modèle (par défaut : `true`) |\n\n#### Exemples par Vendor\n\n**OpenAI**\n\n```json\n{\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**VolcEngine (Doubao)**\n\n```json\n{\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**智谱 AI (GLM)**\n\n```json\n{\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-key\"]\n}\n```\n\n**DeepSeek**\n\n```json\n{\n \"model_name\": \"deepseek-chat\",\n \"model\": \"deepseek/deepseek-chat\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**Anthropic (avec clé API)**\n\n```json\n{\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"api_keys\": [\"sk-ant-your-key\"]\n}\n```\n\n> Exécutez `picoclaw auth login --provider anthropic` pour coller votre token API.\n\n**API Anthropic Messages (format natif)**\n\nPour l'accès direct à l'API Anthropic ou les endpoints personnalisés qui ne prennent en charge que le format de message natif d'Anthropic :\n\n```json\n{\n \"model_name\": \"claude-opus-4-6\",\n \"model\": \"anthropic-messages/claude-opus-4-6\",\n \"api_keys\": [\"sk-ant-your-key\"],\n \"api_base\": \"https://api.anthropic.com\"\n}\n```\n\n> Utilisez le protocole `anthropic-messages` lorsque :\n> - Vous utilisez des proxys tiers qui ne prennent en charge que l'endpoint natif `/v1/messages` d'Anthropic (pas le format compatible OpenAI `/v1/chat/completions`)\n> - Vous vous connectez à des services comme MiniMax, Synthetic qui nécessitent le format de message natif d'Anthropic\n> - Le protocole `anthropic` existant renvoie des erreurs 404 (indiquant que l'endpoint ne prend pas en charge le format compatible OpenAI)\n>\n> **Note :** Le protocole `anthropic` utilise le format compatible OpenAI (`/v1/chat/completions`), tandis que `anthropic-messages` utilise le format natif d'Anthropic (`/v1/messages`). Choisissez en fonction du format pris en charge par votre endpoint.\n\n**Ollama (local)**\n\n```json\n{\n \"model_name\": \"llama3\",\n \"model\": \"ollama/llama3\"\n}\n```\n\n**Proxy/API Personnalisé**\n\n```json\n{\n \"model_name\": \"my-custom-model\",\n \"model\": \"openai/custom-model\",\n \"api_base\": \"https://my-proxy.com/v1\",\n \"api_keys\": [\"sk-...\"],\n \"user_agent\": \"MyApp/1.0\",\n \"request_timeout\": 300\n}\n```\n\n**LiteLLM Proxy**\n\n```json\n{\n \"model_name\": \"lite-gpt4\",\n \"model\": \"litellm/lite-gpt4\",\n \"api_base\": \"http://localhost:4000/v1\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\nPicoClaw ne supprime que le préfixe externe `litellm/` avant d'envoyer la requête, donc les alias de proxy comme `litellm/lite-gpt4` envoient `lite-gpt4`, tandis que `litellm/openai/gpt-4o` envoie `openai/gpt-4o`.\n\n#### Répartition de Charge\n\nConfigurez plusieurs endpoints pour le même nom de modèle — PicoClaw effectuera automatiquement un round-robin entre eux :\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api1.example.com/v1\",\n \"api_keys\": [\"sk-key1\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api2.example.com/v1\",\n \"api_keys\": [\"sk-key2\"]\n }\n ]\n}\n```\n\n#### Migration depuis l'Ancienne Configuration `providers`\n\nL'ancienne configuration `providers` est **dépréciée** et a été supprimée dans V2. Les configs V0/V1 existantes sont auto-migrées.\n\n**Ancienne configuration (dépréciée) :**\n\n```json\n{\n \"providers\": {\n \"zhipu\": {\n \"api_key\": \"your-key\",\n \"api_base\": \"https://open.bigmodel.cn/api/paas/v4\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"provider\": \"zhipu\",\n \"model\": \"glm-4.7\"\n }\n }\n}\n```\n\n**Nouvelle configuration (recommandée) :**\n\n```json\n{\n \"version\": 2,\n \"model_list\": [\n {\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-key\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"glm-4.7\"\n }\n }\n}\n```\n\nPour un guide de migration détaillé, voir [migration/model-list-migration.md](../migration/model-list-migration.md).\n\n### Architecture des Fournisseurs\n\nPicoClaw route les fournisseurs par famille de protocoles :\n\n- Protocole compatible OpenAI : OpenRouter, passerelles compatibles OpenAI, Groq, Zhipu et endpoints de type vLLM.\n- Protocole Anthropic : Comportement natif de l'API Claude.\n- Chemin Codex/OAuth : Route d'authentification OAuth/token OpenAI.\n\nCela maintient le runtime léger tout en faisant des nouveaux backends compatibles OpenAI principalement une opération de configuration (`api_base` + `api_key`).\n\n<details>\n<summary><b>Zhipu</b></summary>\n\n**1. Obtenir la clé API et l'URL de base**\n\n* Obtenir la [clé API](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)\n\n**2. Configurer**\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"workspace\": \"~/.picoclaw/workspace\",\n \"model_name\": \"glm-4.7\",\n \"max_tokens\": 8192,\n \"temperature\": 0.7,\n \"max_tool_iterations\": 20\n }\n },\n \"providers\": {\n \"zhipu\": {\n \"api_key\": \"Your API Key\",\n \"api_base\": \"https://open.bigmodel.cn/api/paas/v4\"\n }\n }\n}\n```\n\n**3. Lancer**\n\n```bash\npicoclaw agent -m \"Hello\"\n```\n\n</details>\n\n<details>\n<summary><b>Exemple de configuration complète</b></summary>\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"anthropic/claude-opus-4-5\"\n }\n },\n \"session\": {\n \"dm_scope\": \"per-channel-peer\"\n },\n \"providers\": {\n \"openrouter\": {\n \"api_key\": \"sk-or-v1-xxx\"\n },\n \"groq\": {\n \"api_key\": \"gsk_xxx\"\n }\n },\n \"channels\": {\n \"telegram\": {\n \"enabled\": true,\n \"token\": \"123456:ABC...\",\n \"allow_from\": [\"123456789\"]\n },\n \"discord\": {\n \"enabled\": true,\n \"token\": \"\",\n \"allow_from\": [\"\"]\n },\n \"whatsapp\": {\n \"enabled\": false,\n \"bridge_url\": \"ws://localhost:3001\",\n \"use_native\": false,\n \"session_store_path\": \"\",\n \"allow_from\": []\n },\n \"feishu\": {\n \"enabled\": false,\n \"app_id\": \"cli_xxx\",\n \"app_secret\": \"xxx\",\n \"encrypt_key\": \"\",\n \"verification_token\": \"\",\n \"allow_from\": []\n },\n \"qq\": {\n \"enabled\": false,\n \"app_id\": \"\",\n \"app_secret\": \"\",\n \"allow_from\": []\n }\n },\n \"tools\": {\n \"web\": {\n \"brave\": {\n \"enabled\": false,\n \"api_key\": \"BSA...\",\n \"max_results\": 5\n },\n \"duckduckgo\": {\n \"enabled\": true,\n \"max_results\": 5\n },\n \"perplexity\": {\n \"enabled\": false,\n \"api_key\": \"\",\n \"max_results\": 5\n },\n \"searxng\": {\n \"enabled\": false,\n \"base_url\": \"http://localhost:8888\",\n \"max_results\": 5\n }\n },\n \"cron\": {\n \"exec_timeout_minutes\": 5\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"interval\": 30\n }\n}\n```\n\n</details>\n\n---\n\n## 📝 Comparaison des Clés API\n\n| Service | Pricing | Use Case |\n| ---------------- | ------------------------ | ------------------------------------- |\n| **OpenRouter** | Free: 200K tokens/month | Multiple models (Claude, GPT-4, etc.) |\n| **Volcengine CodingPlan** | ¥9.9/first month | Best for Chinese users, multiple SOTA models (Doubao, DeepSeek, etc.) |\n| **Zhipu** | Free: 200K tokens/month | Suitable for Chinese users |\n| **Brave Search** | $5/1000 queries | Web search functionality |\n| **SearXNG** | Free (self-hosted) | Privacy-focused metasearch (70+ engines) |\n| **Groq** | Free tier available | Fast inference (Llama, Mixtral) |\n| **Cerebras** | Free tier available | Fast inference (Llama, Qwen, etc.) |\n| **LongCat** | Free: up to 5M tokens/day | Fast inference |\n| **ModelScope** | Free: 2000 requests/day | Inference (Qwen, GLM, DeepSeek, etc.) |\n\n---\n\n<div align=\"center\">\n <img src=\"assets/logo.jpg\" alt=\"PicoClaw Meme\" width=\"512\">\n</div>\n"}}, "docs/pt-br/providers.md": {"0f133473014e443de79a1ee7f5121f2dbc4bb740": {"t": 1785674179.6053762, "n": 17644, "h": "9dd899e12047574a", "c": "# 🔌 Provedores e Configuração de Modelos\n\n> Voltar ao [README](../../README.pt-br.md)\n\n### Provedores\n\n> [!NOTE]\n> O Groq fornece transcrição de voz gratuita via Whisper. Se configurado, mensagens de áudio de qualquer canal serão automaticamente transcritas no nível do agente.\n\n| Provider | Purpose | Get API Key |\n| ------------ | --------------------------------------- | ------------------------------------------------------------ |\n| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) |\n| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](https://bigmodel.cn) |\n| `volcengine` | LLM(Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |\n| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) |\n| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) |\n| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) |\n| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) |\n| `qwen` | LLM (Qwen direct) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |\n| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) |\n| `cerebras` | LLM (Cerebras direct) | [cerebras.ai](https://cerebras.ai) |\n| `vivgrid` | LLM (Vivgrid direct) | [vivgrid.com](https://vivgrid.com) |\n| `moonshot` | LLM (Kimi/Moonshot direct) | [platform.moonshot.cn](https://platform.moonshot.cn) |\n| `minimax` | LLM (Minimax direct) | [platform.minimaxi.com](https://platform.minimaxi.com) |\n| `avian` | LLM (Avian direct) | [avian.io](https://avian.io) |\n| `mistral` | LLM (Mistral direct) | [console.mistral.ai](https://console.mistral.ai) |\n| `longcat` | LLM (Longcat direct) | [longcat.ai](https://longcat.ai) |\n| `modelscope` | LLM (ModelScope direct) | [modelscope.cn](https://modelscope.cn) |\n\n### Configuração de Modelos (model_list)\n\n> **Novidade?** O PicoClaw agora usa uma abordagem de configuração **centrada no modelo**. Basta especificar o formato `vendor/model` (ex.: `zhipu/glm-4.7`) para adicionar novos provedores — **sem necessidade de alteração de código!**\n\nEste design também permite **suporte multi-agente** com seleção flexível de provedores:\n\n- **Agentes diferentes, provedores diferentes**: Cada agente pode usar seu próprio provedor LLM\n- **Fallback de modelos**: Configure modelos primários e de fallback para resiliência\n- **Balanceamento de carga**: Distribua requisições entre múltiplos endpoints\n- **Configuração centralizada**: Gerencie todos os provedores em um só lugar\n\n#### 📋 Todos os Vendors Suportados\n\n| Vendor | `model` Prefix | Default API Base | Protocol | API Key |\n| ------------------- | ----------------- |-----------------------------------------------------| --------- | ---------------------------------------------------------------- |\n| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Get Key](https://platform.openai.com) |\n| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Get Key](https://console.anthropic.com) |\n| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |\n| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Get Key](https://platform.deepseek.com) |\n| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Get Key](https://aistudio.google.com/api-keys) |\n| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Get Key](https://console.groq.com) |\n| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Get Key](https://platform.moonshot.cn) |\n| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Get Key](https://dashscope.console.aliyun.com) |\n| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Get Key](https://build.nvidia.com) |\n| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (no key needed) |\n| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Get Key](https://openrouter.ai/keys) |\n| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | Your LiteLLM proxy key |\n| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local |\n| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Get Key](https://cerebras.ai) |\n| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |\n| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |\n| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [Get Key](https://www.byteplus.com) |\n| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [Get Key](https://vivgrid.com) |\n| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [Get Key](https://longcat.chat/platform) |\n| **ModelScope (魔搭)**| `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [Get Token](https://modelscope.cn/my/tokens) |\n| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth only |\n| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |\n\n#### Configuração Básica\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-your-api-key\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-your-openai-key\"]\n },\n {\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"api_keys\": [\"sk-ant-your-key\"]\n },\n {\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-zhipu-key\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"gpt-5.4\"\n }\n }\n}\n```\n\n#### Campos de entrada `model_list`\n\n| Campo | Tipo | Obrigatório | Descrição |\n|-------|------|-------------|-----------|\n| `model_name` | string | Sim | Nome único para referenciar este modelo na config do agent |\n| `model` | string | Sim | Identificador fornecedor/modelo (ex: `openai/gpt-5.4`, `azure/gpt-5.4`, `anthropic/claude-sonnet-4.6`) |\n| `api_keys` | string[] | Sim* | Chave(s) API para autenticação. Múltiplas chaves permitem rotação por requisição. Não necessário para providers locais (Ollama, LM Studio, VLLM) |\n| `api_base` | string | Não | Substitui a URL base da API padrão |\n| `proxy` | string | Não | URL do proxy HTTP para esta entrada de modelo |\n| `user_agent` | string | Não | Cabeçalho `User-Agent` personalizado enviado com requisições API (suportado por providers OpenAI-compatible, Anthropic e Azure) |\n| `request_timeout` | int | Não | Timeout de requisição em segundos (o padrão varia por provider) |\n| `max_tokens_field` | string | Não | Substitui o nome do campo max tokens no corpo da requisição (ex: `max_completion_tokens` para modelos o1) |\n| `thinking_level` | string | Não | Nível de pensamento estendido: `off`, `low`, `medium`, `high`, `xhigh` ou `adaptive` |\n| `extra_body` | object | Não | Campos adicionais para injetar em cada corpo de requisição |\n| `rpm` | int | Não | Limite de requisições por minuto |\n| `fallbacks` | string[] | Não | Nomes dos modelos de fallback para failover automático |\n| `enabled` | bool | Não | Ativar ou desativar esta entrada de modelo (padrão: `true`) |\n\n#### Exemplos por Vendor\n\n**OpenAI**\n\n```json\n{\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**VolcEngine (Doubao)**\n\n```json\n{\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**智谱 AI (GLM)**\n\n```json\n{\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-key\"]\n}\n```\n\n**DeepSeek**\n\n```json\n{\n \"model_name\": \"deepseek-chat\",\n \"model\": \"deepseek/deepseek-chat\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n**Anthropic (com chave de API)**\n\n```json\n{\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"api_keys\": [\"sk-ant-your-key\"]\n}\n```\n\n> Execute `picoclaw auth login --provider anthropic` para colar seu token de API.\n\n**Anthropic Messages API (formato nativo)**\n\nPara acesso direto à API Anthropic ou endpoints personalizados que suportam apenas o formato de mensagem nativo da Anthropic:\n\n```json\n{\n \"model_name\": \"claude-opus-4-6\",\n \"model\": \"anthropic-messages/claude-opus-4-6\",\n \"api_keys\": [\"sk-ant-your-key\"],\n \"api_base\": \"https://api.anthropic.com\"\n}\n```\n\n> Use o protocolo `anthropic-messages` quando:\n> - Usar proxies de terceiros que suportam apenas o endpoint nativo `/v1/messages` da Anthropic (não o compatível com OpenAI `/v1/chat/completions`)\n> - Conectar a serviços como MiniMax, Synthetic que requerem o formato de mensagem nativo da Anthropic\n> - O protocolo `anthropic` existente retorna erros 404 (indicando que o endpoint não suporta formato compatível com OpenAI)\n>\n> **Nota:** O protocolo `anthropic` usa formato compatível com OpenAI (`/v1/chat/completions`), enquanto `anthropic-messages` usa o formato nativo da Anthropic (`/v1/messages`). Escolha com base no formato suportado pelo seu endpoint.\n\n**Ollama (local)**\n\n```json\n{\n \"model_name\": \"llama3\",\n \"model\": \"ollama/llama3\"\n}\n```\n\n**Proxy/API Personalizado**\n\n```json\n{\n \"model_name\": \"my-custom-model\",\n \"model\": \"openai/custom-model\",\n \"api_base\": \"https://my-proxy.com/v1\",\n \"api_keys\": [\"sk-...\"],\n \"user_agent\": \"MyApp/1.0\",\n \"request_timeout\": 300\n}\n```\n\n**LiteLLM Proxy**\n\n```json\n{\n \"model_name\": \"lite-gpt4\",\n \"model\": \"litellm/lite-gpt4\",\n \"api_base\": \"http://localhost:4000/v1\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\nO PicoClaw remove apenas o prefixo externo `litellm/` antes de enviar a requisição, então aliases de proxy como `litellm/lite-gpt4` enviam `lite-gpt4`, enquanto `litellm/openai/gpt-4o` envia `openai/gpt-4o`.\n\n#### Balanceamento de Carga\n\nConfigure múltiplos endpoints para o mesmo nome de modelo — o PicoClaw fará automaticamente round-robin entre eles:\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api1.example.com/v1\",\n \"api_keys\": [\"sk-key1\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api2.example.com/v1\",\n \"api_keys\": [\"sk-key2\"]\n }\n ]\n}\n```\n\n#### Migração da Configuração Legacy `providers`\n\nA configuração antiga `providers` está **descontinuada** e foi removida no V2. Configs V0/V1 existentes são auto-migradas.\n\n**Configuração Antiga (descontinuada):**\n\n```json\n{\n \"providers\": {\n \"zhipu\": {\n \"api_key\": \"your-key\",\n \"api_base\": \"https://open.bigmodel.cn/api/paas/v4\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"provider\": \"zhipu\",\n \"model\": \"glm-4.7\"\n }\n }\n}\n```\n\n**Configuração Nova (recomendada):**\n\n```json\n{\n \"version\": 2,\n \"model_list\": [\n {\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-key\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"glm-4.7\"\n }\n }\n}\n```\n\nPara guia de migração detalhado, veja [migration/model-list-migration.md](../migration/model-list-migration.md).\n\n### Arquitetura de Provedores\n\nO PicoClaw roteia provedores por família de protocolo:\n\n- Protocolo compatível com OpenAI: OpenRouter, gateways compatíveis com OpenAI, Groq, Zhipu e endpoints estilo vLLM.\n- Protocolo Anthropic: Comportamento nativo da API Claude.\n- Caminho Codex/OAuth: Rota de autenticação OAuth/token da OpenAI.\n\nIsso mantém o runtime leve enquanto torna novos backends compatíveis com OpenAI basicamente uma operação de configuração (`api_base` + `api_keys`).\n\n<details>\n<summary><b>Zhipu</b></summary>\n\n**1. Obter chave de API e URL base**\n\n* Obtenha a [chave de API](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)\n\n**2. Configurar**\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"workspace\": \"~/.picoclaw/workspace\",\n \"model_name\": \"glm-4.7\",\n \"max_tokens\": 8192,\n \"temperature\": 0.7,\n \"max_tool_iterations\": 20\n }\n },\n \"providers\": {\n \"zhipu\": {\n \"api_key\": \"Your API Key\",\n \"api_base\": \"https://open.bigmodel.cn/api/paas/v4\"\n }\n }\n}\n```\n\n**3. Executar**\n\n```bash\npicoclaw agent -m \"Hello\"\n```\n\n</details>\n\n<details>\n<summary><b>Exemplo de configuração completa</b></summary>\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model_name\": \"anthropic/claude-opus-4-5\"\n }\n },\n \"session\": {\n \"dm_scope\": \"per-channel-peer\"\n },\n \"providers\": {\n \"openrouter\": {\n \"api_key\": \"sk-or-v1-xxx\"\n },\n \"groq\": {\n \"api_key\": \"gsk_xxx\"\n }\n },\n \"channels\": {\n \"telegram\": {\n \"enabled\": true,\n \"token\": \"123456:ABC...\",\n \"allow_from\": [\"123456789\"]\n },\n \"discord\": {\n \"enabled\": true,\n \"token\": \"\",\n \"allow_from\": [\"\"]\n },\n \"whatsapp\": {\n \"enabled\": false,\n \"bridge_url\": \"ws://localhost:3001\",\n \"use_native\": false,\n \"session_store_path\": \"\",\n \"allow_from\": []\n },\n \"feishu\": {\n \"enabled\": false,\n \"app_id\": \"cli_xxx\",\n \"app_secret\": \"xxx\",\n \"encrypt_key\": \"\",\n \"verification_token\": \"\",\n \"allow_from\": []\n },\n \"qq\": {\n \"enabled\": false,\n \"app_id\": \"\",\n \"app_secret\": \"\",\n \"allow_from\": []\n }\n },\n \"tools\": {\n \"web\": {\n \"brave\": {\n \"enabled\": false,\n \"api_key\": \"BSA...\",\n \"max_results\": 5\n },\n \"duckduckgo\": {\n \"enabled\": true,\n \"max_results\": 5\n },\n \"perplexity\": {\n \"enabled\": false,\n \"api_key\": \"\",\n \"max_results\": 5\n },\n \"searxng\": {\n \"enabled\": false,\n \"base_url\": \"http://localhost:8888\",\n \"max_results\": 5\n }\n },\n \"cron\": {\n \"exec_timeout_minutes\": 5\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"interval\": 30\n }\n}\n```\n\n</details>\n\n---\n\n## 📝 Comparação de Chaves de API\n\n| Service | Pricing | Use Case |\n| ---------------- | ------------------------ | ------------------------------------- |\n| **OpenRouter** | Free: 200K tokens/month | Multiple models (Claude, GPT-4, etc.) |\n| **Volcengine CodingPlan** | ¥9.9/first month | Best for Chinese users, multiple SOTA models (Doubao, DeepSeek, etc.) |\n| **Zhipu** | Free: 200K tokens/month | Suitable for Chinese users |\n| **Brave Search** | $5/1000 queries | Web search functionality |\n| **SearXNG** | Free (self-hosted) | Privacy-focused metasearch (70+ engines) |\n| **Groq** | Free tier available | Fast inference (Llama, Mixtral) |\n| **Cerebras** | Free tier available | Fast inference (Llama, Qwen, etc.) |\n| **LongCat** | Free: up to 5M tokens/day | Fast inference |\n| **ModelScope** | Free: 2000 requests/day | Inference (Qwen, GLM, DeepSeek, etc.) |\n\n---\n\n<div align=\"center\">\n <img src=\"assets/logo.jpg\" alt=\"PicoClaw Meme\" width=\"512\">\n</div>\n"}}, "docs/zh/configuration.md": {"0f133473014e443de79a1ee7f5121f2dbc4bb740": {"t": 1785674284.9690814, "n": 20228, "h": "b6100002ca28dc83", "c": "# ⚙️ 配置指南\n\n> 返回 [README](../../README.zh.md)\n\n## ⚙️ 配置详解\n\n配置文件路径: `~/.picoclaw/config.json`\n\n### 环境变量\n\n你可以使用环境变量覆盖默认路径。这对于便携安装、容器化部署或将 picoclaw 作为系统服务运行非常有用。这些变量是独立的，控制不同的路径。\n\n| 变量 | 描述 | 默认路径 |\n|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|\n| `PICOCLAW_CONFIG` | 覆盖配置文件的路径。这直接告诉 picoclaw 加载哪个 `config.json`，忽略所有其他位置。 | `~/.picoclaw/config.json` |\n| `PICOCLAW_HOME` | 覆盖 picoclaw 数据根目录。这会更改 `workspace` 和其他数据目录的默认位置。 | `~/.picoclaw` |\n\n**示例：**\n\n```bash\n# 使用特定的配置文件运行 picoclaw\n# 工作区路径将从该配置文件中读取\nPICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway\n\n# 在 /opt/picoclaw 中存储所有数据运行 picoclaw\n# 配置将从默认的 ~/.picoclaw/config.json 加载\n# 工作区将在 /opt/picoclaw/workspace 创建\nPICOCLAW_HOME=/opt/picoclaw picoclaw agent\n\n# 同时使用两者进行完全自定义设置\nPICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway\n```\n\n### Gateway 日志等级\n\n`gateway.log_level` 控制 Gateway 的日志详细程度，可在 `config.json` 中配置：\n\n```json\n{\n \"gateway\": {\n \"log_level\": \"warn\"\n }\n}\n```\n\n默认值为 `warn`。支持的值：`debug`、`info`、`warn`、`error`、`fatal`。\n\n也可通过环境变量覆盖：`PICOCLAW_LOG_LEVEL=info`\n\n### 工作区布局 (Workspace Layout)\n\nPicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/workspace`）：\n\n```\n~/.picoclaw/workspace/\n├── sessions/ # 对话会话和历史\n├── memory/ # 长期记忆 (MEMORY.md)\n├── state/ # 持久化状态 (最后一次频道等)\n├── cron/ # 定时任务数据库\n├── skills/ # 自定义技能\n├── AGENT.md # Agent 行为指南\n├── HEARTBEAT.md # 周期性任务提示词 (每 30 分钟检查一次)\n├── IDENTITY.md # Agent 身份设定\n├── SOUL.md # Agent 灵魂/性格\n└── USER.md # 用户偏好\n```\n\n> **提示：** 对 `AGENT.md`、`SOUL.md`、`USER.md` 和 `memory/MEMORY.md` 的修改会通过文件修改时间（mtime）在运行时自动检测。**无需重启 gateway**，Agent 将在下一次请求时自动加载最新内容。\n\n### Web 启动器控制台\n\n用 **picoclaw-launcher** 打开浏览器控制台前需要先登录。**访问口令**与 **会话签名密钥**默认在**每次启动时在内存中生成**（重启后随机口令会变）。若设置环境变量 **`PICOCLAW_LAUNCHER_TOKEN`**，则该进程使用固定口令（启动日志中不会打印具体口令值）。\n\n**到哪里找口令**：**控制台模式**（`-console`）请看启动时的终端输出；**托盘 / GUI 模式**可使用托盘菜单中的「复制控制台口令」，并在 **`$PICOCLAW_HOME/logs/launcher.log`**（未设置 `PICOCLAW_HOME` 时一般为 `~/.picoclaw/logs/launcher.log`）中查看本次启动写入的随机口令。登录页在未登录时会根据当前运行方式展示提示（含日志文件绝对路径等；**接口与页面均不会返回口令本身**）。\n\n- **配置文件**：与 `config.json` 同一目录（若设置了 `PICOCLAW_CONFIG`，则与它所指的文件同目录）。启动器专用文件名为 `launcher-config.json`。\n- **登录与链接**：在登录页输入口令；自动打开浏览器时可在 URL 上使用 `?token=`。全站响应携带 **`Referrer-Policy: no-referrer`**，减轻 `token` 经 `Referer` 头泄露的风险。\n- **退出登录**：应使用 **`POST /api/auth/logout`**，且请求头为 **`Content-Type: application/json`**（请求体可为 `{}`），勿使用可被第三方页面触发的 GET 链接登出。\n- **暴力尝试**：`POST /api/auth/login` 对同一远程地址有 **每分钟尝试次数上限**（超限返回 HTTP 429）。\n- **会话时长**：登录后的 HttpOnly 会话 Cookie 默认约 **7 天**有效，到期需重新用口令登录。\n\n### 技能来源 (Skill Sources)\n\n默认情况下，技能会按以下顺序加载：\n\n1. `~/.picoclaw/workspace/skills`（工作区）\n2. `~/.picoclaw/skills`（全局）\n3. `<构建时嵌入路径>/skills`（内置）\n\n在高级/测试场景下，可通过以下环境变量覆盖内置技能目录：\n\n```bash\nexport PICOCLAW_BUILTIN_SKILLS=/path/to/skills\n```\n\n### 在聊天频道中使用技能\n\n技能安装完成后，可以直接在聊天频道里查看并显式启用它们：\n\n- `/list skills`：显示当前 Agent 可用的已安装技能名称。\n- `/use <skill> <message>`：只对当前这一条请求强制使用指定技能。\n- `/use <skill>`：为同一会话中的下一条消息预先启用该技能。\n- `/use clear`：取消通过 `/use <skill>` 设置的待应用技能。\n\n示例：\n\n```text\n/list skills\n/use git explain how to squash the last 3 commits\n/use italiapersonalfinance\ndammi le ultime news\n```\n\n### 统一命令执行策略\n\n- 通用斜杠命令通过 `pkg/agent/loop.go` 中的 `commands.Executor` 统一执行。\n- Channel 适配器不再在本地消费通用命令；它们只负责把入站文本转发到 bus/agent 路径。Telegram 仍会在启动时自动注册其支持的命令菜单。\n- 未注册的斜杠命令（例如 `/foo`）会透传给 LLM 按普通输入处理。\n- 已注册但当前 channel 不支持的命令（例如 WhatsApp 上的 `/show`）会返回明确的用户可见错误，并停止后续处理。\n\n### 🔒 安全沙箱 (Security Sandbox)\n\nPicoClaw 默认在沙箱环境中运行。Agent 只能访问配置的工作区内的文件和执行命令。\n\n#### 默认配置\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"workspace\": \"~/.picoclaw/workspace\",\n \"restrict_to_workspace\": true\n }\n }\n}\n```\n\n| 选项 | 默认值 | 描述 |\n| ----------------------- | ----------------------- | ----------------------------- |\n| `workspace` | `~/.picoclaw/workspace` | Agent 的工作目录 |\n| `restrict_to_workspace` | `true` | 限制文件/命令访问在工作区内 |\n\n#### 受保护的工具\n\n当 `restrict_to_workspace: true` 时，以下工具会被沙箱化：\n\n| 工具 | 功能 | 限制 |\n| ------------- | ------------ | ------------------------------ |\n| `read_file` | 读取文件 | 仅限工作区内的文件 |\n| `write_file` | 写入文件 | 仅限工作区内的文件 |\n| `list_dir` | 列出目录 | 仅限工作区内的目录 |\n| `edit_file` | 编辑文件 | 仅限工作区内的文件 |\n| `append_file` | 追加文件 | 仅限工作区内的文件 |\n| `exec` | 执行命令 | 命令路径必须在工作区内 |\n\n#### 额外的 Exec 保护\n\n即使 `restrict_to_workspace: false`，`exec` 工具也会阻止以下危险命令：\n\n* `rm -rf`、`del /f`、`rmdir /s` — 批量删除\n* `format`、`mkfs`、`diskpart` — 磁盘格式化\n* `dd if=` — 磁盘镜像\n* 写入 `/dev/sd[a-z]` — 直接磁盘写入\n* `shutdown`、`reboot`、`poweroff` — 系统关机\n* Fork bomb `:(){ :|:& };:`\n\n### 文件访问控制\n\n| 配置键 | 类型 | 默认值 | 描述 |\n|--------|------|--------|------|\n| `tools.allow_read_paths` | string[] | `[]` | 允许在工作区外读取的额外路径 |\n| `tools.allow_write_paths` | string[] | `[]` | 允许在工作区外写入的额外路径 |\n\n### Exec 安全配置\n\n| 配置键 | 类型 | 默认值 | 描述 |\n|--------|------|--------|------|\n| `tools.exec.allow_remote` | bool | `false` | 允许从远程渠道（Telegram/Discord 等）执行 exec 工具 |\n| `tools.exec.enable_deny_patterns` | bool | `true` | 启用危险命令拦截 |\n| `tools.exec.custom_deny_patterns` | string[] | `[]` | 自定义阻止的正则表达式模式 |\n| `tools.exec.custom_allow_patterns` | string[] | `[]` | 自定义允许的正则表达式模式 |\n\n> **安全提示：** Symlink 保护默认启用——所有文件路径在白名单匹配前都会通过 `filepath.EvalSymlinks` 解析，防止符号链接逃逸攻击。\n\n#### 已知限制：构建工具的子进程\n\nexec 安全守卫仅检查 PicoClaw 直接启动的命令行。它不会递归检查由 `make`、`go run`、`cargo`、`npm run` 或自定义构建脚本等开发工具产生的子进程。\n\n这意味着顶层命令通过初始守卫检查后，仍可以编译或启动其他二进制文件。实际上，应将构建脚本、Makefile、包脚本和生成的二进制文件视为与直接 shell 命令同等级别的可执行代码进行审查。\n\n对于高风险环境：\n\n* 执行前审查构建脚本。\n* 对编译并运行的工作流优先使用审批/手动审查。\n* 如果需要比内置守卫更强的隔离，请在容器或虚拟机中运行 PicoClaw。\n\n#### 错误示例\n\n```\n[ERROR] tool: Tool execution failed\n{tool=exec, error=Command blocked by safety guard (path outside working dir)}\n```\n\n```\n[ERROR] tool: Tool execution failed\n{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}\n```\n\n#### 禁用限制（安全风险）\n\n如果需要 Agent 访问工作区外的路径：\n\n**方法 1: 配置文件**\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"restrict_to_workspace\": false\n }\n }\n}\n```\n\n**方法 2: 环境变量**\n\n```bash\nexport PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false\n```\n\n> ⚠️ **警告**: 禁用此限制将允许 Agent 访问系统上的任何路径。仅在受控环境中谨慎使用。\n\n#### 安全边界一致性\n\n`restrict_to_workspace` 设置在所有执行路径中一致应用：\n\n| 执行路径 | 安全边界 |\n| ---------------- | ---------------------------- |\n| 主 Agent | `restrict_to_workspace` ✅ |\n| 子 Agent / Spawn | 继承相同限制 ✅ |\n| 心跳任务 | 继承相同限制 ✅ |\n\n所有路径共享相同的工作区限制——无法通过子 Agent 或定时任务绕过安全边界。\n\n### 心跳 / 周期性任务 (Heartbeat)\n\nPicoClaw 可以自动执行周期性任务。在工作区创建 `HEARTBEAT.md` 文件：\n\n```markdown\n# Periodic Tasks\n\n- Check my email for important messages\n- Review my calendar for upcoming events\n- Check the weather forecast\n```\n\nAgent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具执行任务。\n\n#### 使用 Spawn 的异步任务\n\n对于耗时较长的任务（网络搜索、API 调用），使用 `spawn` 工具创建一个 **子 Agent (subagent)**：\n\n```markdown\n# Periodic Tasks\n\n## Quick Tasks (respond directly)\n\n- Report current time\n\n## Long Tasks (use spawn for async)\n\n- Search the web for AI news and summarize\n- Check email and report important messages\n```\n\n**关键行为：**\n\n| 特性 | 描述 |\n| ---------------- | ---------------------------------------- |\n| **spawn** | 创建异步子 Agent，不阻塞主心跳进程 |\n| **独立上下文** | 子 Agent 拥有独立上下文，无会话历史 |\n| **message tool** | 子 Agent 通过 message 工具直接与用户通信 |\n| **非阻塞** | spawn 后，心跳继续处理下一个任务 |\n\n**配置：**\n\n```json\n{\n \"heartbeat\": {\n \"enabled\": true,\n \"interval\": 30\n }\n}\n```\n\n| 选项 | 默认值 | 描述 |\n| ---------- | ------ | ---------------------------- |\n| `enabled` | `true` | 启用/禁用心跳 |\n| `interval` | `30` | 检查间隔，单位分钟 (最小: 5) |\n\n**环境变量:**\n\n- `PICOCLAW_HEARTBEAT_ENABLED=false` 禁用\n- `PICOCLAW_HEARTBEAT_INTERVAL=60` 更改间隔\n\n#### 子 Agent 通信流程\n\n```\n心跳触发\n ↓\nAgent 读取 HEARTBEAT.md\n ↓\n遇到耗时任务：spawn 子 Agent\n ↓ ↓\n继续处理下一个任务 子 Agent 独立运行\n ↓ ↓\n所有任务完成 子 Agent 使用 \"message\" 工具\n ↓ ↓\n回复 HEARTBEAT_OK 用户直接收到结果\n```\n\n子 Agent 拥有工具访问权限（message、web_search 等），可以独立与用户通信，无需经过主 Agent。\n\n### Providers（模型提供商）\n\n> [!NOTE]\n> Groq 通过 Whisper 提供免费语音转录。配置后，任意渠道的语音消息都会在 Agent 层自动转录为文字。\n\n| 提供商 | 用途 | 获取 API Key |\n| ------------ | --------------------------------------- | ------------------------------------------------------------ |\n| `gemini` | LLM（Gemini 直连） | [aistudio.google.com](https://aistudio.google.com) |\n| `zhipu` | LLM（智谱直连） | [bigmodel.cn](https://bigmodel.cn) |\n| `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) |\n| `openrouter` | LLM（推荐，可访问所有模型） | [openrouter.ai](https://openrouter.ai) |\n| `anthropic` | LLM（Claude 直连） | [console.anthropic.com](https://console.anthropic.com) |\n| `openai` | LLM（GPT 直连） | [platform.openai.com](https://platform.openai.com) |\n| `deepseek` | LLM（DeepSeek 直连） | [platform.deepseek.com](https://platform.deepseek.com) |\n| `qwen` | LLM（通义千问直连） | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |\n| `groq` | LLM + **语音转录**（Whisper） | [console.groq.com](https://console.groq.com) |\n| `cerebras` | LLM（Cerebras 直连） | [cerebras.ai](https://cerebras.ai) |\n| `vivgrid` | LLM（Vivgrid 直连） | [vivgrid.com](https://vivgrid.com) |\n\n### 模型配置 (model_list)\n\n> **新特性：** PicoClaw 现在采用**以模型为中心**的配置方式。只需指定 `vendor/model` 格式（例如 `zhipu/glm-4.7`）即可接入新提供商——**无需修改任何代码！**\n\n这一设计同时支持**多 Agent**场景，灵活选择提供商：\n\n- **不同 Agent 使用不同提供商**：每个 Agent 可以使用独立的 LLM 提供商\n- **模型降级**：配置主模型和备用模型，提升可用性\n- **负载均衡**：将请求分发到多个端点\n- **集中管理**：在一处管理所有提供商配置\n\n#### 所有支持的厂商\n\n| 厂商 | `model` 前缀 | 默认 API Base | 协议 | API Key |\n| ----------------------- | ----------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |\n| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [获取](https://platform.openai.com) |\n| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [获取](https://console.anthropic.com) |\n| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [获取](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |\n| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [获取](https://platform.deepseek.com) |\n| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [获取](https://aistudio.google.com/api-keys) |\n| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [获取](https://console.groq.com) |\n| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [获取](https://platform.moonshot.cn) |\n| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [获取](https://dashscope.console.aliyun.com) |\n| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [获取](https://build.nvidia.com) |\n| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | 本地（无需 Key） |\n| **LM Studio** | `lmstudio/` | `http://localhost:1234/v1` | OpenAI | 可选（本地默认无需密钥） |\n| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [获取](https://openrouter.ai/keys) |\n| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | 你的 LiteLLM 代理 Key |\n| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | 本地 |\n| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [获取](https://cerebras.ai) |\n| **火山引擎 (豆包)** | `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) |\n| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | — |\n| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [获取](https://www.byteplus.com) |\n| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [获取](https://vivgrid.com) |\n| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [获取](https://longcat.chat/platform) |\n| **ModelScope (魔搭)** | `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [获取](https://modelscope.cn/my/tokens) |\n| **Antigravity** | `antigravity/` | Google Cloud | Custom | 仅 OAuth |\n| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | — |\n\n#### 基础配置\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-your-api-key\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-your-openai-key\"]\n },\n {\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"api_keys\": [\"sk-ant-your-key\"]\n },\n {\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-zhipu-key\"]\n }\n ],\n \"agents\": {\n \"defaults\": {\n \"model\": \"gpt-5.4\"\n }\n }\n}\n```\n\n#### 各厂商配置示例\n\n<details>\n<summary><b>OpenAI</b></summary>\n\n```json\n{\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n</details>\n\n<details>\n<summary><b>火山引擎（豆包）</b></summary>\n\n```json\n{\n \"model_name\": \"ark-code-latest\",\n \"model\": \"volcengine/ark-code-latest\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n</details>\n\n<details>\n<summary><b>智谱 AI (GLM)</b></summary>\n\n```json\n{\n \"model_name\": \"glm-4.7\",\n \"model\": \"zhipu/glm-4.7\",\n \"api_keys\": [\"your-key\"]\n}\n```\n\n</details>\n\n<details>\n<summary><b>DeepSeek</b></summary>\n\n```json\n{\n \"model_name\": \"deepseek-chat\",\n \"model\": \"deepseek/deepseek-chat\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\n</details>\n\n<details>\n<summary><b>Anthropic</b></summary>\n\n```json\n{\n \"model_name\": \"claude-sonnet-4.6\",\n \"model\": \"anthropic/claude-sonnet-4.6\",\n \"api_keys\": [\"sk-ant-your-key\"]\n}\n```\n\n> 运行 `picoclaw auth login --provider anthropic` 粘贴 API Token。\n\n如需直连 Anthropic 原生接口（不兼容 OpenAI 格式的端点）：\n\n```json\n{\n \"model_name\": \"claude-opus-4-6\",\n \"model\": \"anthropic-messages/claude-opus-4-6\",\n \"api_keys\": [\"sk-ant-your-key\"],\n \"api_base\": \"https://api.anthropic.com\"\n}\n```\n\n> 当端点不支持 OpenAI 兼容格式（`/v1/chat/completions`），需要 Anthropic 原生 `/v1/messages` 时使用 `anthropic-messages`。\n\n</details>\n\n<details>\n<summary><b>Ollama（本地）</b></summary>\n\n```json\n{\n \"model_name\": \"llama3\",\n \"model\": \"ollama/llama3\"\n}\n```\n\n</details>\n\n<details>\n<summary><b>LM Studio（本地）</b></summary>\n\n```json\n{\n \"model_name\": \"lmstudio-local\",\n \"model\": \"lmstudio/openai/gpt-oss-20b\"\n}\n```\n\n`api_base` 默认是 `http://localhost:1234/v1`。除非你在 LM Studio 侧启用了认证，否则不需要配置 API Key。\nPicoClaw 向 LM Studio 的 OpenAI 兼容终结点发送请求，且将移除首个 `lmstudio/` 前缀，因此 `lmstudio/openai/gpt-oss-20b` 会发送 `openai/gpt-oss-20b`。\n\n</details>\n\n<details>\n<summary><b>自定义代理 / LiteLLM</b></summary>\n\n```json\n{\n \"model_name\": \"my-custom-model\",\n \"model\": \"openai/custom-model\",\n \"api_base\": \"https://my-proxy.com/v1\",\n \"api_keys\": [\"sk-...\"]\n}\n```\n\nPicoClaw 只剥离最外层的 `litellm/` 前缀再发送请求，因此 `litellm/lite-gpt4` 发送 `lite-gpt4`，而 `litellm/openai/gpt-4o` 发送 `openai/gpt-4o`。\n\n</details>\n\n#### 负载均衡\n\n为同一模型名称配置多个端点，PicoClaw 会自动轮询：\n\n```json\n{\n \"model_list\": [\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api1.example.com/v1\",\n \"api_keys\": [\"sk-key1\"]\n },\n {\n \"model_name\": \"gpt-5.4\",\n \"model\": \"openai/gpt-5.4\",\n \"api_base\": \"https://api2.example.com/v1\",\n \"api_keys\": [\"sk-key2\"]\n }\n ]\n}\n```\n\n#### 从旧版 `providers` 配置迁移\n\n旧版 `providers` 配置**已废弃**，V2 中已移除。现有 V0/V1 配置会自动迁移。完整迁移指南见 [docs/migration/model-list-migration.md](../migration/model-list-migration.md)。\n\n### Provider 架构\n\nPicoClaw 按协议族路由提供商：\n\n- **OpenAI 兼容**：OpenRouter、Groq、智谱、vLLM 风格端点及大多数其他提供商。\n- **Anthropic**：Claude 原生 API 行为。\n- **Codex/OAuth**：OpenAI OAuth/Token 认证路由。\n\n这使运行时保持轻量，同时让接入新的 OpenAI 兼容后端基本只需配置 `api_base` + `api_key`。\n\n<details>\n<summary><b>智谱（旧版 providers 格式）</b></summary>\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"workspace\": \"~/.picoclaw/workspace\",\n \"model\": \"glm-4.7\",\n \"max_tokens\": 8192,\n \"temperature\": 0.7,\n \"max_tool_iterations\": 20\n }\n },\n \"providers\": {\n \"zhipu\": {\n \"api_key\": \"Your API Key\",\n \"api_base\": \"https://open.bigmodel.cn/api/paas/v4\"\n }\n }\n}\n```\n\n</details>\n\n<details>\n<summary><b>完整配置示例</b></summary>\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\"\n }\n },\n \"session\": {\n \"dm_scope\": \"per-channel-peer\",\n \"backlog_limit\": 20\n },\n \"providers\": {\n \"openrouter\": {\n \"api_key\": \"sk-or-v1-xxx\"\n },\n \"groq\": {\n \"api_key\": \"gsk_xxx\"\n }\n },\n \"channels\": {\n \"telegram\": {\n \"enabled\": true,\n \"token\": \"123456:ABC...\",\n \"allow_from\": [\"123456789\"]\n }\n },\n \"tools\": {\n \"web\": {\n \"duckduckgo\": {\n \"enabled\": true,\n \"max_results\": 5\n }\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"interval\": 30\n }\n}\n```\n\n</details>\n\n### 定时任务 / 提醒\n\nPicoClaw 通过 `cron` 工具支持 cron 风格的定时任务。Agent 可以设置、列出和取消在指定时间触发的提醒或周期性任务。\n\n```json\n{\n \"tools\": {\n \"cron\": {\n \"enabled\": true,\n \"exec_timeout_minutes\": 5\n }\n }\n}\n```\n\n定时任务在重启后持久保存，存储于 `~/.picoclaw/workspace/cron/`。\n\n### 进阶主题\n\n| 主题 | 说明 |\n| ---- | ---- |\n| [敏感数据过滤](../sensitive_data_filtering.md) | 在发送给 LLM 前，从工具结果中过滤 API 密钥和令牌 |\n| [Hook 系统](../hooks/README.zh.md) | 事件驱动 Hook：观察者、拦截器、审批 Hook |\n| [Steering](../steering.md) | 在工具调用间向运行中的 Agent 注入消息 |\n| [SubTurn](../subturn.md) | 子 Agent 协调、并发控制、生命周期管理 |\n| [上下文管理](../agent-refactor/context.md) | 上下文边界检测、主动预算检查、压缩策略 |\n"}}}} |