Merge pull request #2766 from SiYue-ZO/docs/v3-config-format-sync

docs: sync all documentation to V3 config format
This commit is contained in:
美電球
2026-05-15 22:06:08 +08:00
committed by GitHub
26 changed files with 187 additions and 132 deletions
+137 -90
View File
@@ -1,4 +1,5 @@
{
"version": 3,
"agents": {
"defaults": {
"workspace": "~/.picoclaw/workspace",
@@ -33,13 +34,13 @@
{
"model_name": "gpt-5.4",
"model": "openai/gpt-5.4",
"api_key": "sk-your-openai-key",
"api_keys": ["sk-your-openai-key"],
"api_base": "https://api.openai.com/v1"
},
{
"model_name": "claude-sonnet-4.6",
"model": "anthropic/claude-sonnet-4.6",
"api_key": "sk-ant-your-key",
"api_keys": ["sk-ant-your-key"],
"api_base": "https://api.anthropic.com/v1",
"thinking_level": "high"
},
@@ -47,7 +48,7 @@
"_comment": "Anthropic Messages API - use native format for direct Anthropic API access",
"model_name": "claude-opus-4-6",
"model": "anthropic-messages/claude-opus-4-6",
"api_key": "sk-ant-your-key",
"api_keys": ["sk-ant-your-key"],
"api_base": "https://api.anthropic.com"
},
{
@@ -59,12 +60,12 @@
{
"model_name": "deepseek",
"model": "deepseek/deepseek-chat",
"api_key": "sk-your-deepseek-key"
"api_keys": ["sk-your-deepseek-key"]
},
{
"model_name": "venice-uncensored",
"model": "venice/venice-uncensored",
"api_key": "your-venice-api-key"
"api_keys": ["your-venice-api-key"]
},
{
"model_name": "lmstudio-local",
@@ -73,114 +74,134 @@
{
"model_name": "longcat",
"model": "longcat/LongCat-Flash-Thinking",
"api_key": "your-longcat-api-key"
"api_keys": ["your-longcat-api-key"]
},
{
"model_name": "modelscope-qwen",
"model": "modelscope/Qwen/Qwen3-235B-A22B-Instruct-2507",
"api_key": "your-modelscope-access-token",
"api_keys": ["your-modelscope-access-token"],
"api_base": "https://api-inference.modelscope.cn/v1"
},
{
"model_name": "azure-gpt5",
"model": "azure/my-gpt5-deployment",
"api_key": "your-azure-api-key",
"api_keys": ["your-azure-api-key"],
"api_base": "https://your-resource.openai.azure.com"
},
{
"model_name": "loadbalanced-gpt-5.4",
"model": "openai/gpt-5.4",
"api_key": "sk-key1",
"api_keys": ["sk-key1"],
"api_base": "https://api1.example.com/v1"
},
{
"model_name": "loadbalanced-gpt-5.4",
"model": "openai/gpt-5.4",
"api_key": "sk-key2",
"api_keys": ["sk-key2"],
"api_base": "https://api2.example.com/v1"
}
],
"channels": {
"channel_list": {
"telegram": {
"enabled": false,
"token": "YOUR_TELEGRAM_BOT_TOKEN",
"base_url": "",
"proxy": "",
"type": "telegram",
"allow_from": ["YOUR_USER_ID"],
"use_markdown_v2": false,
"reasoning_channel_id": "",
"streaming": {
"enabled": true
"settings": {
"token": "YOUR_TELEGRAM_BOT_TOKEN",
"base_url": "",
"proxy": "",
"use_markdown_v2": false,
"streaming": {
"enabled": true
}
}
},
"discord": {
"enabled": false,
"token": "YOUR_DISCORD_BOT_TOKEN",
"proxy": "",
"type": "discord",
"allow_from": [],
"group_trigger": {
"mention_only": false
},
"reasoning_channel_id": ""
"reasoning_channel_id": "",
"settings": {
"token": "YOUR_DISCORD_BOT_TOKEN",
"proxy": ""
}
},
"qq": {
"enabled": false,
"app_id": "YOUR_QQ_APP_ID",
"app_secret": "YOUR_QQ_APP_SECRET",
"type": "qq",
"allow_from": [],
"reasoning_channel_id": ""
"reasoning_channel_id": "",
"settings": {
"app_id": "YOUR_QQ_APP_ID",
"app_secret": "YOUR_QQ_APP_SECRET"
}
},
"maixcam": {
"enabled": false,
"host": "0.0.0.0",
"port": 18790,
"type": "maixcam",
"allow_from": [],
"reasoning_channel_id": ""
"reasoning_channel_id": "",
"settings": {
"host": "0.0.0.0",
"port": 18790
}
},
"whatsapp": {
"enabled": false,
"bridge_url": "ws://localhost:3001",
"use_native": false,
"session_store_path": "",
"type": "whatsapp",
"allow_from": [],
"reasoning_channel_id": ""
"reasoning_channel_id": "",
"settings": {
"bridge_url": "ws://localhost:3001",
"use_native": false,
"session_store_path": ""
}
},
"feishu": {
"enabled": false,
"app_id": "",
"app_secret": "",
"encrypt_key": "",
"verification_token": "",
"type": "feishu",
"allow_from": [],
"reasoning_channel_id": "",
"placeholder": {
"enabled": true,
"text": ["Thinking...", "Processing...", "Typing..."]
},
"reasoning_channel_id": "",
"random_reaction_emoji": [],
"is_lark": false
"settings": {
"app_id": "",
"app_secret": "",
"encrypt_key": "",
"verification_token": "",
"random_reaction_emoji": [],
"is_lark": false
}
},
"dingtalk": {
"enabled": false,
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"type": "dingtalk",
"allow_from": [],
"reasoning_channel_id": ""
"reasoning_channel_id": "",
"settings": {
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}
},
"slack": {
"enabled": false,
"bot_token": "xoxb-YOUR-BOT-TOKEN",
"app_token": "xapp-YOUR-APP-TOKEN",
"type": "slack",
"allow_from": [],
"reasoning_channel_id": ""
"reasoning_channel_id": "",
"settings": {
"bot_token": "xoxb-YOUR-BOT-TOKEN",
"app_token": "xapp-YOUR-APP-TOKEN"
}
},
"matrix": {
"enabled": false,
"homeserver": "https://matrix.org",
"user_id": "@your-bot:matrix.org",
"access_token": "YOUR_MATRIX_ACCESS_TOKEN",
"device_id": "",
"join_on_invite": true,
"type": "matrix",
"allow_from": [],
"group_trigger": {
"mention_only": true
@@ -190,68 +211,82 @@
"text": ["Thinking...", "Processing...", "Typing..."]
},
"reasoning_channel_id": "",
"crypto_database_path": "",
"crypto_passphrase": "YOUR_MATRIX_CRYPTO_PICKLE_KEY"
"settings": {
"homeserver": "https://matrix.org",
"user_id": "@your-bot:matrix.org",
"access_token": "YOUR_MATRIX_ACCESS_TOKEN",
"device_id": "",
"join_on_invite": true,
"crypto_database_path": "",
"crypto_passphrase": "YOUR_MATRIX_CRYPTO_PICKLE_KEY"
}
},
"line": {
"enabled": false,
"channel_secret": "YOUR_LINE_CHANNEL_SECRET",
"channel_access_token": "YOUR_LINE_CHANNEL_ACCESS_TOKEN",
"webhook_path": "/webhook/line",
"type": "line",
"allow_from": [],
"reasoning_channel_id": ""
"reasoning_channel_id": "",
"settings": {
"channel_secret": "YOUR_LINE_CHANNEL_SECRET",
"channel_access_token": "YOUR_LINE_CHANNEL_ACCESS_TOKEN",
"webhook_path": "/webhook/line"
}
},
"onebot": {
"enabled": false,
"ws_url": "ws://127.0.0.1:3001",
"access_token": "",
"reconnect_interval": 5,
"group_trigger_prefix": [],
"type": "onebot",
"allow_from": [],
"reasoning_channel_id": ""
"reasoning_channel_id": "",
"group_trigger": {
"prefixes": []
},
"settings": {
"ws_url": "ws://127.0.0.1:3001",
"access_token": "",
"reconnect_interval": 5
}
},
"wecom": {
"_comment": "WeCom AI Bot over WebSocket.",
"enabled": false,
"bot_id": "YOUR_BOT_ID",
"secret": "YOUR_SECRET",
"websocket_url": "wss://openws.work.weixin.qq.com",
"send_thinking_message": true,
"type": "wecom",
"allow_from": [],
"reasoning_channel_id": ""
"reasoning_channel_id": "",
"settings": {
"bot_id": "YOUR_BOT_ID",
"secret": "YOUR_SECRET",
"websocket_url": "wss://openws.work.weixin.qq.com",
"send_thinking_message": true
}
},
"pico": {
"enabled": false,
"token": "YOUR_PICO_TOKEN",
"allow_token_query": false,
"allow_origins": [],
"ping_interval": 30,
"read_timeout": 60,
"max_connections": 100,
"allow_from": []
"type": "pico",
"allow_from": [],
"settings": {
"token": "YOUR_PICO_TOKEN",
"allow_token_query": false,
"allow_origins": [],
"ping_interval": 30,
"read_timeout": 60,
"max_connections": 100
}
},
"pico_client": {
"enabled": false,
"url": "wss://remote-pico-server/pico/ws",
"token": "YOUR_PICO_TOKEN",
"session_id": "",
"ping_interval": 30,
"read_timeout": 60,
"allow_from": []
"type": "pico_client",
"allow_from": [],
"settings": {
"url": "wss://remote-pico-server/pico/ws",
"token": "YOUR_PICO_TOKEN",
"session_id": "",
"ping_interval": 30,
"read_timeout": 60
}
},
"irc": {
"enabled": false,
"server": "irc.libera.chat:6697",
"tls": true,
"nick": "mybot",
"user": "",
"real_name": "",
"password": "",
"nickserv_password": "",
"sasl_user": "",
"sasl_password": "",
"channels": ["#mychannel"],
"request_caps": ["server-time", "message-tags"],
"type": "irc",
"allow_from": [],
"group_trigger": {
"mention_only": true
@@ -259,7 +294,20 @@
"typing": {
"enabled": false
},
"reasoning_channel_id": ""
"reasoning_channel_id": "",
"settings": {
"server": "irc.libera.chat:6697",
"tls": true,
"nick": "mybot",
"user": "",
"real_name": "",
"password": "",
"nickserv_password": "",
"sasl_user": "",
"sasl_password": "",
"channels": ["#mychannel"],
"request_caps": ["server-time", "message-tags"]
}
}
},
"tools": {
@@ -268,7 +316,6 @@
"web": {
"enabled": true,
"prefer_native": true,
"fetch_limit_bytes": 10485760,
"format": "plaintext",
"brave": {
"enabled": false,
+5 -5
View File
@@ -78,17 +78,17 @@ Inspired by [LiteLLM](https://docs.litellm.ai/docs/proxy/configs) design:
"model_name": "deepseek-chat",
"model": "openai/deepseek-chat",
"api_base": "https://api.deepseek.com/v1",
"api_key": "sk-xxx"
"api_keys": ["sk-xxx"]
},
{
"model_name": "gpt-5.4",
"model": "openai/gpt-5.4",
"api_key": "sk-xxx"
"api_keys": ["sk-xxx"]
},
{
"model_name": "claude-sonnet-4.6",
"model": "anthropic/claude-sonnet-4.6",
"api_key": "sk-xxx"
"api_keys": ["sk-xxx"]
},
{
"model_name": "gemini-3-flash",
@@ -99,7 +99,7 @@ Inspired by [LiteLLM](https://docs.litellm.ai/docs/proxy/configs) design:
"model_name": "my-company-llm",
"model": "openai/company-model-v1",
"api_base": "https://llm.company.com/v1",
"api_key": "xxx"
"api_keys": ["xxx"]
}
],
@@ -252,7 +252,7 @@ func (c *Config) GetModelConfig(modelName string) (*ModelConfig, error) {
{
"providers": {
"deepseek": {
"api_key": "sk-xxx",
"api_keys": ["sk-xxx"],
"api_base": "https://api.deepseek.com/v1"
}
},
+2 -1
View File
@@ -354,6 +354,7 @@ Cela crée `~/.picoclaw/config.json` et le répertoire workspace.
```json
{
"version": 3,
"agents": {
"defaults": {
"model_name": "gpt-5.4"
@@ -363,7 +364,7 @@ Cela crée `~/.picoclaw/config.json` et le répertoire workspace.
{
"model_name": "gpt-5.4",
"model": "openai/gpt-5.4",
"api_key": "sk-your-api-key"
"api_keys": ["sk-your-api-key"]
}
]
}
+2 -1
View File
@@ -350,6 +350,7 @@ Ini membuat `~/.picoclaw/config.json` dan direktori workspace.
```json
{
"version": 3,
"agents": {
"defaults": {
"model_name": "gpt-5.4"
@@ -359,7 +360,7 @@ Ini membuat `~/.picoclaw/config.json` dan direktori workspace.
{
"model_name": "gpt-5.4",
"model": "openai/gpt-5.4",
"api_key": "sk-your-api-key"
"api_keys": ["sk-your-api-key"]
}
]
}
+2 -1
View File
@@ -350,6 +350,7 @@ Questo crea `~/.picoclaw/config.json` e la directory workspace.
```json
{
"version": 3,
"agents": {
"defaults": {
"model_name": "gpt-5.4"
@@ -359,7 +360,7 @@ Questo crea `~/.picoclaw/config.json` e la directory workspace.
{
"model_name": "gpt-5.4",
"model": "openai/gpt-5.4",
"api_key": "sk-your-api-key"
"api_keys": ["sk-your-api-key"]
}
]
}
+2 -1
View File
@@ -351,6 +351,7 @@ picoclaw onboard
```json
{
"version": 3,
"agents": {
"defaults": {
"model_name": "gpt-5.4"
@@ -360,7 +361,7 @@ picoclaw onboard
{
"model_name": "gpt-5.4",
"model": "openai/gpt-5.4",
"api_key": "sk-your-api-key"
"api_keys": ["sk-your-api-key"]
}
]
}
+2 -1
View File
@@ -351,6 +351,7 @@ Isso cria `~/.picoclaw/config.json` e o diretório workspace.
```json
{
"version": 3,
"agents": {
"defaults": {
"model_name": "gpt-5.4"
@@ -360,7 +361,7 @@ Isso cria `~/.picoclaw/config.json` e o diretório workspace.
{
"model_name": "gpt-5.4",
"model": "openai/gpt-5.4",
"api_key": "sk-your-api-key"
"api_keys": ["sk-your-api-key"]
}
]
}
+2 -1
View File
@@ -351,6 +351,7 @@ Lệnh này tạo `~/.picoclaw/config.json` và thư mục workspace.
```json
{
"version": 3,
"agents": {
"defaults": {
"model_name": "gpt-5.4"
@@ -360,7 +361,7 @@ Lệnh này tạo `~/.picoclaw/config.json` và thư mục workspace.
{
"model_name": "gpt-5.4",
"model": "openai/gpt-5.4",
"api_key": "sk-your-api-key"
"api_keys": ["sk-your-api-key"]
}
]
}
+2 -1
View File
@@ -351,6 +351,7 @@ picoclaw onboard
```json
{
"version": 3,
"agents": {
"defaults": {
"model_name": "gpt-5.4"
@@ -360,7 +361,7 @@ picoclaw onboard
{
"model_name": "gpt-5.4",
"model": "openai/gpt-5.4",
"api_key": "sk-your-api-key"
"api_keys": ["sk-your-api-key"]
}
]
}
+9 -8
View File
@@ -45,7 +45,8 @@ When you load a config file:
The `version` field in `config.json` indicates the schema version:
- `0` or missing: Legacy config (no version field)
- `1`: Previous version (will be auto-migrated to V2 on load)
- `2`: Current version
- `2`: Previous version (will be auto-migrated to V3 on load)
- `3`: Current version
```json
{
@@ -64,8 +65,8 @@ When making breaking changes to the config schema:
Create a new struct for the new version if the structure changes significantly:
```go
// ConfigV2 represents version 2 config structure
type ConfigV2 struct {
// ConfigV3 represents version 3 config structure
type ConfigV3 struct {
Version int `json:"version"`
Agents AgentsConfig `json:"agents"`
// ... other fields with new structure
@@ -75,7 +76,7 @@ type ConfigV2 struct {
### Step 2: Update Current Config Version
```go
const CurrentVersion = 2 // Increment this
const CurrentVersion = 3 // Increment this
```
### Step 3: Add a Loader Function
@@ -141,9 +142,9 @@ Create a test in `config_migration_test.go`:
```go
func TestMigrateV2ToV3(t *testing.T) {
// Create a version 2 config
v2Config := Config{
Version: 2,
// Create a version 3 config
v3Config := Config{
Version: 3,
// ... set up test data
}
@@ -224,7 +225,7 @@ Backups are created in the same directory as your config file:
### Scenario: Adding a new field with default value
Old config (version 2):
Old config (version 3):
```json
{
"version": 3,
+2 -2
View File
@@ -691,7 +691,7 @@ case "your-provider":
{
"model_name": "your-model",
"model": "your-provider/model-name",
"api_key": "your-api-key",
"api_keys": ["your-api-key"],
"api_base": "https://api.your-provider.com/v1"
}
]
@@ -725,7 +725,7 @@ picoclaw agent -m "Hello" --model your-model
export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
# Remplacer les paramètres du fournisseur
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_keys":["..."]}]'
```
---
+2 -2
View File
@@ -691,7 +691,7 @@ case "your-provider":
{
"model_name": "your-model",
"model": "your-provider/model-name",
"api_key": "your-api-key",
"api_keys": ["your-api-key"],
"api_base": "https://api.your-provider.com/v1"
}
]
@@ -725,7 +725,7 @@ picoclaw agent -m "Hello" --model your-model
export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
# プロバイダー設定の上書き
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_keys":["..."]}]'
```
---
+2 -2
View File
@@ -689,7 +689,7 @@ case "your-provider":
{
"model_name": "your-model",
"model": "your-provider/model-name",
"api_key": "your-api-key",
"api_keys": ["your-api-key"],
"api_base": "https://api.your-provider.com/v1"
}
]
@@ -723,7 +723,7 @@ picoclaw agent -m "Hello" --model your-model
export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
# Override provider settings
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_keys":["..."]}]'
```
---
+2 -2
View File
@@ -691,7 +691,7 @@ case "your-provider":
{
"model_name": "your-model",
"model": "your-provider/model-name",
"api_key": "your-api-key",
"api_keys": ["your-api-key"],
"api_base": "https://api.your-provider.com/v1"
}
]
@@ -725,7 +725,7 @@ picoclaw agent -m "Hello" --model your-model
export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
# Substituir configurações do provedor
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_keys":["..."]}]'
```
---
+2 -2
View File
@@ -691,7 +691,7 @@ case "your-provider":
{
"model_name": "your-model",
"model": "your-provider/model-name",
"api_key": "your-api-key",
"api_keys": ["your-api-key"],
"api_base": "https://api.your-provider.com/v1"
}
]
@@ -725,7 +725,7 @@ picoclaw agent -m "Hello" --model your-model
export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
# Ghi đè cài đặt nhà cung cấp
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_keys":["..."]}]'
```
---
+2 -2
View File
@@ -691,7 +691,7 @@ case "your-provider":
{
"model_name": "your-model",
"model": "your-provider/model-name",
"api_key": "your-api-key",
"api_keys": ["your-api-key"],
"api_base": "https://api.your-provider.com/v1"
}
]
@@ -725,7 +725,7 @@ picoclaw agent -m "Hello" --model your-model
export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
# 覆盖提供商设置
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_keys":["..."]}]'
```
---
+1 -1
View File
@@ -33,7 +33,7 @@ enc://AAAA...base64...
{
"model_name": "gpt-4o",
"model": "openai/gpt-4o",
"api_key": "enc://AAAA...base64...",
"api_keys": ["enc://AAAA...base64..."],
"api_base": "https://api.openai.com/v1"
}
]
+1 -1
View File
@@ -32,7 +32,7 @@ enc://AAAA...base64...
{
"model_name": "gpt-4o",
"model": "openai/gpt-4o",
"api_key": "enc://AAAA...base64...",
"api_keys": ["enc://AAAA...base64..."],
"api_base": "https://api.openai.com/v1"
}
]
+1 -1
View File
@@ -31,7 +31,7 @@ enc://AAAA...base64...
{
"model_name": "gpt-4o",
"model": "openai/gpt-4o",
// "api_key": "enc://AAAA...base64..." move to .security.yml
// "api_keys": ["enc://AAAA...base64..."] move to .security.yml
"api_base": "https://api.openai.com/v1"
}
]
+1 -1
View File
@@ -33,7 +33,7 @@ enc://AAAA...base64...
{
"model_name": "gpt-4o",
"model": "openai/gpt-4o",
"api_key": "enc://AAAA...base64...",
"api_keys": ["enc://AAAA...base64..."],
"api_base": "https://api.openai.com/v1"
}
]
+1 -1
View File
@@ -33,7 +33,7 @@ enc://AAAA...base64...
{
"model_name": "gpt-4o",
"model": "openai/gpt-4o",
"api_key": "enc://AAAA...base64...",
"api_keys": ["enc://AAAA...base64..."],
"api_base": "https://api.openai.com/v1"
}
]
+1 -1
View File
@@ -32,7 +32,7 @@ enc://AAAA...base64...
{
"model_name": "gpt-4o",
"model": "openai/gpt-4o",
"api_key": "enc://AAAA...base64...",
"api_keys": ["enc://AAAA...base64..."],
"api_base": "https://api.openai.com/v1"
}
]
+1 -1
View File
@@ -152,7 +152,7 @@ You can now remove sensitive fields from `config.json` since they're loaded from
"model_name": "gpt-5.4",
"model": "openai/gpt-5.4",
"api_base": "https://api.openai.com/v1",
"api_key": "sk-your-actual-api-key-here"
"api_keys": ["sk-your-actual-api-key-here"]
}
],
"channel_list": {
+1 -1
View File
@@ -33,7 +33,7 @@ go run ./examples/pico-echo-server -addr :9090 -token secret
2. Configure `pico_client` in your `config.json`:
```json
{
"channels": {
"channel_list": {
"pico_client": {
"enabled": true,
"url": "ws://localhost:9090/ws",
+1 -1
View File
@@ -791,7 +791,7 @@ the top level, with channel-specific settings in the `settings` sub-key:
```json
{
"channels": {
"channel_list": {
"matrix": {
"enabled": true,
"type": "matrix",
+1 -1
View File
@@ -790,7 +790,7 @@ channel 特定的设置放在 `settings` 子键中:
```json
{
"channels": {
"channel_list": {
"matrix": {
"enabled": true,
"type": "matrix",