PicoClaw 部署实战：从零搭建 AI 助手并配置安全沙箱

目录

最近发现了一个有趣的 AI 项目——PicoClaw，这是一个专为嵌入式系统和物联网（IoT）设计的 AI 助手。它最大的特点是可以直接与硬件交互（I2C、SPI 等），还支持多种通讯渠道（Telegram、Discord、飞书等）。本文记录我在阿里云服务器上部署 PicoClaw 的完整过程，包括遇到的坑和安全加固方案。

一、PicoClaw 简介

PicoClaw 是由 Sipeed 团队开发的开源 AI 助手，定位是”Personal AI Assistant”。相比于其他 AI 助手，它的特色功能包括：

• 🔧 硬件交互：支持 I2C、SPI 总线操作，可直接读写传感器
• 💬 多平台集成：支持 Telegram、Discord、飞书、企业微信等 10+ 渠道
• 🛠️ 工具系统：内置文件操作、网页搜索、定时任务等工具
• 🔌 Pico 协议：专为嵌入式设备设计的通讯协议

二、部署环境

• 服务器：阿里云 ECS
• 操作系统：Alibaba Cloud Linux 3 (x86_64)
• PicoClaw 版本：v0.2.0

三、部署过程

1. 下载安装包

官方提供了 RPM 和 DEB 包，我这边是 CentOS 系，选择 RPM：

# 注意：要根据服务器架构选择正确的包
# 我一开始下载了 aarch64 包，结果服务器是 x86_64，会报错
wget https://github.com/sipeed/picoclaw/releases/download/v0.2.0/picoclaw_x86_64.rpm

2. 安装

rpm -ivh picoclaw_x86_64.rpm
# 或者如果有依赖问题
yum localinstall -y picoclaw_x86_64.rpm

3. 初始化配置

# 运行 onboard 初始化
picoclaw onboard

这会创建默认配置文件在 ~/.picoclaw/config.json。

4. 配置 AI Provider

踩坑记录：一开始我配置了 Moonshot (Kimi) 的 API Key，但总是报错 Invalid Authentication。后来发现是 Key 格式问题。最后换成了 DeepSeek，稳定性和性价比都不错。

在 ~/.picoclaw/config.json 中配置：

{
  "agents": {
    "defaults": {
      "provider": "deepseek",
      "model": "deepseek-chat",
      "max_tokens": 4096
    }
  },
  "model_list": [
    {
      "model_name": "deepseek-chat",
      "model": "deepseek/deepseek-chat",
      "api_base": "https://api.deepseek.com/v1",
      "api_key": "sk-your-api-key-here"
    }
  ]
}

注意：DeepSeek 的 max_tokens 最大支持 8192，但建议设为 4096 以平衡性能和成本。

5. 启用 Channel

又一个坑：如果只配置 Agent 不启用 Channel，服务会报错 no channels enabled 并退出。

最简单的方案是启用 pico channel（Pico Protocol）：

{
  "channels": {
    "pico": {
      "enabled": true,
      "host": "0.0.0.0",
      "port": 18790,
      "token": "your-secure-token"
    }
  }
}

6. 创建 systemd 服务

cat > /etc/systemd/system/picoclaw.service << 'EOF'
[Unit]
Description=PicoClaw AI Gateway
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/.picoclaw
ExecStart=/usr/bin/picoclaw gateway
Restart=always
RestartSec=5
Environment="HOME=/root"

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable picoclaw
systemctl start picoclaw

7. 验证部署

# 查看状态
systemctl status picoclaw

# 测试对话
picoclaw agent -m "你好，请介绍一下自己"

# 查看健康检查端点
curl http://localhost:18790/health

部署成功后，可以看到服务正常运行，AI 助手能够正常响应：

四、安全配置：构建沙箱环境

由于 PicoClaw 默认拥有较高的系统权限（可以执行 shell 命令、访问文件系统），在生产环境中必须进行安全加固。

1. 限制工作目录

修改配置，将工作目录限制在 /opt/picoclaw：

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

创建目录并设置权限：

mkdir -p /opt/picoclaw
chmod 755 /opt/picoclaw

2. 禁用系统命令执行

通过配置 exec 工具的拒绝模式，阻止所有命令执行：

{
  "tools": {
    "exec": {
      "enable_deny_patterns": true,
      "custom_deny_patterns": [".*"]
    }
  }
}

这里的正则 .* 会匹配任何命令，实现完全禁止。

3. 禁用定时任务

{
  "tools": {
    "cron": {
      "exec_timeout_minutes": 0
    }
  }
}

4. 安全验证

配置完成后，进行安全测试：

# 测试 1：尝试访问系统目录（应该被拒绝）
picoclaw agent -m "查看 /etc/passwd 文件"
# 输出：无法直接访问系统级的 `/etc` 目录

# 测试 2：尝试执行系统命令（应该被阻止）
picoclaw agent -m "执行 ls -la /root"
# 日志显示：Command blocked by safety guard (dangerous pattern detected)

# 测试 3：验证工作目录限制（应该成功）
picoclaw agent -m "在当前目录创建 test.txt 文件，内容为 hello"
# 输出：文件已成功写入 /opt/picoclaw/test.txt

从日志中可以清楚看到，当 AI 尝试执行 whoami 等系统命令时，被安全策略阻止：

五、使用示例

命令行对话

# 单次对话
picoclaw agent -m "帮我写一段 Python 代码，计算斐波那契数列"

# 交互模式
picoclaw agent

文件操作（在限制目录内）

# 让 AI 读取并分析工作目录内的文件
picoclaw agent -m "读取 HEARTBEAT.md 并总结内容"

HTTP API

# 健康检查
curl http://your-server:18790/health

# 就绪检查  
curl http://your-server:18790/ready

六、总结

PicoClaw 是一个功能强大的 AI 助手，特别适合需要硬件交互和自动化任务的场景。但在生产环境部署时，安全配置是重中之重。

关键要点

1. 架构匹配：下载安装包时注意服务器架构（x86_64 vs aarch64）
2. 必须启用 Channel：至少启用一个 channel（如 pico）否则服务无法启动
3. Token 限制：DeepSeek 的 max_tokens 建议设为 4096-8192
4. 安全沙箱：务必限制工作目录、禁用 exec 工具，防止 AI 误操作或恶意指令

最终安全配置清单

配置项	推荐值	说明
workspace	/opt/picoclaw	隔离的工作目录
restrict_to_workspace	true	禁止访问工作目录外文件
exec.custom_deny_patterns	[".*"]	禁止执行所有系统命令
cron.exec_timeout_minutes	0	禁用定时任务功能

通过本文的配置，你可以在享受 AI 助手便利的同时，确保系统安全性。如果有任何问题，欢迎在评论区交流！

---

参考链接：

• PicoClaw GitHub
• DeepSeek API 文档

文章作者：阿文

文章链接： https://www.awen.me/post/picoclaw-deploy-guide.html

版权声明：本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 阿文的博客！