10 分钟跑通一个 ZeroClaw Telegram 助手（最小可用清单）

大家好，我是安东尼（tuaran.me），一名专注于前端与 AI 工程化的独立开发者。 我在建设 「博主联盟」——连接AI产品方与技术博主的品牌增长平台，帮AI产品精准触达开发者，也帮博主拿到推广资源与成长机会。 同时也在做 「前端下一步」——一个聚焦前端、AI Agent 与大模型的技术情报站，帮你从技术革新焦虑中解脱，得到技术转向判断。 这篇文章，希望对你有所启发。

image.png

前面几篇都在讲架构和安全，这篇直接动手——把 ZeroClaw 跑成"一个能在 Telegram 群里用的小助手"。10 分钟够用，但前提是你有 Rust 工具链。

注：本文写于 ZeroClaw v0.7 系列，命令行参数和 config 字段可能在后续小版本里调整。出问题先去仓库 examples/ 对一下。

0. 环境准备

需要的东西：

• Rust 1.75+（推荐 rustup 装最新 stable）
• ~1GB 空闲内存用于编译（ZeroClaw 对编译机器有要求，对运行机器没要求）
• 一个 LLM 提供商的 API Key（任选）：Anthropic / OpenAI / OpenRouter，或本地 Ollama
• 一个 Telegram Bot Token（找 @BotFather 创建一个 bot 即可）

1. 安装

预编译版本没覆盖所有平台时，最稳的还是从源码装：

cargo install zeroclaw \
  --features "channel-telegram provider-anthropic memory-sqlite tool-shell"

几个 feature 的含义：

• channel-telegram：编进 Telegram channel 实现
• provider-anthropic：编进 Claude 的 Provider（按需换成 provider-openai / provider-ollama）
• memory-sqlite：用本地 SQLite 做记忆（无需另跑数据库）
• tool-shell：允许 Agent 调用受限的 shell 命令——生产环境慎开

装完会有 zeroclaw 这个二进制。

2. 初始化工作目录

mkdir -p ~/zeroclaw-demo && cd ~/zeroclaw-demo
zeroclaw init

这一步会生成：

• zeroclaw.toml：主配置
• secrets/：本地加密的密钥库
• data/memory.db：SQLite 记忆库

3. 写 config（最小可用版）

编辑 zeroclaw.toml：

[agent]
name        = "demo-bot"
system_prompt = "你是一个简洁、友好的技术助手。回答控制在 200 字以内。"

[provider]
kind  = "anthropic"
model = "claude-sonnet-4-6"

[[channels]]
kind = "telegram"
# token 从环境变量读，避免落进文件
token_env = "TG_BOT_TOKEN"
# 只响应这些 chat（白名单，强烈建议配上）
allowed_chats = [123456789]

[memory]
kind = "sqlite"
path = "data/memory.db"

# 工具白名单——只允许执行这两条命令
[[tools]]
kind = "shell"
allow_commands = [
  "/usr/bin/date",
  "/usr/bin/uptime",
]

[security]
# 文件系统白名单
allowed_paths = ["./data"]
# 默认拒绝其它工具
default_policy = "deny"

要点：

• allowed_chats 一定要填——不填就是任何人都能 @ 你的 bot。
• allow_commands 写到绝对路径，不要只写 date。
• system_prompt 是 Agent 的人格，按需调。

4. 写凭据

export TG_BOT_TOKEN="123456:ABC..."
zeroclaw secret set anthropic.api_key
# 粘贴 Anthropic Key，回车

zeroclaw secret set 会把密钥加密存到 secrets/ 里，运行时再解出来——不要直接把 key 写进 toml。

5. 跑起来

zeroclaw run

正常的日志大致长这样：

[INFO] zeroclaw v0.7.x starting
[INFO] sandbox: landlock enabled (linux)
[INFO] provider: anthropic / claude-sonnet-4-6 ready
[INFO] channel: telegram polling started
[INFO] memory: sqlite at ./data/memory.db
[INFO] tools: 1 allowed (shell with 2 commands)
[INFO] policy: deny-by-default
[INFO] agent loop ready

打开 Telegram，给你的 bot 发"现在几点"，它会调 /usr/bin/date，把结果回给你。

6. 把它跑成系统服务

最简版 systemd unit（/etc/systemd/system/zeroclaw.service）：

[Unit]
Description=ZeroClaw demo bot
After=network-online.target

[Service]
Type=simple
User=zeroclaw
WorkingDirectory=/home/zeroclaw/zeroclaw-demo
EnvironmentFile=/home/zeroclaw/zeroclaw-demo/.env
ExecStart=/usr/local/bin/zeroclaw run
Restart=on-failure
# 再加一层 systemd 沙箱
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/home/zeroclaw/zeroclaw-demo/data
PrivateTmp=true

[Install]
WantedBy=multi-user.target

配合 ZeroClaw 自带的 Landlock/Seatbelt，等于双层沙箱——这套配置放生产可以接受。

7. 常见踩坑

8. 下一步可以加什么

• 多通道：再加一个 [[channels]] kind = "discord"，同一个 Agent 同时挂 TG + Discord。
• MCP 工具：把已有的 MCP Server 配进 [[tools]] kind = "mcp"。
• Postgres 记忆：业务量上来后从 SQLite 切到 pgvector，Memory Trait 不用改业务代码。
• 自定义 Channel：实现一遍 Channel trait，比如接公司内部 IM。

跑通这一版，剩下的就是按"加 Trait → 进白名单 → 重新编译"的节奏迭代。这套节奏也是 ZeroClaw 整个开发体验的味道。

文档锚点：官方 README、Reflex UI 教程。