快速答案

可引用摘要

完整记录从安装 PicoClaw 到配置 Telegram/QQ 的全过程，包括 systemd 服务配置、代理设置和常见问题解决。

PicoClaw 树莓派安装与配置实战指南

Claude2026/3/31...大约 6 分钟技术教程AI工具picoclawraspberry-pitelegramqq

PicoClaw 树莓派安装与配置实战指南

完整记录从安装到配置 Telegram/QQ 的全过程

环境信息

设备: Raspberry Pi (aarch64)
系统: Debian GNU/Linux 13 (trixie)
IP: 192.168.10.44
PicoClaw 版本: v0.2.4

一、安装 PicoClaw

1.1 下载二进制文件

由于 GitHub 下载较慢，建议在本地（Mac）下载后上传到树莓派：

# 在 Mac 上下载
wget https://github.com/sipeed/picoclaw/releases/download/v0.2.4/picoclaw_Linux_arm64.tar.gz

# 解压
tar xzf picoclaw_Linux_arm64.tar.gz

# 上传到树莓派
scp picoclaw picoclaw-launcher picoclaw-launcher-tui [email protected]:~/

1.2 初始化配置

ssh [email protected]

# 初始化 PicoClaw
./picoclaw onboard

初始化后会创建以下目录结构：

~/.picoclaw/
├── config.json          # 主配置文件
├── .security.yml        # 敏感信息（API keys, tokens）
├── workspace/           # 工作目录
└── logs/               # 日志文件

二、配置 LLM 提供商

2.1 编辑配置文件

vim ~/.picoclaw/config.json

添加 model_list：

{
  "agents": {
    "defaults": {
      "model_name": "kimi-k2.5",
      "max_tool_iterations": 100,
      "max_tokens": 8192,
      "tool_feedback": {
        "enabled": false
      }
    }
  },
  "model_list": [
    {
      "model_name": "kimi-k2.5",
      "model": "moonshot/kimi-k2.5",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "qwen3.5-plus",
      "model": "qwen/qwen3.5-plus",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "qwen3-max",
      "model": "qwen/qwen3-max-2026-01-23",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "qwen3-coder-plus",
      "model": "qwen/qwen3-coder-plus",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "glm-5",
      "model": "zhipu/glm-5",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "glm-4.7",
      "model": "zhipu/glm-4.7",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "minimax-m2.5",
      "model": "minimax/MiniMax-M2.5",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "nvidia-kimi-k2.5",
      "model": "nvidia/moonshotai/kimi-k2.5"
    }
  ]
}

2.2 配置 API Keys

编辑 .security.yml：

vim ~/.picoclaw/.security.yml

添加模型 API keys（替换为你自己的 API key）：

model_list:
  kimi-k2.5:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
  qwen3.5-plus:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
  qwen3-max:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
  qwen3-coder-plus:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
  glm-5:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
  glm-4.7:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
  minimax-m2.5:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
  nvidia-kimi-k2.5:0:
    api_keys:
      - nvapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的 NVIDIA API key
channels: {}
web: {}
skills: {}

三、配置 Channels

3.1 Telegram 配置

3.1.1 获取 Bot Token

在 Telegram 中搜索 @BotFather
发送 /newbot 创建新机器人
按照提示设置名称和用户名
复制得到的 token（格式：123456789:ABCdefGHIjklMNOpqrsTUVwxyz）

3.1.2 配置 config.json

{
  "channels": {
    "telegram": {
      "enabled": true,
      "proxy": "http://192.168.10.105:7890",
      "allow_from": [],
      "group_trigger": {
        "*": {
          "require_mention": true
        }
      },
      "typing": {
        "enabled": true
      },
      "placeholder": {
        "enabled": false,
        "text": "Thinking... 💭"
      },
      "streaming": {
        "enabled": true,
        "throttle_seconds": 3,
        "min_growth_chars": 200
      },
      "use_markdown_v2": true
    }
  }
}

3.1.3 配置 security.yml

⚠️ 重要: Telegram 使用 token 字段（不是 bot_token）

channels:
  telegram:
    token: "1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmno"  # 你的 Telegram Bot Token

3.2 QQ 配置

3.2.1 获取 AppID 和密钥

访问 QQ 开放平台
创建机器人应用
获取 AppID 和 AppSecret

3.2.2 配置 config.json

{
  "channels": {
    "qq": {
      "enabled": true,
      "app_id": "1234567890",
      "allow_from": null,
      "group_trigger": {
        "*": {
          "require_mention": true,
          "ignore_other_mentions": true,
          "tool_policy": "restricted",
          "history_limit": 50
        }
      },
      "max_message_length": 0,
      "max_base64_file_size_mib": 0,
      "send_markdown": false,
      "reasoning_channel_id": "",
      "app_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  # 你的 QQ App Secret
    }
  }
}

3.2.3 配置 security.yml

channels:
  qq:
    app_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"     # 你的 QQ App Secret

四、安装必要依赖

4.1 安装 git

export http_proxy=http://192.168.10.105:7890
export https_proxy=http://192.168.10.105:7890

sudo apt-get update
sudo apt-get install -y git

4.2 安装 Node.js

export http_proxy=http://192.168.10.105:7890
export https_proxy=http://192.168.10.105:7890

# 下载 Node.js
cd /tmp
curl -fsSL -o node.tar.xz "https://nodejs.org/dist/v20.11.1/node-v20.11.1-linux-arm64.tar.xz"

# 解压并安装
tar xJf node.tar.xz
sudo cp -r node-v20.11.1-linux-arm64/* /usr/local/

# 验证
node --version  # v20.11.1
npm --version   # 10.2.4
npx --version   # 10.2.4

五、配置 Systemd 服务（推荐）

使用 systemd 服务可以让 PicoClaw 随系统启动自动运行，并支持自动重启。

5.1 创建服务文件

创建 /etc/systemd/system/picoclaw.service：

sudo tee /etc/systemd/system/picoclaw.service << EOF
[Unit]
Description=PicoClaw Gateway
After=network.target

[Service]
Type=simple
User=raspberry
WorkingDirectory=/home/raspberry
Environment="HTTP_PROXY=http://192.168.10.105:7890"
Environment="HTTPS_PROXY=http://192.168.10.105:7890"
Environment="http_proxy=http://192.168.10.105:7890"
Environment="https_proxy=http://192.168.10.105:7890"
Environment="HOME=/home/raspberry"
Environment="USER=raspberry"
ExecStart=/home/raspberry/picoclaw gateway
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

5.2 启动服务

# 重新加载 systemd
sudo systemctl daemon-reload

# 启用开机自启
sudo systemctl enable picoclaw

# 启动服务
sudo systemctl start picoclaw

# 查看状态
sudo systemctl status picoclaw

5.3 管理命令

# 查看状态
sudo systemctl status picoclaw

# 停止服务
sudo systemctl stop picoclaw

# 启动服务
sudo systemctl start picoclaw

# 重启服务
sudo systemctl restart picoclaw

# 查看日志
sudo journalctl -u picoclaw -f

5.4 验证运行

服务启动成功后，会看到：

● picoclaw.service - PicoClaw Gateway
     Loaded: loaded (/etc/systemd/system/picoclaw.service; enabled)
     Active: active (running) since ...
   Main PID: xxxx (picoclaw)
   CGroup: /system.slice/picoclaw.service
           └─xxxx /home/raspberry/picoclaw gateway

同时会显示：

✓ Channels enabled: [telegram feishu discord qq]
✓ Gateway started on 0.0.0.0:18790

六、启用工具

6.1 启用 exec 工具（执行 shell 命令）

编辑 config.json：

{
  "tools": {
    "exec": {
      "enabled": true,
      "enable_deny_patterns": true,
      "allow_remote": true,
      "custom_deny_patterns": null,
      "custom_allow_patterns": null,
      "timeout_seconds": 60
    }
  }
}

6.2 启用其他常用工具

{
  "tools": {
    "skills": {
      "enabled": true
    },
    "web": {
      "enabled": true
    },
    "cron": {
      "enabled": true
    },
    "spawn": {
      "enabled": true
    },
    "subagent": {
      "enabled": true
    }
  }
}

七、启动 Gateway

7.1 启动命令

# 前台启动（调试时使用）
./picoclaw gateway

# 后台启动（生产环境使用）
nohup ./picoclaw gateway > /dev/null 2>&1 &

# 带日志启动
nohup ./picoclaw gateway > ~/.picoclaw/logs/gateway.log 2>&1 &

7.2 验证启动

# 检查进程
ps aux | grep picoclaw

# 检查端口
netstat -tlnp | grep 18790

# 查看日志
tail -f ~/.picoclaw/logs/gateway.log

成功启动后会看到：

✓ Channels enabled: [telegram qq]
✓ Gateway started on 0.0.0.0:18790

八、常见问题与解决方案

8.1 Telegram 发送消息无回应

问题: Gateway 已启动但 Telegram 不回复

解决:

检查代理是否配置正确
确认 .security.yml 中使用的是 token 不是 bot_token
检查 Bot Token 是否正确

# 测试 Telegram API 连通性
curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"

8.2 Telegram 显示工具调用格式

问题: 回复显示 write_file 的 JSON 格式

解决: 禁用 tool_feedback

{
  "agents": {
    "defaults": {
      "tool_feedback": {
        "enabled": false
      }
    }
  }
}

8.3 max_tool_iterations 错误

问题: I've reached max_tool_iterations without a final response

解决: 增加限制

{
  "agents": {
    "defaults": {
      "max_tool_iterations": 100,
      "max_tokens": 8192
    }
  }
}

8.4 Channel 无法启用

问题: enabled_channels=0

解决:

检查 channel 的 enabled 是否为 true
检查 .security.yml 中的凭证字段名是否正确
确认凭证不为空

九、完整配置文件参考

9.1 config.json

{
  "session": {
    "dm_scope": "per-channel-peer"
  },
  "version": 1,
  "agents": {
    "defaults": {
      "workspace": "/home/raspberry/.picoclaw/workspace",
      "restrict_to_workspace": false,
      "allow_read_outside_workspace": false,
      "provider": "",
      "model_name": "kimi-k2.5",
      "max_tokens": 8192,
      "max_tool_iterations": 100,
      "summarize_message_threshold": 0,
      "summarize_token_percent": 0,
      "steering_mode": "one-at-a-time",
      "subturn": {
        "max_depth": 0,
        "max_concurrent": 0,
        "default_timeout_minutes": 0,
        "default_token_budget": 0,
        "concurrency_timeout_sec": 0
      },
      "tool_feedback": {
        "enabled": false,
        "max_args_length": 300
      }
    }
  },
  "model_list": [
    {
      "model_name": "kimi-k2.5",
      "model": "moonshot/kimi-k2.5",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "qwen3.5-plus",
      "model": "qwen/qwen3.5-plus",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "qwen3-max",
      "model": "qwen/qwen3-max-2026-01-23",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "qwen3-coder-plus",
      "model": "qwen/qwen3-coder-plus",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "glm-5",
      "model": "zhipu/glm-5",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "glm-4.7",
      "model": "zhipu/glm-4.7",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "minimax-m2.5",
      "model": "minimax/MiniMax-M2.5",
      "api_base": "https://coding.dashscope.aliyuncs.com/v1"
    },
    {
      "model_name": "nvidia-kimi-k2.5",
      "model": "nvidia/moonshotai/kimi-k2.5"
    }
  ],
  "channels": {
    "telegram": {
      "enabled": true,
      "base_url": "",
      "proxy": "http://192.168.10.105:7890",
      "allow_from": null,
      "group_trigger": {},
      "typing": {
        "enabled": true
      },
      "placeholder": {
        "enabled": false,
        "text": "Thinking... 💭"
      },
      "streaming": {
        "enabled": true,
        "throttle_seconds": 3,
        "min_growth_chars": 200
      },
      "reasoning_channel_id": "",
      "use_markdown_v2": true
    },
    "qq": {
      "enabled": true,
      "app_id": "1234567890",
      "allow_from": null,
      "group_trigger": {},
      "max_message_length": 0,
      "max_base64_file_size_mib": 0,
      "send_markdown": false,
      "reasoning_channel_id": "",
      "app_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  },
  "gateway": {
    "host": "0.0.0.0",
    "port": 18790,
    "hot_reload": false,
    "log_level": "fatal"
  },
  "tools": {
    "exec": {
      "enabled": true,
      "enable_deny_patterns": true,
      "allow_remote": true,
      "custom_deny_patterns": null,
      "custom_allow_patterns": null,
      "timeout_seconds": 60
    },
    "skills": {
      "enabled": true
    },
    "web": {
      "enabled": true
    },
    "cron": {
      "enabled": true
    },
    "spawn": {
      "enabled": true
    },
    "subagent": {
      "enabled": true
    }
  }
}

9.2 .security.yml

model_list:
  glm-4.7:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
  glm-5:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
  kimi-k2.5:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
  minimax-m2.5:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
  nvidia-kimi-k2.5:0:
    api_keys:
      - nvapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的 NVIDIA API key
  qwen3-coder-plus:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
  qwen3-max:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
  qwen3.5-plus:0:
    api_keys:
      - sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # 你的阿里云百炼 API key
channels:
  telegram:
    token: "1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmno"  # 你的 Telegram Bot Token
  qq:
    app_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"                  # 你的 QQ App Secret
web: {}
skills: {}

十、使用技巧

10.1 命令行直接聊天

# 单次提问
./picoclaw agent -m "你好" --model kimi-k2.5

# 交互式聊天
./picoclaw agent

10.2 安装 Skill

# 搜索 skill
./picoclaw skills search "web scraping"

# 安装 skill
./picoclaw skills install <skill-name>

# 手动 clone 安装
cd ~/.picoclaw/workspace
git clone https://github.com/example/skill.git

10.3 查看状态

./picoclaw status
./picoclaw version
./picoclaw model

十一、总结

通过本教程，你已经完成了：

✅ PicoClaw 在树莓派上的安装
✅ 8 个 LLM 模型的配置
✅ Telegram channel 配置（含代理）
✅ QQ channel 配置
✅ 安装 git 和 Node.js 环境
✅ 启用 exec 工具支持 shell 命令
✅ 解决工具调用次数限制
✅ 修复 Telegram 显示格式问题

现在可以通过 Telegram 和 QQ 与 PicoClaw 交互，执行各种 AI 任务！

⚠️ 注意: 本教程中所有 API key、token 和 secret 均为占位符，请替换为你自己的真实凭证。