Picobot配置完全手册:config.json字段、环境变量与工作区文件逐条解析
Picobot配置完全手册:config.json字段、环境变量与工作区文件逐条解析
Picobot 是一款用 Go 编写的轻量级自托管 AI Bot,单个二进制文件即可运行,支持 Telegram、Discord、Slack、WhatsApp 四大聊天渠道。本文作为 Picobot 配置完全手册,逐条解析 config.json 全部字段、Docker 环境变量与工作区文件,帮新手快速完成 Picobot 配置。
一、Picobot 配置体系速览:一个 JSON + 一个工作区
Picobot 的所有配置集中在 一个 JSON 文件:~/.picobot/config.json(结构定义见 internal/config/schema.go)。首次运行 picobot onboard 即可自动生成默认配置与工作区,无需手写。
整个 config.json 只有 4 个顶级区块,职责清晰:
| 区块 | 作用 |
|---|---|
agents |
智能体行为:模型、超时、工具循环次数等 |
mcpServers |
挂载外部 MCP 工具服务 |
channels |
Telegram / Discord / Slack / WhatsApp 四大渠道 |
providers |
LLM API 密钥与地址 |
二、onboard 一键初始化:最快生成默认配置
拿到 Picobot 二进制后,第一条命令永远是它:
./picobot onboard # 生成 ~/.picobot/config.json + ~/.picobot/workspace
这条命令由 internal/config/onboard.go 实现,一次完成三件事:
- 写入带默认值的
config.json - 创建
~/.picobot/workspace工作区及 5 个引导文件(SOUL.md、AGENTS.md等) - 把内嵌的示例技能(embeds/skills/)释放到
workspace/skills/
💡 Docker 部署时同样支持"自动 onboard":容器首次启动发现没有配置时会自动执行 docker/entrypoint.sh,随后提示你补齐 API Key。
三、agents.defaults:智能体行为字段逐条解析
这是使用频率最高的一块,完整默认值可参考 docs/CONFIG.md。
| 字段 | 默认值 | 说明 |
|---|---|---|
workspace |
~/.picobot/workspace |
工作区路径,存放引导文件、记忆与技能 |
model |
stub-model |
默认模型,建议改成真实模型名,可被 -M 参数覆盖 |
maxTokens |
8192 |
LLM 单次回复的最大 token 数 |
temperature |
0.7 |
0.0 更确定、1.0 更有创意 |
maxToolIterations |
100 |
单次请求的工具调用上限,防止死循环 |
heartbeatIntervalS |
60 |
心跳检查间隔(秒),仅 gateway 模式生效 |
requestTimeoutS |
60 |
单次 LLM API 请求的 HTTP 超时(秒) |
agentTimeoutS |
300 |
一整轮智能体任务的墙钟超时(秒),0 时回退 300 |
enableToolActivityIndicator |
true |
工具调用时是否发送 🤖 进度提示,无头部署建议关 |
commands.deny |
[] |
额外禁止 exec 执行的程序名(大小写不敏感) |
模型解析优先级(从高到低):CLI 参数 -M → agents.defaults.model → Provider 默认值。
一个典型示例:
{
"agents": {
"defaults": {
"workspace": "/home/user/.picobot/workspace",
"model": "google/gemini-2.5-flash",
"maxTokens": 16384,
"temperature": 0.5,
"maxToolIterations": 200,
"requestTimeoutS": 120,
"commands": { "deny": ["curl", "chmod"] }
}
}
}
⚠️
commands.deny之外还有一份内置黑名单(rm、sudo、dd、mkfs、shutdown、reboot),不可关闭。
四、providers.openai:对接任意 OpenAI 兼容 API
Picobot 走 OpenAI 兼容协议,因此 OpenAI、OpenRouter、本地 Ollama 等都能接,只需两个字段:
| 字段 | 说明 |
|---|---|
apiKey |
必填。各家服务的 API Key |
apiBase |
默认指向 OpenRouter;接 OpenAI 改成 https://api.openai.com/v1,接本地 Ollama 改成 http://localhost:11434/v1 |
{
"providers": {
"openai": {
"apiKey": "sk-or-v1-your-key-here",
"apiBase": "https://openrouter.ai/api/v1"
}
}
}
兜底机制:如果没配置有效 Provider,Picobot 会退回 Stub 模式(把你的消息原样回显),方便离线测试连通性(实现见 internal/providers/stub.go)。
五、channels:四大聊天渠道配置详解
四个渠道默认 enabled: false,配置后 picobot gateway 长驻模式即可收发消息。
channels.telegram
| 字段 | 说明 |
|---|---|
token |
BotFather 签发的 Bot Token |
allowFrom |
允许对话的用户 ID 列表,留空 = 放行所有人 |
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456:ABC-DEF1234ghIkl",
"allowFrom": ["8881234567"]
}
}
}
channels.discord
字段与 Telegram 相同(token + allowFrom)。注意前置条件:在开发者后台开启 Message Content Intent,Bot 只需"发送消息"和"读取历史"权限。群内被 @ 或收到回复消息时才会应答,私聊则全量应答。
channels.slack
Slack 走 Socket Mode,因此需要 两个 Token,这也是它字段最多的原因:
| 字段 | 说明 |
|---|---|
appToken |
App-Level Token,以 xapp- 开头,用于建立 Socket 连接 |
botToken |
Bot Token,以 xoxb- 开头,用于发消息 |
allowUsers |
允许的用户 ID(U...),留空 = 全放行 |
allowChannels |
允许的频道 ID(C.../G.../D...),私聊不受此限制 |
App-Level Token 在 Slack 后台的 App-Level Tokens 页面生成(scope 选 connections:write):
Bot Token 在 OAuth & Permissions 页面获取,点击 Reinstall to My Workspace 后复制:
channels.whatsapp
WhatsApp 使用个人账号(基于 whatsmeow),字段最特殊:
| 字段 | 说明 |
|---|---|
dbPath |
SQLite 会话库路径,默认 ~/.picobot/whatsapp.db |
allowFrom |
允许发送的 LID 数字(不是手机号!) |
一次性扫码:picobot channels login 选 3) WhatsApp,手机在"已关联设备"扫码后,会话写入 dbPath,之后无需再扫。
🚨 最易踩的坑:新版 WhatsApp 内部用 LID 寻址。往
allowFrom填手机号,对方的消息会被静默丢弃。正确做法:让好友发条消息,Picobot 日志会打印dropped message from unauthorized sender xxxxx@lid,把日志里的数字填进去即可。
六、mcpServers:为 Picobot 挂载外部 MCP 工具
想给智能体加"超能力",直接挂 MCP 服务器即可。每个条目支持两种传输方式,同时配置时 command 优先:
| 传输 | 必填字段 | 适用场景 |
|---|---|---|
| Stdio | command + args |
本地进程:npx、uvx、二进制、docker |
| HTTP | url(可加 headers) |
远程托管服务,支持 Bearer Token |
{
"mcpServers": {
"via-npx": { "command": "npx", "args": ["-y", "@some/mcp-server"] },
"via-remote": { "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } }
}
}
两个实用细节:
- 工具会自动注册为
mcp_{server}_{tool},智能体像调用内置工具一样调用它(实现见 internal/agent/tools/mcp.go) - 某台服务器连接失败不会拖垮整个进程,Picobot 记录日志后继续启动
🐳 用 docker 跑 MCP 时,
args里务必带-i,否则 stdin 立即关闭会导致握手失败。
七、Docker 环境变量:不改文件的覆盖配置法
容器化部署时,docker/entrypoint.sh 会在启动时用 jq 把环境变量写回 config.json,因此环境变量与配置文件完全等价:
| 环境变量 | 对应配置路径 |
|---|---|
OPENAI_API_KEY |
providers.openai.apiKey |
OPENAI_API_BASE |
providers.openai.apiBase |
PICOBOT_MODEL |
agents.defaults.model |
PICOBOT_MAX_TOKENS |
agents.defaults.maxTokens |
PICOBOT_MAX_TOOL_ITERATIONS |
agents.defaults.maxToolIterations |
PICOBOT_AGENT_TIMEOUT_S |
agents.defaults.agentTimeoutS |
PICOBOT_ENABLE_TOOL_ACTIVITY_INDICATOR |
agents.defaults.enableToolActivityIndicator |
TELEGRAM_BOT_TOKEN / TELEGRAM_ALLOW_FROM |
channels.telegram.*(设置 token 会自动启用渠道) |
DISCORD_BOT_TOKEN / DISCORD_ALLOW_FROM |
channels.discord.* |
SLACK_APP_TOKEN / SLACK_BOT_TOKEN / SLACK_ALLOW_USERS / SLACK_ALLOW_CHANNELS |
channels.slack.* |
列表型变量(如 TELEGRAM_ALLOW_FROM)用 逗号分隔,脚本会自动转成 JSON 数组。参考示例见 docker/docker-compose.yml。
数据落盘约定:挂载 -v ./picobot-data:/home/picobot/.picobot,配置、记忆、技能、WhatsApp 会话全部持久化,容器重建不丢数据。
另外,internal/config/loader.go 表明:即使不用 Docker 的原生运行模式,PICOBOT_MODEL、PICOBOT_MAX_TOKENS、PICOBOT_MAX_TOOL_ITERATIONS、PICOBOT_AGENT_TIMEOUT_S、PICOBOT_ENABLE_TOOL_ACTIVITY_INDICATOR 这 5 个变量同样生效,且优先级高于配置文件。
八、工作区文件:workspace 目录逐个解析
agents.defaults.workspace 指向的目录(默认 ~/.picobot/workspace)是塑造智能体人格与行为的核心,由 internal/config/onboard.go 初始化:
| 文件 | 作用 | 谁来改 |
|---|---|---|
SOUL.md |
人格、价值观、沟通风格 | 你(一次性) |
AGENTS.md |
行为准则:文件创建规范、记忆与安全规则 | 你(一次性) |
USER.md |
你的画像:姓名、时区、偏好 | 你(一次性) |
TOOLS.md |
全部内置工具的参考文档 | 你(可选) |
HEARTBEAT.md |
自然语言定时任务,每 heartbeatIntervalS 秒检查一次 |
你 / 智能体 |
memory/MEMORY.md |
长期记忆,跨重启保留 | 智能体(write_memory 工具) |
memory/YYYY-MM-DD.md |
按日期归档的每日笔记 | 智能体 |
skills/ |
可复用技能包(markdown),可对话创建也可手写 | 智能体 / 你 |
💡 新手最常改的只有两个:
USER.md(告诉 Bot 你是谁)和HEARTBEAT.md(给它布置定时任务)。
九、最小生产配置示例
抄走即用(渠道按需删减):
{
"agents": {
"defaults": {
"workspace": "/home/user/.picobot/workspace",
"model": "google/gemini-2.5-flash",
"maxTokens": 8192,
"temperature": 0.7,
"maxToolIterations": 200,
"heartbeatIntervalS": 60
}
},
"channels": {
"telegram": {
"enabled": true,
"token": "YOUR_TELEGRAM_BOT_TOKEN",
"allowFrom": ["YOUR_TELEGRAM_USER_ID"]
}
},
"providers": {
"openai": {
"apiKey": "sk-or-v1-YOUR_KEY",
"apiBase": "https://openrouter.ai/api/v1"
}
}
}
改完保存,picobot gateway 启动即生效。
十、Picobot 配置避坑清单
- 模型没生效? 检查优先级:
-M参数会覆盖配置文件,其次才是agents.defaults.model - WhatsApp 消息石沉大海?
allowFrom必须填 LID 而不是手机号,看日志获取 - 响应被截断? 调大
maxTokens;请求超时? 慢模型把requestTimeoutS提到 120 - 工具狂转停不下来? 用
maxToolIterations设上限,或commands.deny封禁特定命令 - 想只收最终结果?
enableToolActivityIndicator设为false - Docker 数据丢了? 确认挂载了
./picobot-data:/home/picobot/.picobot
更多字段细节可直接查阅仓库内官方文档 docs/CONFIG.md,入门流程参考 docs/HOW_TO_START.md。


