Picobot配置完全手册:config.json字段、环境变量与工作区文件逐条解析

原创2026-10-15 09:27:181,765 阅读

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 即可自动生成默认配置与工作区,无需手写。

Picobot 配置架构总览:Chat Hub 与 Agent Loop 的消息流转

整个 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):

Picobot 配置所需 Slack App-Level Token 生成页面

Bot Token 在 OAuth & Permissions 页面获取,点击 Reinstall to My Workspace 后复制:

Picobot 配置所需 Slack Bot Token 复制页面

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 配置避坑清单

  1. 模型没生效? 检查优先级:-M 参数会覆盖配置文件,其次才是 agents.defaults.model
  2. WhatsApp 消息石沉大海? allowFrom 必须填 LID 而不是手机号,看日志获取
  3. 响应被截断? 调大 maxTokens;请求超时? 慢模型把 requestTimeoutS 提到 120
  4. 工具狂转停不下来? 用 maxToolIterations 设上限,或 commands.deny 封禁特定命令
  5. 想只收最终结果? enableToolActivityIndicator 设为 false
  6. Docker 数据丢了? 确认挂载了 ./picobot-data:/home/picobot/.picobot

更多字段细节可直接查阅仓库内官方文档 docs/CONFIG.md,入门流程参考 docs/HOW_TO_START.md。

登录后查看全文
picobot