picoclaw/docs/guides/configuration.zh.md

⚙️ 配置指南

返回 README

⚙️ 配置详解

配置文件路径: ~/.picoclaw/config.json

环境变量

你可以使用环境变量覆盖默认路径。这对于便携安装、容器化部署或将 picoclaw 作为系统服务运行非常有用。这些变量是独立的，控制不同的路径。

变量	描述	默认路径
PICOCLAW_CONFIG	覆盖配置文件的路径。这直接告诉 picoclaw 加载哪个 config.json，忽略所有其他位置。	~/.picoclaw/config.json
PICOCLAW_HOME	覆盖 picoclaw 数据根目录。这会更改 workspace 和其他数据目录的默认位置。	~/.picoclaw

示例：

# 使用特定的配置文件运行 picoclaw
# 工作区路径将从该配置文件中读取
PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway

# 在 /opt/picoclaw 中存储所有数据运行 picoclaw
# 配置将从默认的 ~/.picoclaw/config.json 加载
# 工作区将在 /opt/picoclaw/workspace 创建
PICOCLAW_HOME=/opt/picoclaw picoclaw agent

# 同时使用两者进行完全自定义设置
PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway

Gateway 日志等级

gateway.log_level 控制 Gateway 的日志详细程度，可在 config.json 中配置：

{
  "gateway": {
    "log_level": "warn"
  }
}

默认值为 warn。支持的值：debug、info、warn、error、fatal。

也可通过环境变量覆盖：PICOCLAW_LOG_LEVEL=info

工作区布局 (Workspace Layout)

PicoClaw 将数据存储在您配置的工作区中（默认：~/.picoclaw/workspace）：

~/.picoclaw/workspace/
├── sessions/          # 对话会话和历史
├── memory/           # 长期记忆 (MEMORY.md)
├── state/            # 持久化状态 (最后一次频道等)
├── cron/             # 定时任务数据库
├── skills/           # 自定义技能
├── AGENT.md          # Agent 行为指南
├── HEARTBEAT.md      # 周期性任务提示词 (每 30 分钟检查一次)
├── IDENTITY.md       # Agent 身份设定
├── SOUL.md           # Agent 灵魂/性格
└── USER.md           # 用户偏好

提示： 对 AGENT.md、SOUL.md、USER.md 和 memory/MEMORY.md 的修改会通过文件修改时间（mtime）在运行时自动检测。无需重启 gateway，Agent 将在下一次请求时自动加载最新内容。

Web 启动器控制台

用 picoclaw-launcher 打开浏览器控制台前需要先登录。访问口令与 会话签名密钥默认在每次启动时在内存中生成（重启后随机口令会变）。若设置环境变量 PICOCLAW_LAUNCHER_TOKEN，则该进程使用固定口令（启动日志中不会打印具体口令值）。

到哪里找口令：控制台模式（-console）请看启动时的终端输出；托盘 / GUI 模式可使用托盘菜单中的「复制控制台口令」，并在 $PICOCLAW_HOME/logs/launcher.log（未设置 PICOCLAW_HOME 时一般为 ~/.picoclaw/logs/launcher.log）中查看本次启动写入的随机口令。登录页在未登录时会根据当前运行方式展示提示（含日志文件绝对路径等；接口与页面均不会返回口令本身）。

• 配置文件：与 config.json 同一目录（若设置了 PICOCLAW_CONFIG，则与它所指的文件同目录）。启动器专用文件名为 launcher-config.json。
• 登录与链接：在登录页输入口令；自动打开浏览器时可在 URL 上使用 ?token=。全站响应携带 Referrer-Policy: no-referrer，减轻 token 经 Referer 头泄露的风险。
• 退出登录：应使用 POST /api/auth/logout，且请求头为 Content-Type: application/json（请求体可为 {}），勿使用可被第三方页面触发的 GET 链接登出。
• 暴力尝试：POST /api/auth/login 对同一远程地址有 每分钟尝试次数上限（超限返回 HTTP 429）。
• 会话时长：登录后的 HttpOnly 会话 Cookie 默认约 7 天有效，到期需重新用口令登录。

技能来源 (Skill Sources)

默认情况下，技能会按以下顺序加载：

1. ~/.picoclaw/workspace/skills（工作区）
2. ~/.picoclaw/skills（全局）
3. <构建时嵌入路径>/skills（内置）

在高级/测试场景下，可通过以下环境变量覆盖内置技能目录：

export PICOCLAW_BUILTIN_SKILLS=/path/to/skills

在聊天频道中使用技能

技能安装完成后，可以直接在聊天频道里查看并显式启用它们：

• /list skills：显示当前 Agent 可用的已安装技能名称。
• /use <skill> <message>：只对当前这一条请求强制使用指定技能。
• /use <skill>：为同一会话中的下一条消息预先启用该技能。
• /use clear：取消通过 /use <skill> 设置的待应用技能。
• /btw <question>：发起一个即时的旁支提问，且不改动当前会话历史。/btw 会按一次无工具的直接问答处理，不会进入常规的工具执行流程。

示例：

/list skills
/use git explain how to squash the last 3 commits
/btw 帮我回顾一下刚才关于发布方案的结论
/use italiapersonalfinance
dammi le ultime news

统一命令执行策略

• 通用斜杠命令通过 pkg/agent/loop.go 中的 commands.Executor 统一执行。
• Channel 适配器不再在本地消费通用命令；它们只负责把入站文本转发到 bus/agent 路径。Telegram 仍会在启动时自动注册其支持的命令菜单，例如 /start、/help、/show、/list、/use 和 /btw。
• 未注册的斜杠命令（例如 /foo）会透传给 LLM 按普通输入处理。
• 已注册但当前 channel 不支持的命令（例如 WhatsApp 上的 /show）会返回明确的用户可见错误，并停止后续处理。

🔒 安全沙箱 (Security Sandbox)

PicoClaw 默认在沙箱环境中运行。Agent 只能访问配置的工作区内的文件和执行命令。

默认配置

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "restrict_to_workspace": true
    }
  }
}

选项	默认值	描述
workspace	~/.picoclaw/workspace	Agent 的工作目录
restrict_to_workspace	true	限制文件/命令访问在工作区内

受保护的工具

当 restrict_to_workspace: true 时，以下工具会被沙箱化：

工具	功能	限制
read_file	读取文件	仅限工作区内的文件
write_file	写入文件	仅限工作区内的文件
list_dir	列出目录	仅限工作区内的目录
edit_file	编辑文件	仅限工作区内的文件
append_file	追加文件	仅限工作区内的文件
exec	执行命令	命令路径必须在工作区内

额外的 Exec 保护

即使 restrict_to_workspace: false，exec 工具也会阻止以下危险命令：

• rm -rf、del /f、rmdir /s — 批量删除
• format、mkfs、diskpart — 磁盘格式化
• dd if= — 磁盘镜像
• 写入 /dev/sd[a-z] — 直接磁盘写入
• shutdown、reboot、poweroff — 系统关机
• Fork bomb :(){ :|:& };:

文件访问控制

配置键	类型	默认值	描述
tools.allow_read_paths	string[]	[]	允许在工作区外读取的额外路径
tools.allow_write_paths	string[]	[]	允许在工作区外写入的额外路径

Exec 安全配置

配置键	类型	默认值	描述
tools.exec.allow_remote	bool	false	允许从远程渠道（Telegram/Discord 等）执行 exec 工具
tools.exec.enable_deny_patterns	bool	true	启用危险命令拦截
tools.exec.custom_deny_patterns	string[]	[]	自定义阻止的正则表达式模式
tools.exec.custom_allow_patterns	string[]	[]	自定义允许的正则表达式模式

安全提示： Symlink 保护默认启用——所有文件路径在白名单匹配前都会通过 filepath.EvalSymlinks 解析，防止符号链接逃逸攻击。

已知限制：构建工具的子进程

exec 安全守卫仅检查 PicoClaw 直接启动的命令行。它不会递归检查由 make、go run、cargo、npm run 或自定义构建脚本等开发工具产生的子进程。

这意味着顶层命令通过初始守卫检查后，仍可以编译或启动其他二进制文件。实际上，应将构建脚本、Makefile、包脚本和生成的二进制文件视为与直接 shell 命令同等级别的可执行代码进行审查。

对于高风险环境：

• 执行前审查构建脚本。
• 对编译并运行的工作流优先使用审批/手动审查。
• 如果需要比内置守卫更强的隔离，请在容器或虚拟机中运行 PicoClaw。

错误示例

[ERROR] tool: Tool execution failed
{tool=exec, error=Command blocked by safety guard (path outside working dir)}

[ERROR] tool: Tool execution failed
{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}

禁用限制（安全风险）

如果需要 Agent 访问工作区外的路径：

方法 1: 配置文件

{
  "agents": {
    "defaults": {
      "restrict_to_workspace": false
    }
  }
}

方法 2: 环境变量

export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false

⚠️ 警告: 禁用此限制将允许 Agent 访问系统上的任何路径。仅在受控环境中谨慎使用。

安全边界一致性

restrict_to_workspace 设置在所有执行路径中一致应用：

执行路径	安全边界
主 Agent	restrict_to_workspace ✅
子 Agent / Spawn	继承相同限制 ✅
心跳任务	继承相同限制 ✅

所有路径共享相同的工作区限制——无法通过子 Agent 或定时任务绕过安全边界。

心跳 / 周期性任务 (Heartbeat)

PicoClaw 可以自动执行周期性任务。在工作区创建 HEARTBEAT.md 文件：

# Periodic Tasks

- Check my email for important messages
- Review my calendar for upcoming events
- Check the weather forecast

Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具执行任务。

使用 Spawn 的异步任务

对于耗时较长的任务（网络搜索、API 调用），使用 spawn 工具创建一个 子 Agent (subagent)：

# Periodic Tasks

## Quick Tasks (respond directly)

- Report current time

## Long Tasks (use spawn for async)

- Search the web for AI news and summarize
- Check email and report important messages

关键行为：

特性	描述
spawn	创建异步子 Agent，不阻塞主心跳进程
独立上下文	子 Agent 拥有独立上下文，无会话历史
message tool	子 Agent 通过 message 工具直接与用户通信
非阻塞	spawn 后，心跳继续处理下一个任务

配置：

{
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

选项	默认值	描述
enabled	true	启用/禁用心跳
interval	30	检查间隔，单位分钟 (最小: 5)

环境变量:

• PICOCLAW_HEARTBEAT_ENABLED=false 禁用
• PICOCLAW_HEARTBEAT_INTERVAL=60 更改间隔

子 Agent 通信流程

心跳触发
    ↓
Agent 读取 HEARTBEAT.md
    ↓
遇到耗时任务：spawn 子 Agent
    ↓                           ↓
继续处理下一个任务         子 Agent 独立运行
    ↓                           ↓
所有任务完成               子 Agent 使用 "message" 工具
    ↓                           ↓
回复 HEARTBEAT_OK          用户直接收到结果

子 Agent 拥有工具访问权限（message、web_search 等），可以独立与用户通信，无需经过主 Agent。

Providers（模型提供商）

Note

Groq 通过 Whisper 提供免费语音转录。配置后，任意渠道的语音消息都会在 Agent 层自动转录为文字。

提供商	用途	获取 API Key
gemini	LLM（Gemini 直连）	aistudio.google.com
zhipu	LLM（智谱直连）	bigmodel.cn
volcengine	LLM（火山引擎直连）	volcengine.com
openrouter	LLM（推荐，可访问所有模型）	openrouter.ai
anthropic	LLM（Claude 直连）	console.anthropic.com
openai	LLM（GPT 直连）	platform.openai.com
deepseek	LLM（DeepSeek 直连）	platform.deepseek.com
qwen	LLM（通义千问直连）	dashscope.console.aliyun.com
groq	LLM + 语音转录（Whisper）	console.groq.com
cerebras	LLM（Cerebras 直连）	cerebras.ai
vivgrid	LLM（Vivgrid 直连）	vivgrid.com

模型配置 (model_list)

新特性： PicoClaw 现在采用以模型为中心的配置方式。只需指定 vendor/model 格式（例如 zhipu/glm-4.7）即可接入新提供商——无需修改任何代码！

这一设计同时支持多 Agent场景，灵活选择提供商：

• 不同 Agent 使用不同提供商：每个 Agent 可以使用独立的 LLM 提供商
• 模型降级：配置主模型和备用模型，提升可用性
• 负载均衡：将请求分发到多个端点
• 集中管理：在一处管理所有提供商配置

所有支持的厂商

厂商	model 前缀	默认 API Base	协议	API Key
OpenAI	openai/	https://api.openai.com/v1	OpenAI	获取
Anthropic	anthropic/	https://api.anthropic.com/v1	Anthropic	获取
智谱 AI (GLM)	zhipu/	https://open.bigmodel.cn/api/paas/v4	OpenAI	获取
DeepSeek	deepseek/	https://api.deepseek.com/v1	OpenAI	获取
Google Gemini	gemini/	https://generativelanguage.googleapis.com/v1beta	OpenAI	获取
Groq	groq/	https://api.groq.com/openai/v1	OpenAI	获取
Moonshot	moonshot/	https://api.moonshot.cn/v1	OpenAI	获取
通义千问 (Qwen)	qwen/	https://dashscope.aliyuncs.com/compatible-mode/v1	OpenAI	获取
NVIDIA	nvidia/	https://integrate.api.nvidia.com/v1	OpenAI	获取
Ollama	ollama/	http://localhost:11434/v1	OpenAI	本地（无需 Key）
LM Studio	lmstudio/	http://localhost:1234/v1	OpenAI	可选（本地默认无需密钥）
OpenRouter	openrouter/	https://openrouter.ai/api/v1	OpenAI	获取
LiteLLM Proxy	litellm/	http://localhost:4000/v1	OpenAI	你的 LiteLLM 代理 Key
VLLM	vllm/	http://localhost:8000/v1	OpenAI	本地
Cerebras	cerebras/	https://api.cerebras.ai/v1	OpenAI	获取
火山引擎 (豆包)	volcengine/	https://ark.cn-beijing.volces.com/api/v3	OpenAI	获取
神算云	shengsuanyun/	https://router.shengsuanyun.com/api/v1	OpenAI	—
BytePlus	byteplus/	https://ark.ap-southeast.bytepluses.com/api/v3	OpenAI	获取
Vivgrid	vivgrid/	https://api.vivgrid.com/v1	OpenAI	获取
LongCat	longcat/	https://api.longcat.chat/openai	OpenAI	获取
ModelScope (魔搭)	modelscope/	https://api-inference.modelscope.cn/v1	OpenAI	获取
Antigravity	antigravity/	Google Cloud	Custom	仅 OAuth
GitHub Copilot	github-copilot/	localhost:4321	gRPC	—

基础配置

{
  "model_list": [
    {
      "model_name": "ark-code-latest",
      "model": "volcengine/ark-code-latest",
      "api_keys": ["sk-your-api-key"]
    },
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_keys": ["sk-your-openai-key"]
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_keys": ["sk-ant-your-key"]
    },
    {
      "model_name": "glm-4.7",
      "model": "zhipu/glm-4.7",
      "api_keys": ["your-zhipu-key"]
    }
  ],
  "agents": {
    "defaults": {
      "model": "gpt-5.4"
    }
  }
}

各厂商配置示例

OpenAI

{
  "model_name": "gpt-5.4",
  "model": "openai/gpt-5.4",
  "api_keys": ["sk-..."]
}

火山引擎（豆包）

{
  "model_name": "ark-code-latest",
  "model": "volcengine/ark-code-latest",
  "api_keys": ["sk-..."]
}

智谱 AI (GLM)

{
  "model_name": "glm-4.7",
  "model": "zhipu/glm-4.7",
  "api_keys": ["your-key"]
}

DeepSeek

{
  "model_name": "deepseek-chat",
  "model": "deepseek/deepseek-chat",
  "api_keys": ["sk-..."]
}

Anthropic

{
  "model_name": "claude-sonnet-4.6",
  "model": "anthropic/claude-sonnet-4.6",
  "api_keys": ["sk-ant-your-key"]
}

运行 picoclaw auth login --provider anthropic 粘贴 API Token。

如需直连 Anthropic 原生接口（不兼容 OpenAI 格式的端点）：

{
  "model_name": "claude-opus-4-6",
  "model": "anthropic-messages/claude-opus-4-6",
  "api_keys": ["sk-ant-your-key"],
  "api_base": "https://api.anthropic.com"
}

当端点不支持 OpenAI 兼容格式（/v1/chat/completions），需要 Anthropic 原生 /v1/messages 时使用 anthropic-messages。

Ollama（本地）

{
  "model_name": "llama3",
  "model": "ollama/llama3"
}

LM Studio（本地）

{
  "model_name": "lmstudio-local",
  "model": "lmstudio/openai/gpt-oss-20b"
}

api_base 默认是 http://localhost:1234/v1。除非你在 LM Studio 侧启用了认证，否则不需要配置 API Key。 PicoClaw 向 LM Studio 的 OpenAI 兼容终结点发送请求，且将移除首个 lmstudio/ 前缀，因此 lmstudio/openai/gpt-oss-20b 会发送 openai/gpt-oss-20b。

自定义代理 / LiteLLM

{
  "model_name": "my-custom-model",
  "model": "openai/custom-model",
  "api_base": "https://my-proxy.com/v1",
  "api_keys": ["sk-..."]
}

PicoClaw 只剥离最外层的 litellm/ 前缀再发送请求，因此 litellm/lite-gpt4 发送 lite-gpt4，而 litellm/openai/gpt-4o 发送 openai/gpt-4o。

负载均衡

为同一模型名称配置多个端点，PicoClaw 会自动轮询：

{
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_base": "https://api1.example.com/v1",
      "api_keys": ["sk-key1"]
    },
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_base": "https://api2.example.com/v1",
      "api_keys": ["sk-key2"]
    }
  ]
}

从旧版 providers 配置迁移

旧版 providers 配置已废弃，V2 中已移除。现有 V0/V1 配置会自动迁移。完整迁移指南见 docs/migration/model-list-migration.md。

Provider 架构

PicoClaw 按协议族路由提供商：

• OpenAI 兼容：OpenRouter、Groq、智谱、vLLM 风格端点及大多数其他提供商。
• Anthropic：Claude 原生 API 行为。
• Codex/OAuth：OpenAI OAuth/Token 认证路由。

这使运行时保持轻量，同时让接入新的 OpenAI 兼容后端基本只需配置 api_base + api_key。

智谱（旧版 providers 格式）

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model": "glm-4.7",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "providers": {
    "zhipu": {
      "api_key": "Your API Key",
      "api_base": "https://open.bigmodel.cn/api/paas/v4"
    }
  }
}

完整配置示例

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5"
    }
  },
  "session": {
    "dm_scope": "per-channel-peer",
    "backlog_limit": 20
  },
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-xxx"
    },
    "groq": {
      "api_key": "gsk_xxx"
    }
  },
  "channel_list": {
    "telegram": {
      "enabled": true,
      "type": "telegram",
      "token": "123456:ABC...",
      "allow_from": ["123456789"]
    }
  },
  "tools": {
    "web": {
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      }
    }
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

定时任务 / 提醒

PicoClaw 通过 cron 工具支持 cron 风格的定时任务。Agent 可以设置、列出和取消在指定时间触发的提醒或周期性任务。

{
  "tools": {
    "cron": {
      "enabled": true,
      "exec_timeout_minutes": 5
    }
  }
}

定时任务在重启后持久保存，存储于 ~/.picoclaw/workspace/cron/。

进阶主题

主题	说明
敏感数据过滤	在发送给 LLM 前，从工具结果中过滤 API 密钥和令牌
Hook 系统	事件驱动 Hook：观察者、拦截器、审批 Hook
Steering	在工具调用间向运行中的 Agent 注入消息
SubTurn	子 Agent 协调、并发控制、生命周期管理
上下文管理	上下文边界检测、主动预算检查、压缩策略