# PicoBot 配置说明

配置文件加载顺序：`~/.picobot/config.json` → 当前目录 `./config.json`。
占位符 `<VAR_NAME>` 从启动环境替换。PicoBot 依次加载 `config.json` 同目录的 `.env`、`workspace_dir/.env`，最后保留启动进程已有环境变量作为最高优先级；workspace 层覆盖配置目录层。合并值也会进入进程环境，供 MCP 和工具子进程继承。workspace `.env` 不能修改用于定位自身的 `workspace_dir`。

Gateway WebUI 的“配置”页可以编辑实际加载的配置文件。读取时 API Key、secret、password 和 token 会显示为 `********`，保持掩码不变再保存会保留原值；写入采用同目录临时文件替换。运行配置保存后需要重启 Gateway，`USER.md` 与 `AGENTS.md` 的修改用于后续构建的 Agent 上下文。

## config.json 结构

```jsonc
{
  "providers": {},    // LLM 提供商配置
  "models": {},       // 模型配置
  "agents": {},       // agent 配置
  "gateway": {},      // 网关配置
  "client": {},       // 客户端配置
  "channels": {},     // 渠道配置
  "memory": {},       // 记忆系统配置
  "workspace_dir": "", // 工作目录，默认 ~/.picobot/workspace
  "mcp": {},           // MCP 服务器配置
  "browser": {}        // 可选浏览器自动化配置
}
```

完整示例见 `assets/config.example.json`。

## providers 字段

| 字段 | 说明 |
|------|------|
| `type` | 提供商类型: `openai`（兼容 OpenAI API）、`anthropic` |
| `base_url` | API 端点地址 |
| `api_key` | API 密钥，支持 `<ENV_VAR>` 占位符 |
| `extra_headers` | 额外 HTTP 头 |

## models 字段

| 字段 | 说明 |
|------|------|
| `model_id` | 模型标识名称 |
| `temperature` | 采样温度，可选 |
| `max_tokens` | 最大输出 token 数，可选 |
| `input_type` | 模型支持的输入类型，如 `["text"]` 或 `["text", "image"]`，默认 `["text"]`. 纯内部使用，不会传递给 LLM API |

## agents 字段

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `provider` | string | - | 提供商名称（对应 providers key） |
| `model` | string | - | 模型名称（对应 models key） |
| `max_tool_iterations` | int | 99 | 最大工具调用轮数 |
| `token_limit` | int | 128000 | 上下文 token 限制 |

## gateway 字段

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `host` | string | 127.0.0.1 | 监听地址 |
| `port` | int | 19876 | 监听端口 |
| `require_pairing` | bool | true | 是否要求 WebUI 与 CLI 设备先使用一次性代码配对 |
| `session_ttl_hours` | int | - | 兼容/预留字段；当前没有会话 TTL 清理循环 |
| `session_db_path` | string | - | SQLite 数据库路径，默认在 workspace 下 |
| `cleanup_interval_minutes` | int | - | 兼容/预留字段；当前没有按此间隔运行的 session 清理任务 |
| `max_concurrent_background_tasks` | int | 10 | delegate 后台子任务最大并发数 |
| `scheduler` | object | - | 调度器配置 |

### gateway.scheduler 字段

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `enabled` | bool | true | 是否启动调度器并注册 cron 工具 |
| `poll_interval_secs` | int | 60 | 检查到期任务的轮询间隔 |
| `max_concurrent` | int | 1 | 每批到期任务的最大并发数，运行时限制在 1–256 |
| `execution_timeout_secs` | int | 900 | 单个定时任务 Agent 执行的硬超时；租约会覆盖执行和托管投递等待 |

## memory 字段

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `consolidation_provider` | string | 主 Agent provider | 当前记录在 MemoryManager 中供后续归并使用；压缩摘要仍使用 Session provider |
| `consolidation_model` | string | 主 Agent model | 当前记录在 MemoryManager 中供后续归并使用；压缩摘要仍使用 Session model |
| `recall_limit` | int | 5 | 预期的每轮知识召回上限；当前 worker 固定使用 5 |
| `idle_consolidation_minutes` | int | 10 | 预留的空闲归并阈值；当前无对应循环 |
| `timeline_retention_days` | int | 90 | 默认日常维护巡检删除超过该期限的 Timeline；Knowledge 不受影响 |
| `max_failures_before_degrade` | int | 3 | 预留的归并失败阈值；当前无失败降级循环 |

注意：当前 worker 的 Knowledge 召回数量仍固定为 5；idle consolidation 和失败降级循环尚未接入。Timeline 清理由默认启用的 `picobot-routine-maintenance` 定时巡检执行。

## channels.feishu 字段

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `enabled` | bool | false | 是否启用 |
| `app_id` | string | - | 飞书应用 ID |
| `app_secret` | string | - | 飞书应用密钥 |
| `allow_from` | []string | ["*"] | 允许交互的用户列表 |
| `agent` | string | - | 使用的 agent 名称 |
| `media_dir` | string | ~/.picobot/media/feishu | 配置默认值；Gateway 注册渠道时会覆盖为 `{workspace}/media/feishu` |
| `reaction_emoji` | string | "Typing" | 回复意向表达的表情 |
| `live_updates` | bool | false | 是否用单张卡片实时编辑活动 Turn；关闭时只发送终态 |
| `live_update_interval_ms` | int | 500 | 卡片更新最小间隔，运行时限制在 250–5000ms |

飞书属于外部渠道：无论是否开启实时卡片，都不会接收模型 reasoning；工具只显示紧凑状态。配置修改需重启 Gateway 生效。

## mcp 字段

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `servers` | array | [] | MCP 服务器列表 |
| `tool_timeout_secs` | int | 180 | 工具调用超时秒数 |

MCP 服务器单条配置:

| 字段 | 说明 |
|------|------|
| `name` | 服务器名称 |
| `transport` | 传输方式: `stdio`、`sse`、`streamable-http` |
| `command` | 启动命令（stdio 模式） |
| `args` | 命令参数 |
| `env` | 子进程环境变量 |
| `url` | URL（sse / streamable-http 模式） |
| `headers` | HTTP 传输额外请求头 |
| `tool_timeout_secs` | 单独的超时设置 |

## browser 字段

浏览器工具默认关闭，开启后注册 `browser` 工具。依赖 Chrome/Chromium 与 chromedriver/WebDriver。

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `enabled` | bool | false | 是否启用浏览器工具 |
| `webdriver_url` | string | http://127.0.0.1:9515 | WebDriver 服务地址 |
| `headless` | bool | true | 是否无头运行 |
| `chrome_path` | string | - | 自定义 Chrome/Chromium 路径 |