diff --git a/README.md b/README.md index cdd644fd8..78c402735 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@
-PicoClaw + PicoClaw -

PicoClaw: 基于Go语言的超高效 AI 助手

+

PicoClaw: Ultra-Efficient AI Assistant in Go

-

10$硬件 · 10MB内存 · 1秒启动 · 皮皮虾，我们走！

+

$10 Hardware · 10MB RAM · 1s Boot · 皮皮虾，我们走！

Go @@ -12,133 +12,135 @@
Website Twitter +
+ + Discord

-**中文** | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [English](README.md) +[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | **English**
--- -🦐 **PicoClaw** 是一个受 [nanobot](https://github.com/HKUDS/nanobot) 启发的超轻量级个人 AI 助手。它采用 **Go 语言** 从零重构，经历了一个“自举”过程——即由 AI Agent 自身驱动了整个架构迁移和代码优化。 +🦐 PicoClaw is an ultra-lightweight personal AI Assistant inspired by [nanobot](https://github.com/HKUDS/nanobot), refactored from the ground up in Go through a self-bootstrapping process, where the AI agent itself drove the entire architectural migration and code optimization. -⚡️ **极致轻量**：可在 **10 美元** 的硬件上运行，内存占用 **<10MB**。这意味着比 OpenClaw 节省 99% 的内存，比 Mac mini 便宜 98%！ +⚡️ Runs on $10 hardware with <10MB RAM: That's 99% less memory than OpenClaw and 98% cheaper than a Mac mini! - - - - + + + +
-

- -

-		 -

- -

-
+

+ +

+ 		+

+ +

+
-注意：人手有限，中文文档可能略有滞后，请优先查看英文文档。 - > [!CAUTION] > **🚨 SECURITY & OFFICIAL CHANNELS / 安全声明** > -> - **无加密货币 (NO CRYPTO):** PicoClaw **没有** 发行任何官方代币、Token 或虚拟货币。所有在 `pump.fun` 或其他交易平台上的相关声称均为 **诈骗**。 -> - **官方域名:** 唯一的官方网站是 **[picoclaw.io](https://picoclaw.io)**，公司官网是 **[sipeed.com](https://sipeed.com)**。 -> - **警惕:** 许多 `.ai/.org/.com/.net/...` 后缀的域名被第三方抢注，请勿轻信。 -> - **注意:** picoclaw正在初期的快速功能开发阶段，可能有尚未修复的网络安全问题，在1.0正式版发布前，请不要将其部署到生产环境中 -> - **注意:** picoclaw最近合并了大量PRs，近期版本可能内存占用较大(10~20MB)，我们将在功能较为收敛后进行资源占用优化. +> * **NO CRYPTO:** PicoClaw has **NO** official token/coin. All claims on `pump.fun` or other trading platforms are **SCAMS**. +> +> * **OFFICIAL DOMAIN:** The **ONLY** official website is **[picoclaw.io](https://picoclaw.io)**, and company website is **[sipeed.com](https://sipeed.com)** +> * **Warning:** Many `.ai/.org/.com/.net/...` domains are registered by third parties. +> * **Warning:** picoclaw is in early development now and may have unresolved network security issues. Do not deploy to production environments before the v1.0 release. +> * **Note:** picoclaw has recently merged a lot of PRs, which may result in a larger memory footprint (10–20MB) in the latest versions. We plan to prioritize resource optimization as soon as the current feature set reaches a stable state. -## 📢 新闻 (News) +## 📢 News -2026-02-16 🎉 PicoClaw 在一周内突破了12K star! 感谢大家的关注！PicoClaw 的成长速度超乎我们预期. 由于PR数量的快速膨胀，我们亟需社区开发者参与维护. 我们需要的志愿者角色和roadmap已经发布到了[这里](docs/ROADMAP.md), 期待你的参与！ +2026-02-16 🎉 PicoClaw hit 12K stars in one week! Thank you all for your support! PicoClaw is growing faster than we ever imagined. Given the high volume of PRs, we urgently need community maintainers. Our volunteer roles and roadmap are officially posted [here](docs/ROADMAP.md) —we can’t wait to have you on board! -2026-02-13 🎉 **PicoClaw 在 4 天内突破 5000 Stars！** 感谢社区的支持！由于正值中国春节假期，PR 和 Issue 涌入较多，我们正在利用这段时间敲定 **项目路线图 (Roadmap)** 并组建 **开发者群组**，以便加速 PicoClaw 的开发。 -🚀 **行动号召：** 请在 GitHub Discussions 中提交您的功能请求 (Feature Requests)。我们将在接下来的周会上进行审查和优先级排序。 +2026-02-13 🎉 PicoClaw hit 5000 stars in 4days! Thank you for the community! There are so many PRs & issues coming in (during Chinese New Year holidays), we are finalizing the Project Roadmap and setting up the Developer Group to accelerate PicoClaw's development. +🚀 Call to Action: Please submit your feature requests in GitHub Discussions. We will review and prioritize them during our upcoming weekly meeting. -2026-02-09 🎉 **PicoClaw 正式发布！** 仅用 1 天构建，旨在将 AI Agent 带入 10 美元硬件与 <10MB 内存的世界。🦐 PicoClaw（皮皮虾），我们走！ +2026-02-09 🎉 PicoClaw Launched! Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. 🦐 PicoClaw，Let's Go！ -## ✨ 特性 +## ✨ Features -🪶 **超轻量级**: 核心功能内存占用 <10MB — 比 Clawdbot 小 99%。 +🪶 **Ultra-Lightweight**: <10MB Memory footprint — 99% smaller than Clawdbot - core functionality. -💰 **极低成本**: 高效到足以在 10 美元的硬件上运行 — 比 Mac mini 便宜 98%。 +💰 **Minimal Cost**: Efficient enough to run on $10 Hardware — 98% cheaper than a Mac mini. -⚡️ **闪电启动**: 启动速度快 400 倍，即使在 0.6GHz 单核处理器上也能在 1 秒内启动。 +⚡️ **Lightning Fast**: 400X Faster startup time, boot in 1 second even in 0.6GHz single core. -🌍 **真正可移植**: 跨 RISC-V、ARM 和 x86 架构的单二进制文件，一键运行！ +🌍 **True Portability**: Single self-contained binary across RISC-V, ARM, and x86, One-click to Go! -🤖 **AI 自举**: 纯 Go 语言原生实现 — 95% 的核心代码由 Agent 生成，并经由“人机回环 (Human-in-the-loop)”微调。 +🤖 **AI-Bootstrapped**: Autonomous Go-native implementation — 95% Agent-generated core with human-in-the-loop refinement. -| | OpenClaw | NanoBot | **PicoClaw** | -| ------------------------------ | ------------- | ------------------------ | -------------------------------------- | -| **语言** | TypeScript | Python | **Go** | -| **RAM** | >1GB | >100MB | **< 10MB** | -| **启动时间**
(0.8GHz core) | >500s | >30s | **<1s** | -| **成本** | Mac Mini $599 | 大多数 Linux 开发板 ~$50 | **任意 Linux 开发板**
**低至 $10** | +| | OpenClaw | NanoBot | **PicoClaw** | +| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- | +| **Language** | TypeScript | Python | **Go** | +| **RAM** | >1GB | >100MB | **< 10MB** | +| **Startup**
(0.8GHz core) | >500s | >30s | **<1s** | +| **Cost** | Mac Mini 599$ | Most Linux SBC
~50$ | **Any Linux Board**
**As low as 10$** | PicoClaw -## 🦾 演示 +## 🦾 Demonstration -### 🛠️ 标准助手工作流 +### 🛠️ Standard Assistant Workflows - - - - - - - - - - - - - - - + + + + + + + + + + + + + + +

🧩 全栈工程师模式

🗂️ 日志与规划管理

🔎 网络搜索与学习

开发 • 部署 • 扩展日程 • 自动化 • 记忆发现 • 洞察 • 趋势

🧩 Full-Stack Engineer

🗂️ Logging & Planning Management

🔎 Web Search & Learning

Develop • Deploy • ScaleSchedule • Automate • MemoryDiscovery • Insights • Trends
-### 📱 在手机上轻松运行 +### 📱 Run on old Android Phones -picoclaw 可以将你10年前的老旧手机废物利用，变身成为你的AI助理！快速指南: +Give your decade-old phone a second life! Turn it into a smart AI Assistant with PicoClaw. Quick Start: -1. 先去应用商店下载安装Termux -2. 打开后执行指令 +1. **Install Termux** (Available on F-Droid or Google Play). +2. **Execute cmds** ```bash -# 注意: 下面的v0.1.1 可以换为你实际看到的最新版本 +# Note: Replace v0.1.1 with the latest version from the Releases page wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64 chmod +x picoclaw-linux-arm64 pkg install proot termux-chroot ./picoclaw-linux-arm64 onboard ``` -然后跟随下面的“快速开始”章节继续配置picoclaw即可使用！ +And then follow the instructions in the "Quick Start" section to complete the configuration! PicoClaw -### 🐜 创新的低占用部署 +### 🐜 Innovative Low-Footprint Deploy -PicoClaw 几乎可以部署在任何 Linux 设备上！ +PicoClaw can be deployed on almost any Linux device! -- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(网口) 或 W(WiFi6) 版本，用于极简家庭助手。 -- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html)，或 $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html)，用于自动化服务器运维。 -- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) 或 $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera)，用于智能监控。 +- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) or W(WiFi6) version, for Minimal Home Assistant +- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), or $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) for Automated Server Maintenance +- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) or $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) for Smart Monitoring -[https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4](https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4) + -🌟 更多部署案例敬请期待！ +🌟 More Deployment Cases Await！ -## 📦 安装 +## 📦 Install -### 使用预编译二进制文件安装 +### Install with precompiled binary -从 [Release 页面](https://github.com/sipeed/picoclaw/releases) 下载适用于您平台的固件。 +Download the firmware for your platform from the [release](https://github.com/sipeed/picoclaw/releases) page. -### 从源码安装（获取最新特性，开发推荐） +### Install from source (latest features, recommended for development) ```bash git clone https://github.com/sipeed/picoclaw.git @@ -146,80 +148,78 @@ git clone https://github.com/sipeed/picoclaw.git cd picoclaw make deps -# 构建（无需安装） +# Build, no need to install make build -# 为多平台构建 +# Build for multiple platforms make build-all -# 构建并安装 +# Build And Install make install - ``` ## 🐳 Docker Compose -您也可以使用 Docker Compose 运行 PicoClaw，无需在本地安装任何环境。 +You can also run PicoClaw using Docker Compose without installing anything locally. ```bash -# 1. 克隆仓库 +# 1. Clone this repo git clone https://github.com/sipeed/picoclaw.git cd picoclaw -# 2. 首次运行 — 自动生成 docker/data/config.json 后退出 +# 2. First run — auto-generates docker/data/config.json then exits docker compose -f docker/docker-compose.yml --profile gateway up -# 容器打印 "First-run setup complete." 后自动停止 +# The container prints "First-run setup complete." and stops. -# 3. 填写 API Key 等配置 -vim docker/data/config.json # 设置 provider API key、Bot Token 等 +# 3. Set your API keys +vim docker/data/config.json # Set provider API keys, bot tokens, etc. -# 4. 正式启动 +# 4. Start docker compose -f docker/docker-compose.yml --profile gateway up -d ``` > [!TIP] -> **Docker 用户**: 默认情况下, Gateway 监听 `127.0.0.1`，该端口不会暴露到容器外。如果需要通过端口映射访问健康检查接口，请在环境变量中设置 `PICOCLAW_GATEWAY_HOST=0.0.0.0` 或修改 `config.json`。 +> **Docker Users**: By default, the Gateway listens on `127.0.0.1` which is not accessible from the host. If you need to access the health endpoints or expose ports, set `PICOCLAW_GATEWAY_HOST=0.0.0.0` in your environment or update `config.json`. ```bash -# 5. 查看日志 +# 5. Check logs docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway -# 6. 停止 +# 6. Stop docker compose -f docker/docker-compose.yml --profile gateway down ``` -### Agent 模式 (一次性运行) +### Agent Mode (One-shot) ```bash -# 提问 -docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 等于几？" +# Ask a question +docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?" -# 交互模式 +# Interactive mode docker compose -f docker/docker-compose.yml run --rm picoclaw-agent ``` -### 更新镜像 +### Update ```bash docker compose -f docker/docker-compose.yml pull docker compose -f docker/docker-compose.yml --profile gateway up -d ``` -### 🚀 快速开始 +### 🚀 Quick Start > [!TIP] -> 在 `~/.picoclaw/config.json` 中设置您的 API Key。 -> 获取 API Key: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu (智谱)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM) -> 网络搜索是 **可选的** - 获取免费的 [Tavily API](https://tavily.com) (每月 1000 次免费查询) 或 [Brave Search API](https://brave.com/search/api) (每月 2000 次免费查询) +> Set your API key in `~/.picoclaw/config.json`. +> Get API keys: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM) +> Web Search is **optional** - get free [Tavily API](https://tavily.com) (1000 free queries/month) or [Brave Search API](https://brave.com/search/api) (2000 free queries/month) or use built-in auto fallback. -**1. 初始化 (Initialize)** +**1. Initialize** ```bash picoclaw onboard - ``` -**2. 配置 (Configure)** (`~/.picoclaw/config.json`) +**2. Configure** (`~/.picoclaw/config.json`) ```json { @@ -256,88 +256,456 @@ picoclaw onboard "enabled": false, "api_key": "YOUR_TAVILY_API_KEY", "max_results": 5 + }, + "duckduckgo": { + "enabled": true, + "max_results": 5 } - }, - "cron": { - "exec_timeout_minutes": 5 } } } ``` -> **新功能**: `model_list` 配置格式支持零代码添加 provider。详见[模型配置](#模型配置-model_list)章节。 -> `request_timeout` 为可选项，单位为秒。若省略或设置为 `<= 0`，PicoClaw 使用默认超时（120 秒）。 +> **New**: The `model_list` configuration format allows zero-code provider addition. See [Model Configuration](#model-configuration-model_list) for details. +> `request_timeout` is optional and uses seconds. If omitted or set to `<= 0`, PicoClaw uses the default timeout (120s). -**3. 获取 API Key** +**3. Get API Keys** -* **LLM 提供商**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys) -* **网络搜索** (可选): [Tavily](https://tavily.com) - 专为 AI Agent 优化 (1000 请求/月) · [Brave Search](https://brave.com/search/api) - 提供免费层级 (2000 请求/月) +* **LLM Provider**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys) +* **Web Search** (optional): [Tavily](https://tavily.com) - Optimized for AI Agents (1000 requests/month) · [Brave Search](https://brave.com/search/api) - Free tier available (2000 requests/month) -> **注意**: 完整的配置模板请参考 `config.example.json`。 +> **Note**: See `config.example.json` for a complete configuration template. -**4. 对话 (Chat)** +**4. Chat** ```bash -picoclaw agent -m "2+2 等于几？" - +picoclaw agent -m "What is 2+2?" ``` -就是这样！您在 2 分钟内就拥有了一个可工作的 AI 助手。 +That's it! You have a working AI assistant in 2 minutes. --- -## 💬 聊天应用集成 (Chat Apps) +## 💬 Chat Apps -PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方。 +Talk to your picoclaw through Telegram, Discord, DingTalk, LINE, or WeCom -### 核心渠道 +| Channel | Setup | +| ------------ | ---------------------------------- | +| **Telegram** | Easy (just a token) | +| **Discord** | Easy (bot token + intents) | +| **QQ** | Easy (AppID + AppSecret) | +| **DingTalk** | Medium (app credentials) | +| **LINE** | Medium (credentials + webhook URL) | +| **WeCom** | Medium (CorpID + webhook setup) | -| 渠道 | 设置难度 | 特性说明 | 文档链接 | -| -------------------- | ----------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -| **Telegram** | ⭐ 简单 | 推荐，支持语音转文字，长轮询无需公网 | [查看文档](docs/channels/telegram/README.zh.md) | -| **Discord** | ⭐ 简单 | Socket Mode，支持群组/私信，Bot 生态成熟 | [查看文档](docs/channels/discord/README.zh.md) | -| **Slack** | ⭐ 简单 | **Socket Mode** (无需公网 IP)，企业级支持 | [查看文档](docs/channels/slack/README.zh.md) | -| **QQ** | ⭐⭐ 中等 | 官方机器人 API，适合国内社群 | [查看文档](docs/channels/qq/README.zh.md) | -| **钉钉 (DingTalk)** | ⭐⭐ 中等 | Stream 模式无需公网，企业办公首选 | [查看文档](docs/channels/dingtalk/README.zh.md) | -| **企业微信 (WeCom)** | ⭐⭐⭐ 较难 | 支持群机器人(Webhook)和自建应用(API) | [Bot 文档](docs/channels/wecom/wecom_bot/README.zh.md) / [App 文档](docs/channels/wecom/wecom_app/README.zh.md) | -| **飞书 (Feishu)** | ⭐⭐⭐ 较难 | 企业级协作，功能丰富 | [查看文档](docs/channels/feishu/README.zh.md) | -| **Line** | ⭐⭐⭐ 较难 | 需要 HTTPS Webhook | [查看文档](docs/channels/line/README.zh.md) | -| **OneBot** | ⭐⭐ 中等 | 兼容 NapCat/Go-CQHTTP，社区生态丰富 | [查看文档](docs/channels/onebot/README.zh.md) | -| **MaixCam** | ⭐ 简单 | 专为 AI 摄像头设计的硬件集成通道 | [查看文档](docs/channels/maixcam/README.zh.md) | +
+Telegram (Recommended) -## ClawdChat 加入 Agent 社交网络 +**1. Create a bot** -只需通过 CLI 或任何集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。 +* Open Telegram, search `@BotFather` +* Send `/newbot`, follow prompts +* Copy the token -\*\*阅读 `https://clawdchat.ai/skill.md` 并按照说明加入 [ClawdChat.ai](https://clawdchat.ai) +**2. Configure** -## ⚙️ 配置详解 +```json +{ + "channels": { + "telegram": { + "enabled": true, + "token": "YOUR_BOT_TOKEN", + "allow_from": ["YOUR_USER_ID"] + } + } +} +``` -配置文件路径: `~/.picoclaw/config.json` +> Get your user ID from `@userinfobot` on Telegram. -### 工作区布局 (Workspace Layout) +**3. Run** -PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/workspace`）： +```bash +picoclaw gateway +``` + +
+ +
+Discord + +**1. Create a bot** + +* Go to +* Create an application → Bot → Add Bot +* Copy the bot token + +**2. Enable intents** + +* In the Bot settings, enable **MESSAGE CONTENT INTENT** +* (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data + +**3. Get your User ID** +* Discord Settings → Advanced → enable **Developer Mode** +* Right-click your avatar → **Copy User ID** + +**4. Configure** + +```json +{ + "channels": { + "discord": { + "enabled": true, + "token": "YOUR_BOT_TOKEN", + "allow_from": ["YOUR_USER_ID"], + "mention_only": false + } + } +} +``` + +**5. Invite the bot** + +* OAuth2 → URL Generator +* Scopes: `bot` +* Bot Permissions: `Send Messages`, `Read Message History` +* Open the generated invite URL and add the bot to your server + +**Optional: Mention-only mode** + +Set `"mention_only": true` to make the bot respond only when @-mentioned. Useful for shared servers where you want the bot to respond only when explicitly called. + +**6. Run** + +```bash +picoclaw gateway +``` + +
+ +
+QQ + +**1. Create a bot** + +- Go to [QQ Open Platform](https://q.qq.com/#) +- Create an application → Get **AppID** and **AppSecret** + +**2. Configure** + +```json +{ + "channels": { + "qq": { + "enabled": true, + "app_id": "YOUR_APP_ID", + "app_secret": "YOUR_APP_SECRET", + "allow_from": [] + } + } +} +``` + +> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access. + +**3. Run** + +```bash +picoclaw gateway +``` + +
+ +
+DingTalk + +**1. Create a bot** + +* Go to [Open Platform](https://open.dingtalk.com/) +* Create an internal app +* Copy Client ID and Client Secret + +**2. Configure** + +```json +{ + "channels": { + "dingtalk": { + "enabled": true, + "client_id": "YOUR_CLIENT_ID", + "client_secret": "YOUR_CLIENT_SECRET", + "allow_from": [] + } + } +} +``` + +> Set `allow_from` to empty to allow all users, or specify DingTalk user IDs to restrict access. + +**3. Run** + +```bash +picoclaw gateway +``` +
+ +
+LINE + +**1. Create a LINE Official Account** + +- Go to [LINE Developers Console](https://developers.line.biz/) +- Create a provider → Create a Messaging API channel +- Copy **Channel Secret** and **Channel Access Token** + +**2. Configure** + +```json +{ + "channels": { + "line": { + "enabled": true, + "channel_secret": "YOUR_CHANNEL_SECRET", + "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN", + "webhook_host": "0.0.0.0", + "webhook_port": 18791, + "webhook_path": "/webhook/line", + "allow_from": [] + } + } +} +``` + +**3. Set up Webhook URL** + +LINE requires HTTPS for webhooks. Use a reverse proxy or tunnel: + +```bash +# Example with ngrok +ngrok http 18791 +``` + +Then set the Webhook URL in LINE Developers Console to `https://your-domain/webhook/line` and enable **Use webhook**. + +**4. Run** + +```bash +picoclaw gateway +``` + +> In group chats, the bot responds only when @mentioned. Replies quote the original message. + +> **Docker Compose**: Add `ports: ["18791:18791"]` to the `picoclaw-gateway` service to expose the webhook port. + +
+ +
+WeCom (企业微信) + +PicoClaw supports two types of WeCom integration: + +**Option 1: WeCom Bot (智能机器人)** - Easier setup, supports group chats +**Option 2: WeCom App (自建应用)** - More features, proactive messaging + +See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detailed setup instructions. + +**Quick Setup - WeCom Bot:** + +**1. Create a bot** + +* Go to WeCom Admin Console → Group Chat → Add Group Bot +* Copy the webhook URL (format: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`) + +**2. Configure** + +```json +{ + "channels": { + "wecom": { + "enabled": true, + "token": "YOUR_TOKEN", + "encoding_aes_key": "YOUR_ENCODING_AES_KEY", + "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY", + "webhook_host": "0.0.0.0", + "webhook_port": 18793, + "webhook_path": "/webhook/wecom", + "allow_from": [] + } + } +} +``` + +**Quick Setup - WeCom App:** + +**1. Create an app** + +* Go to WeCom Admin Console → App Management → Create App +* Copy **AgentId** and **Secret** +* Go to "My Company" page, copy **CorpID** +**2. Configure receive message** + +* In App details, click "Receive Message" → "Set API" +* Set URL to `http://your-server:18792/webhook/wecom-app` +* Generate **Token** and **EncodingAESKey** + +**3. Configure** + +```json +{ + "channels": { + "wecom_app": { + "enabled": true, + "corp_id": "wwxxxxxxxxxxxxxxxx", + "corp_secret": "YOUR_CORP_SECRET", + "agent_id": 1000002, + "token": "YOUR_TOKEN", + "encoding_aes_key": "YOUR_ENCODING_AES_KEY", + "webhook_host": "0.0.0.0", + "webhook_port": 18792, + "webhook_path": "/webhook/wecom-app", + "allow_from": [] + } + } +} +``` + +**4. Run** + +```bash +picoclaw gateway +``` + +> **Note**: WeCom App requires opening port 18792 for webhook callbacks. Use a reverse proxy for HTTPS. + +
+ +## ClawdChat Join the Agent Social Network + +Connect Picoclaw to the Agent Social Network simply by sending a single message via the CLI or any integrated Chat App. + +**Read `https://clawdchat.ai/skill.md` and follow the instructions to join [ClawdChat.ai](https://clawdchat.ai)** + +## ⚙️ Configuration + +Config file: `~/.picoclaw/config.json` + +### Workspace Layout + +PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspace`): ``` ~/.picoclaw/workspace/ -├── sessions/ # 对话会话和历史 -├── memory/ # 长期记忆 (MEMORY.md) -├── state/ # 持久化状态 (最后一次频道等) -├── cron/ # 定时任务数据库 -├── skills/ # 自定义技能 -├── AGENTS.md # Agent 行为指南 -├── HEARTBEAT.md # 周期性任务提示词 (每 30 分钟检查一次) -├── IDENTITY.md # Agent 身份设定 -├── SOUL.md # Agent 灵魂/性格 -├── TOOLS.md # 工具描述 -└── USER.md # 用户偏好 - +├── sessions/ # Conversation sessions and history +├── memory/ # Long-term memory (MEMORY.md) +├── state/ # Persistent state (last channel, etc.) +├── cron/ # Scheduled jobs database +├── skills/ # Custom skills +├── AGENTS.md # Agent behavior guide +├── HEARTBEAT.md # Periodic task prompts (checked every 30 min) +├── IDENTITY.md # Agent identity +├── SOUL.md # Agent soul +├── TOOLS.md # Tool descriptions +└── USER.md # User preferences ``` -### 心跳 / 周期性任务 (Heartbeat) +### 🔒 Security Sandbox -PicoClaw 可以自动执行周期性任务。在工作区创建 `HEARTBEAT.md` 文件： +PicoClaw runs in a sandboxed environment by default. The agent can only access files and execute commands within the configured workspace. + +#### Default Configuration + +```json +{ + "agents": { + "defaults": { + "workspace": "~/.picoclaw/workspace", + "restrict_to_workspace": true + } + } +} +``` + +| Option | Default | Description | +| ----------------------- | ----------------------- | ----------------------------------------- | +| `workspace` | `~/.picoclaw/workspace` | Working directory for the agent | +| `restrict_to_workspace` | `true` | Restrict file/command access to workspace | + +#### Protected Tools + +When `restrict_to_workspace: true`, the following tools are sandboxed: + +| Tool | Function | Restriction | +| ------------- | ---------------- | -------------------------------------- | +| `read_file` | Read files | Only files within workspace | +| `write_file` | Write files | Only files within workspace | +| `list_dir` | List directories | Only directories within workspace | +| `edit_file` | Edit files | Only files within workspace | +| `append_file` | Append to files | Only files within workspace | +| `exec` | Execute commands | Command paths must be within workspace | + +#### Additional Exec Protection + +Even with `restrict_to_workspace: false`, the `exec` tool blocks these dangerous commands: + +* `rm -rf`, `del /f`, `rmdir /s` — Bulk deletion +* `format`, `mkfs`, `diskpart` — Disk formatting +* `dd if=` — Disk imaging +* Writing to `/dev/sd[a-z]` — Direct disk writes +* `shutdown`, `reboot`, `poweroff` — System shutdown +* Fork bomb `:(){ :|:& };:` + +#### Error Examples + +``` +[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)} +``` + +#### Disabling Restrictions (Security Risk) + +If you need the agent to access paths outside the workspace: + +**Method 1: Config file** + +```json +{ + "agents": { + "defaults": { + "restrict_to_workspace": false + } + } +} +``` + +**Method 2: Environment variable** + +```bash +export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false +``` + +> ⚠️ **Warning**: Disabling this restriction allows the agent to access any path on your system. Use with caution in controlled environments only. + +#### Security Boundary Consistency + +The `restrict_to_workspace` setting applies consistently across all execution paths: + +| Execution Path | Security Boundary | +| ---------------- | ---------------------------- | +| Main Agent | `restrict_to_workspace` ✅ | +| Subagent / Spawn | Inherits same restriction ✅ | +| Heartbeat tasks | Inherits same restriction ✅ | + +All paths share the same workspace restriction — there's no way to bypass the security boundary through subagents or scheduled tasks. + +### Heartbeat (Periodic Tasks) + +PicoClaw can perform periodic tasks automatically. Create a `HEARTBEAT.md` file in your workspace: ```markdown # Periodic Tasks @@ -347,11 +715,11 @@ PicoClaw 可以自动执行周期性任务。在工作区创建 `HEARTBEAT.md` - Check the weather forecast ``` -Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具执行任务。 +The agent will read this file every 30 minutes (configurable) and execute any tasks using available tools. -#### 使用 Spawn 的异步任务 +#### Async Tasks with Spawn -对于耗时较长的任务（网络搜索、API 调用），使用 `spawn` 工具创建一个 **子 Agent (subagent)**： +For long-running tasks (web search, API calls), use the `spawn` tool to create a **subagent**: ```markdown # Periodic Tasks @@ -366,35 +734,34 @@ Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具 - Check email and report important messages ``` -**关键行为：** +**Key behaviors:** -| 特性 | 描述 | -| ---------------- | ---------------------------------------- | -| **spawn** | 创建异步子 Agent，不阻塞主心跳进程 | -| **独立上下文** | 子 Agent 拥有独立上下文，无会话历史 | -| **message tool** | 子 Agent 通过 message 工具直接与用户通信 | -| **非阻塞** | spawn 后，心跳继续处理下一个任务 | +| Feature | Description | +| ----------------------- | --------------------------------------------------------- | +| **spawn** | Creates async subagent, doesn't block heartbeat | +| **Independent context** | Subagent has its own context, no session history | +| **message tool** | Subagent communicates with user directly via message tool | +| **Non-blocking** | After spawning, heartbeat continues to next task | -#### 子 Agent 通信原理 +#### How Subagent Communication Works ``` -心跳触发 (Heartbeat triggers) +Heartbeat triggers ↓ -Agent 读取 HEARTBEAT.md +Agent reads HEARTBEAT.md ↓ -对于长任务: spawn 子 Agent +For long task: spawn subagent ↓ ↓ -继续下一个任务 子 Agent 独立工作 +Continue to next task Subagent works independently ↓ ↓ -所有任务完成 子 Agent 使用 "message" 工具 +All tasks done Subagent uses "message" tool ↓ ↓ -响应 HEARTBEAT_OK 用户直接收到结果 - +Respond HEARTBEAT_OK User receives result directly ``` -子 Agent 可以访问工具（message, web_search 等），并且无需通过主 Agent 即可独立与用户通信。 +The subagent has access to tools (message, web_search, etc.) and can communicate with the user independently without going through the main agent. -**配置：** +**Configuration:** ```json { @@ -405,68 +772,68 @@ Agent 读取 HEARTBEAT.md } ``` -| 选项 | 默认值 | 描述 | -| ---------- | ------ | ---------------------------- | -| `enabled` | `true` | 启用/禁用心跳 | -| `interval` | `30` | 检查间隔，单位分钟 (最小: 5) | +| Option | Default | Description | +| ---------- | ------- | ---------------------------------- | +| `enabled` | `true` | Enable/disable heartbeat | +| `interval` | `30` | Check interval in minutes (min: 5) | -**环境变量:** +**Environment variables:** -- `PICOCLAW_HEARTBEAT_ENABLED=false` 禁用 -- `PICOCLAW_HEARTBEAT_INTERVAL=60` 更改间隔 +* `PICOCLAW_HEARTBEAT_ENABLED=false` to disable +* `PICOCLAW_HEARTBEAT_INTERVAL=60` to change interval -### 提供商 (Providers) +### Providers > [!NOTE] -> Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，Telegram 语音消息将被自动转录为文字。 +> Groq provides free voice transcription via Whisper. If configured, Telegram voice messages will be automatically transcribed. -| 提供商 | 用途 | 获取 API Key | -| -------------------- | ---------------------------- | -------------------------------------------------------------------- | -| `gemini` | LLM (Gemini 直连) | [aistudio.google.com](https://aistudio.google.com) | -| `zhipu` | LLM (智谱直连) | [bigmodel.cn](bigmodel.cn) | -| `openrouter(待测试)` | LLM (推荐，可访问所有模型) | [openrouter.ai](https://openrouter.ai) | -| `anthropic(待测试)` | LLM (Claude 直连) | [console.anthropic.com](https://console.anthropic.com) | -| `openai(待测试)` | LLM (GPT 直连) | [platform.openai.com](https://platform.openai.com) | -| `deepseek(待测试)` | LLM (DeepSeek 直连) | [platform.deepseek.com](https://platform.deepseek.com) | -| `qwen` | LLM (通义千问) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | -| `groq` | LLM + **语音转录** (Whisper) | [console.groq.com](https://console.groq.com) | -| `cerebras` | LLM (Cerebras 直连) | [cerebras.ai](https://cerebras.ai) | +| Provider | Purpose | Get API Key | +| -------------------------- | --------------------------------------- | -------------------------------------------------------------------- | +| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) | +| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](https://bigmodel.cn) | +| `openrouter(To be tested)` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) | +| `anthropic(To be tested)` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) | +| `openai(To be tested)` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) | +| `deepseek(To be tested)` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) | +| `qwen` | LLM (Qwen direct) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | +| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) | +| `cerebras` | LLM (Cerebras direct) | [cerebras.ai](https://cerebras.ai) | -### 模型配置 (model_list) +### Model Configuration (model_list) -> **新功能！** PicoClaw 现在采用**以模型为中心**的配置方式。只需使用 `厂商/模型` 格式（如 `zhipu/glm-4.7`）即可添加新的 provider——**无需修改任何代码！** +> **What's New?** PicoClaw now uses a **model-centric** configuration approach. Simply specify `vendor/model` format (e.g., `zhipu/glm-4.7`) to add new providers—**zero code changes required!** -该设计同时支持**多 Agent 场景**，提供灵活的 Provider 选择： +This design also enables **multi-agent support** with flexible provider selection: -- **不同 Agent 使用不同 Provider**：每个 Agent 可以使用自己的 LLM provider -- **模型回退（Fallback）**：配置主模型和备用模型，提高可靠性 -- **负载均衡**：在多个 API 端点之间分配请求 -- **集中化配置**：在一个地方管理所有 provider +- **Different agents, different providers**: Each agent can use its own LLM provider +- **Model fallbacks**: Configure primary and fallback models for resilience +- **Load balancing**: Distribute requests across multiple endpoints +- **Centralized configuration**: Manage all providers in one place -#### 📋 所有支持的厂商 +#### 📋 All Supported Vendors -| 厂商 | `model` 前缀 | 默认 API Base | 协议 | 获取 API Key | -| ------------------- | ----------------- | --------------------------------------------------- | --------- | ----------------------------------------------------------------- | -| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [获取密钥](https://platform.openai.com) | -| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [获取密钥](https://console.anthropic.com) | -| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [获取密钥](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | -| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [获取密钥](https://platform.deepseek.com) | -| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [获取密钥](https://aistudio.google.com/api-keys) | -| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [获取密钥](https://console.groq.com) | -| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [获取密钥](https://platform.moonshot.cn) | -| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [获取密钥](https://dashscope.console.aliyun.com) | -| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [获取密钥](https://build.nvidia.com) | -| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | 本地（无需密钥） | -| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [获取密钥](https://openrouter.ai/keys) | -| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | 本地 | -| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [获取密钥](https://cerebras.ai) | -| **火山引擎** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [获取密钥](https://console.volcengine.com) | -| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - | -| **Antigravity** | `antigravity/` | Google Cloud | 自定义 | 仅 OAuth | -| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - | -| **Cloudflare AI Gateway** | `cloudflare/` | `https://gateway.ai.cloudflare.com/v1/YOUR_ACCOUNT_ID/YOUR_GATEWAY_ID/compat` | OpenAI | [获取令牌](https://www.cloudflare.com/zh-tw/developer-platform/products/ai-gateway/) | +| Vendor | `model` Prefix | Default API Base | Protocol | API Key | +| ------------------- | ----------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- | +| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Get Key](https://platform.openai.com) | +| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Get Key](https://console.anthropic.com) | +| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | +| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Get Key](https://platform.deepseek.com) | +| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Get Key](https://aistudio.google.com/api-keys) | +| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Get Key](https://console.groq.com) | +| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Get Key](https://platform.moonshot.cn) | +| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Get Key](https://dashscope.console.aliyun.com) | +| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Get Key](https://build.nvidia.com) | +| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (no key needed) | +| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Get Key](https://openrouter.ai/keys) | +| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local | +| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Get Key](https://cerebras.ai) | +| **火山引擎** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Get Key](https://console.volcengine.com) | +| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - | +| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth only | +| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - | +| **Cloudflare AI Gateway** | `cloudflare/` | `https://gateway.ai.cloudflare.com/v1/YOUR_ACCOUNT_ID/YOUR_GATEWAY_ID/compat` | OpenAI | [Get Token](https://www.cloudflare.com/zh-tw/developer-platform/products/ai-gateway/) | -#### 基础配置示例 +#### Basic Configuration ```json { @@ -495,7 +862,7 @@ Agent 读取 HEARTBEAT.md } ``` -#### 各厂商配置示例 +#### Vendor-Specific Examples **OpenAI** @@ -527,19 +894,19 @@ Agent 读取 HEARTBEAT.md } ``` -**Anthropic (使用 OAuth)** +**Anthropic (with API key)** ```json { "model_name": "claude-sonnet-4.6", "model": "anthropic/claude-sonnet-4.6", - "auth_method": "oauth" + "api_key": "sk-ant-your-key" } ``` -> 运行 `picoclaw auth login --provider anthropic` 来设置 OAuth 凭证。 +> Run `picoclaw auth login --provider anthropic` to paste your API token. -**Ollama (本地)** +**Ollama (local)** ```json { @@ -548,7 +915,7 @@ Agent 读取 HEARTBEAT.md } ``` -**自定义代理/API** +**Custom Proxy/API** ```json { @@ -560,9 +927,9 @@ Agent 读取 HEARTBEAT.md } ``` -**Cloudflare AI Gateway（统一计费）** +**Cloudflare AI Gateway (Unified Billing)** -使用 Cloudflare 的计费来支付上游服务商 —— 无需各个服务商的 API Key： +Use Cloudflare's billing to pay for upstream providers — no individual API keys needed: ```json { @@ -573,9 +940,9 @@ Agent 读取 HEARTBEAT.md } ``` -**Cloudflare AI Gateway（BYOK — 自带密钥）** +**Cloudflare AI Gateway (BYOK — Bring Your Own Key)** -通过 Cloudflare 路由请求，同时使用自己的服务商 API Key： +Route through Cloudflare while using your own provider API key: ```json { @@ -589,7 +956,7 @@ Agent 读取 HEARTBEAT.md **Cloudflare Workers AI** -通过 Cloudflare Workers AI 运行无服务器推理模型： +Run serverless inference via Cloudflare Workers AI models: ```json { @@ -600,11 +967,11 @@ Agent 读取 HEARTBEAT.md } ``` -> 详见 [Cloudflare AI Gateway 文档](https://developers.cloudflare.com/ai-gateway/)、[Workers AI 模型列表](https://developers.cloudflare.com/workers-ai/models/) 和 [Workers AI 定价](https://developers.cloudflare.com/workers-ai/platform/pricing/)。 +> See [Cloudflare AI Gateway docs](https://developers.cloudflare.com/ai-gateway/), [Workers AI models](https://developers.cloudflare.com/workers-ai/models/), and [Workers AI pricing](https://developers.cloudflare.com/workers-ai/platform/pricing/) for more details. -#### 负载均衡 +#### Load Balancing -为同一个模型名称配置多个端点——PicoClaw 会自动在它们之间轮询： +Configure multiple endpoints for the same model name—PicoClaw will automatically round-robin between them: ```json { @@ -625,11 +992,11 @@ Agent 读取 HEARTBEAT.md } ``` -#### 从旧的 `providers` 配置迁移 +#### Migration from Legacy `providers` Config -旧的 `providers` 配置格式**已弃用**，但为向后兼容仍支持。 +The old `providers` configuration is **deprecated** but still supported for backward compatibility. -**旧配置（已弃用）：** +**Old Config (deprecated):** ```json { @@ -648,7 +1015,7 @@ Agent 读取 HEARTBEAT.md } ``` -**新配置（推荐）：** +**New Config (recommended):** ```json { @@ -667,16 +1034,27 @@ Agent 读取 HEARTBEAT.md } ``` -详细的迁移指南请参考 [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md)。 +For detailed migration guide, see [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md). + +### Provider Architecture + +PicoClaw routes providers by protocol family: + +- OpenAI-compatible protocol: OpenRouter, OpenAI-compatible gateways, Groq, Zhipu, and vLLM-style endpoints. +- Anthropic protocol: Claude-native API behavior. +- Codex/OAuth path: OpenAI OAuth/token authentication route. +- Cloudflare AI Gateway: unified OpenAI-compatible proxy supporting multiple upstream providers (OpenAI, Anthropic, Google, Workers AI) via `cf-aig-authorization` header. + +This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_key`).
-智谱 (Zhipu) 配置示例 +Zhipu -**1. 获取 API key 和 base URL** +**1. Get API key and base URL** -- 获取 [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) +* Get [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) -**2. 配置** +**2. Configure** ```json { @@ -698,17 +1076,16 @@ Agent 读取 HEARTBEAT.md } ``` -**3. 运行** +**3. Run** ```bash -picoclaw agent -m "你好" - +picoclaw agent -m "Hello" ```
-完整配置示例 +Full config example ```json { @@ -758,7 +1135,7 @@ picoclaw agent -m "你好" "web": { "brave": { "enabled": false, - "api_key": "YOUR_BRAVE_API_KEY", + "api_key": "BSA...", "max_results": 5 }, "duckduckgo": { @@ -779,52 +1156,54 @@ picoclaw agent -m "你好"
-## CLI 命令行参考 +## CLI Reference -| 命令 | 描述 | -| ------------------------- | ------------------ | -| `picoclaw onboard` | 初始化配置和工作区 | -| `picoclaw agent -m "..."` | 与 Agent 对话 | -| `picoclaw agent` | 交互式聊天模式 | -| `picoclaw gateway` | 启动网关 (Gateway) | -| `picoclaw status` | 显示状态 | -| `picoclaw cron list` | 列出所有定时任务 | -| `picoclaw cron add ...` | 添加定时任务 | +| Command | Description | +| ------------------------- | ----------------------------- | +| `picoclaw onboard` | Initialize config & workspace | +| `picoclaw agent -m "..."` | Chat with the agent | +| `picoclaw agent` | Interactive chat mode | +| `picoclaw gateway` | Start the gateway | +| `picoclaw status` | Show status | +| `picoclaw cron list` | List all scheduled jobs | +| `picoclaw cron add ...` | Add a scheduled job | -### 定时任务 / 提醒 (Scheduled Tasks) +### Scheduled Tasks / Reminders -PicoClaw 通过 `cron` 工具支持定时提醒和重复任务： +PicoClaw supports scheduled reminders and recurring tasks through the `cron` tool: -- **一次性提醒**: "Remind me in 10 minutes" (10分钟后提醒我) → 10分钟后触发一次 -- **重复任务**: "Remind me every 2 hours" (每2小时提醒我) → 每2小时触发 -- **Cron 表达式**: "Remind me at 9am daily" (每天上午9点提醒我) → 使用 cron 表达式 +* **One-time reminders**: "Remind me in 10 minutes" → triggers once after 10min +* **Recurring tasks**: "Remind me every 2 hours" → triggers every 2 hours +* **Cron expressions**: "Remind me at 9am daily" → uses cron expression -任务存储在 `~/.picoclaw/workspace/cron/` 中并自动处理。 +Jobs are stored in `~/.picoclaw/workspace/cron/` and processed automatically. -## 🤝 贡献与路线图 (Roadmap) +## 🤝 Contribute & Roadmap -欢迎提交 PR！代码库刻意保持小巧和可读。🤗 +PRs welcome! The codebase is intentionally small and readable. 🤗 -路线图即将发布... +See our full [Community Roadmap](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md). -开发者群组正在组建中，入群门槛：至少合并过 1 个 PR。 +Developer group building, join after your first merged PR! -用户群组： +User Groups: -Discord: [https://discord.gg/V4sAZ9XWpN](https://discord.gg/V4sAZ9XWpN) +discord: PicoClaw -## 🐛 疑难解答 (Troubleshooting) +## 🐛 Troubleshooting -### 网络搜索提示 "API 配置问题" +### Web search says "API key configuration issue" -如果您尚未配置搜索 API Key，这是正常的。PicoClaw 会提供手动搜索的帮助链接。 +This is normal if you haven't configured a search API key yet. PicoClaw will provide helpful links for manual searching. -启用网络搜索： +To enable web search: -1. 在 [https://tavily.com](https://tavily.com) (1000 次免费) 或 [https://brave.com/search/api](https://brave.com/search/api) 获取免费 API Key (2000 次免费) -2. 添加到 `~/.picoclaw/config.json`: +1. **Option 1 (Recommended)**: Get a free API key at [https://brave.com/search/api](https://brave.com/search/api) (2000 free queries/month) for the best results. +2. **Option 2 (No Credit Card)**: If you don't have a key, we automatically fall back to **DuckDuckGo** (no key required). + +Add the key to `~/.picoclaw/config.json` if using Brave: ```json { @@ -844,23 +1223,23 @@ Discord: [https://discord.gg/V4sAZ9XWpN](https://discord.gg/V4sAZ9XWpN) } ``` -### 遇到内容过滤错误 (Content Filtering Errors) +### Getting content filtering errors -某些提供商（如智谱）有严格的内容过滤。尝试改写您的问题或使用其他模型。 +Some providers (like Zhipu) have content filtering. Try rephrasing your query or use a different model. -### Telegram bot 提示 "Conflict: terminated by other getUpdates" +### Telegram bot says "Conflict: terminated by other getUpdates" -这表示有另一个机器人实例正在运行。请确保同一时间只有一个 `picoclaw gateway` 进程在运行。 +This happens when another instance of the bot is running. Make sure only one `picoclaw gateway` is running at a time. --- -## 📝 API Key 对比 +## 📝 API Key Comparison -| 服务 | 免费层级 | 适用场景 | -| --- | --- | --- | -| **OpenRouter** | 200K tokens/月 | 多模型聚合 (Claude, GPT-4 等) | -| **智谱 (Zhipu)** | 200K tokens/月 | 最适合中国用户 | -| **Brave Search** | 2000 次查询/月 | 网络搜索功能 | -| **Tavily** | 1000 次查询/月 | AI Agent 搜索优化 | -| **Groq** | 提供免费层级 | 极速推理 (Llama, Mixtral) | -| **Cloudflare AI Gateway** | Workers AI 免费层级 | 多提供商统一计费，无服务器模型 | +| Service | Free Tier | Use Case | +| -------------------------- | --------------------- | ------------------------------------- | +| **OpenRouter** | 200K tokens/month | Multiple models (Claude, GPT-4, etc.) | +| **Zhipu** | 200K tokens/month | Best for Chinese users | +| **Brave Search** | 2000 queries/month | Web search functionality | +| **Groq** | Free tier available | Fast inference (Llama, Mixtral) | +| **Cerebras** | Free tier available | Fast inference (Llama, Qwen, etc.) | +| **Cloudflare AI Gateway** | Workers AI free tier | Unified billing for multiple providers, serverless models | diff --git a/README.zh.md b/README.zh.md index 449e3d774..cdd644fd8 100644 --- a/README.zh.md +++ b/README.zh.md @@ -600,7 +600,7 @@ Agent 读取 HEARTBEAT.md } ``` -> 详见 [Cloudflare AI Gateway 文档](https://developers.cloudflare.com/ai-gateway/) 和 [Workers AI 模型列表](https://developers.cloudflare.com/workers-ai/models/)。 +> 详见 [Cloudflare AI Gateway 文档](https://developers.cloudflare.com/ai-gateway/)、[Workers AI 模型列表](https://developers.cloudflare.com/workers-ai/models/) 和 [Workers AI 定价](https://developers.cloudflare.com/workers-ai/platform/pricing/)。 #### 负载均衡 @@ -863,3 +863,4 @@ Discord: [https://discord.gg/V4sAZ9XWpN](https://discord.gg/V4sAZ9XWpN) | **Brave Search** | 2000 次查询/月 | 网络搜索功能 | | **Tavily** | 1000 次查询/月 | AI Agent 搜索优化 | | **Groq** | 提供免费层级 | 极速推理 (Llama, Mixtral) | +| **Cloudflare AI Gateway** | Workers AI 免费层级 | 多提供商统一计费，无服务器模型 |