PicoClaw Deployment in Practice: Building an AI Assistant From Scratch and Configuring a Security Sandbox

目录

I recently came across an interesting AI project — PicoClaw, an AI assistant designed specifically for embedded systems and the Internet of Things (IoT). Its biggest feature is that it can interact directly with hardware (I2C, SPI, etc.), and it supports multiple communication channels (Telegram, Discord, Feishu, etc.). This article documents my complete process of deploying PicoClaw on an Aliyun server, including the pitfalls I hit and my security-hardening plan.

1. Introduction to PicoClaw

PicoClaw is an open-source AI assistant developed by the Sipeed team, positioned as a “Personal AI Assistant.” Compared with other AI assistants, its distinctive features include:

• 🔧 Hardware interaction: Supports I2C and SPI bus operations, and can read and write sensors directly
• 💬 Multi-platform integration: Supports 10+ channels including Telegram, Discord, Feishu, and WeCom
• 🛠️ Tool system: Built-in tools for file operations, web search, scheduled tasks, and more
• 🔌 Pico protocol: A communication protocol designed specifically for embedded devices

2. Deployment Environment

• Server: Aliyun ECS
• Operating system: Alibaba Cloud Linux 3 (x86_64)
• PicoClaw version: v0.2.0

3. Deployment Process

1. Download the installer package

The official site provides RPM and DEB packages. Mine is a CentOS-family system, so I chose RPM:

# Note: choose the right package for your server architecture
# I initially downloaded the aarch64 package, but the server was x86_64, which errors out
wget https://github.com/sipeed/picoclaw/releases/download/v0.2.0/picoclaw_x86_64.rpm

2. Install

rpm -ivh picoclaw_x86_64.rpm
# Or, if there are dependency issues
yum localinstall -y picoclaw_x86_64.rpm

3. Initialize the configuration

# Run the onboard initialization
picoclaw onboard

This creates a default config file at ~/.picoclaw/config.json.

4. Configure the AI Provider

Pitfall log: At first I configured Moonshot’s (Kimi’s) API Key, but it kept reporting Invalid Authentication. Later I found it was a Key-format issue. In the end I switched to DeepSeek, which offers good stability and value for money.

Configure it in ~/.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"
    }
  ]
}

Note: DeepSeek’s max_tokens supports up to 8192, but it’s recommended to set it to 4096 to balance performance and cost.

5. Enable a Channel

Another pitfall: If you only configure an Agent without enabling a Channel, the service reports no channels enabled and exits.

The simplest approach is to enable the pico channel (Pico Protocol):

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

6. Create a systemd service

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. Verify the deployment

# Check the status
systemctl status picoclaw

# Test a conversation
picoclaw agent -m "Hello, please introduce yourself"

# Check the health-check endpoint
curl http://localhost:18790/health

After a successful deployment, you can see the service running normally and the AI assistant responding properly:

4. Security Configuration: Building a Sandbox

Because PicoClaw has relatively high system privileges by default (it can execute shell commands and access the file system), you must harden security in a production environment.

1. Restrict the working directory

Modify the config to restrict the working directory to /opt/picoclaw:

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

Create the directory and set permissions:

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

2. Disable system command execution

Configure a deny pattern for the exec tool to block all command execution:

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

Here the regex .* matches any command, achieving a full ban.

3. Disable scheduled tasks

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

4. Security verification

After configuration, run security tests:

# Test 1: Try to access a system directory (should be denied)
picoclaw agent -m "Look at the /etc/passwd file"
# Output: cannot directly access the system-level `/etc` directory

# Test 2: Try to execute a system command (should be blocked)
picoclaw agent -m "Execute ls -la /root"
# The log shows: Command blocked by safety guard (dangerous pattern detected)

# Test 3: Verify the working-directory restriction (should succeed)
picoclaw agent -m "In the current directory create a test.txt file with the content hello"
# Output: File successfully written to /opt/picoclaw/test.txt

From the logs you can clearly see that when the AI tries to run system commands like whoami, it’s blocked by the security policy:

5. Usage Examples

Command-Line Chat

# One-shot conversation
picoclaw agent -m "Help me write a Python snippet that computes the Fibonacci sequence"

# Interactive mode
picoclaw agent

File Operations (within the restricted directory)

# Have the AI read and analyze a file in the working directory
picoclaw agent -m "Read HEARTBEAT.md and summarize its contents"

HTTP API

# Health check
curl http://your-server:18790/health

# Readiness check
curl http://your-server:18790/ready

6. Summary

PicoClaw is a powerful AI assistant, especially suited to scenarios that need hardware interaction and automated tasks. But when deploying to production, security configuration is paramount.

Key Points

1. Architecture matching: When downloading the installer, pay attention to the server architecture (x86_64 vs aarch64)
2. A Channel is required: Enable at least one channel (such as pico), or the service won’t start
3. Token limits: Set DeepSeek’s max_tokens to 4096-8192
4. Security sandbox: Be sure to restrict the working directory and disable the exec tool, to prevent the AI from misbehaving or executing malicious instructions

Final Security Configuration Checklist

Config item	Recommended value	Description
workspace	/opt/picoclaw	Isolated working directory
restrict_to_workspace	true	Blocks access to files outside the working directory
exec.custom_deny_patterns	[".*"]	Blocks execution of all system commands
cron.exec_timeout_minutes	0	Disables the scheduled-task feature

With the configuration in this article, you can enjoy the convenience of an AI assistant while ensuring system security. If you have any questions, feel free to discuss in the comments!

---

Reference links:

• PicoClaw GitHub
• DeepSeek API documentation

中英对照

文章作者：阿文

文章链接： https://www.awen.me/post/454de196.html

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