🧹 cleanup: remove translations and consolidate documentation to English

- Remove all non-English README and CONTRIBUTING files. - Translate Chinese documentation for DingTalk, Discord, LINE, MaixCam, OneBot, QQ, Slack, and Telegram to English. - Translate design document for Issue #783 to English. - Clean up root README.md and CONTRIBUTING.md to remove translation links and bilingual text. - Standardize all repository documentation to English. Co-authored-by: hobbyistlabs-coder <267281733+hobbyistlabs-coder@users.noreply.github.com>
2026-03-13 21:03:23 +00:00 · 2026-03-13 21:03:23 +00:00 · 5a077d0139
commit 5a077d0139
parent 5b1e5e9f17
28 changed files with 333 additions and 7301 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -108,7 +108,7 @@ Use descriptive branch names, e.g. `fix/telegram-timeout`, `feat/ollama-provider
 - Reference the related issue when relevant: `Fix session leak (#123)`.
 - Keep commits focused. One logical change per commit is preferred.
 - For minor cleanups or typo fixes, squash them into a single commit before opening a PR.
- Refer to https://www.conventionalcommits.org/zh-hans/v1.0.0/
+- Refer to https://www.conventionalcommits.org/en/v1.0.0/

 ### Keeping Up to Date

--- a/CONTRIBUTING.zh.md
+++ b/CONTRIBUTING.zh.md
@ -1,303 +0,0 @@
-# 参与贡献 PicoClaw
-
-感谢你对 PicoClaw 的关注！本项目是一个社区驱动的开源项目，目标是构建 轻量灵活,人人可用 的个人AI助手。我们欢迎一切形式的贡献：Bug 修复、新功能、文档、翻译和测试。
-
-PicoClaw 本身在很大程度上是借助 AI 辅助开发的——我们拥抱这种方式，并围绕它构建了贡献流程。
-
-## 目录
-
- [行为准则](#行为准则)
- [贡献方式](#贡献方式)
- [快速开始](#快速开始)
- [开发环境配置](#开发环境配置)
- [提交修改](#提交修改)
- [AI 辅助贡献](#ai-辅助贡献)
- [Pull Request 流程](#pull-request-流程)
- [分支策略](#分支策略)
- [代码审查](#代码审查)
- [沟通渠道](#沟通渠道)
-
---
-
-## 行为准则
-
-我们致力于维护一个友好、互相尊重的社区环境。请保持善意、建设性的态度，并善意地理解他人。任何形式的骚扰或歧视均不被接受。
-
---
-
-## 贡献方式
-
- **Bug 反馈** — 使用 Bug 报告模板提交 Issue。
- **功能建议** — 使用功能请求模板提交 Issue，建议在开始实现前先进行讨论。
- **代码贡献** — 修复 Bug 或实现新功能，参见下方工作流程。
- **文档改进** — 完善 README、文档、代码注释或翻译。
- **测试与验证** — 在新硬件、新渠道或新 LLM 提供商上运行 PicoClaw 并反馈结果。
-
-对于较大的新功能，请先提交 Issue 讨论设计方案，再动手写代码。这能避免无效投入，也确保与项目方向保持一致。
-
---
-
-## 快速开始
-
-1. 在 GitHub 上 **Fork** 本仓库。
-2. 将你的 Fork **克隆**到本地：
-   ```bash
-   git clone https://github.com/<你的用户名>/picoclaw.git
-   cd picoclaw
-   ```
-3. 添加上游远程仓库：
-   ```bash
-   git remote add upstream https://github.com/sipeed/picoclaw.git
-   ```
-
---
-
-## 开发环境配置
-
-### 前置依赖
-
- Go 1.25 或更高版本
- `make`
-
-### 构建
-
-```bash
-make build       # 构建二进制文件（会先执行 go generate）
-make generate    # 仅执行 go generate
-make check       # 完整的提交前检查：deps + fmt + vet + test
-```
-
-### 运行测试
-
-```bash
-make test                                    # 运行所有测试
-go test -run TestName -v ./pkg/session/      # 运行单个测试
-go test -bench=. -benchmem -run='^$' ./...  # 运行基准测试
-```
-
-### 代码风格
-
-```bash
-make fmt   # 格式化代码
-make vet   # 静态分析
-make lint  # 完整的 lint 检查
-```
-
-所有 CI 检查通过后 PR 才能被合并。推送代码前请先在本地运行 `make check`，提前发现问题。
-
---
-
-## 提交修改
-
-### 分支管理
-
-始终从 `main` 分支切出，并在 PR 中以 `main` 为目标分支。不要直接向 `main` 或任何 `release/*` 分支推送代码：
-
-```bash
-git checkout main
-git pull upstream main
-git checkout -b 你的功能分支名
-```
-
-请使用描述性的分支名，例如：`fix/telegram-timeout`、`feat/ollama-provider`、`docs/contributing-guide`。
-
-### Commit 规范
-
- 使用英文撰写清晰、简洁的 commit 信息。
- 使用祈使句：写 "Add retry logic"，而不是 "Added retry logic"。
- 有关联 Issue 时请引用：`Fix session leak (#123)`。
- 保持 commit 专注，每个 commit 只做一件事。
- 对于小的清理或拼写修正，提 PR 前请将其合并为一个 commit。
- 按照 https://www.conventionalcommits.org/zh-hans/v1.0.0/ 规范来撰写
-
-### 保持与上游同步
-
-提 PR 前，请将你的分支变基到上游 `main`：
-
-```bash
-git fetch upstream
-git rebase upstream/main
-```
-
---
-
-## AI 辅助贡献
-
-PicoClaw 在很大程度上借助 AI 辅助开发，我们完全拥抱这种开发方式。但贡献者必须清楚地了解自己在使用 AI 工具时所承担的责任。
-
-### 必须披露 AI 使用情况
-
-每个 PR 都必须通过 PR 模板中的 **🤖 AI 代码生成** 部分披露 AI 参与情况，共分三个级别：
-
-| 级别 | 说明 |
-|---|---|
-| 🤖 完全由 AI 生成 | AI 编写代码，贡献者负责审查和验证 |
-| 🛠️ 主要由 AI 生成 | AI 起草，贡献者做了较大修改 |
-| 👨‍💻 主要由人工编写 | 贡献者主导，AI 仅提供辅助或未使用 AI |
-
-我们期望你诚实填写。三种级别均可接受，没有任何歧视——重要的是贡献的质量。
-
-### 你对提交的代码负全责
-
-使用 AI 生成代码并不能减轻你作为贡献者的责任。在提交含有 AI 生成代码的 PR 之前，你必须：
-
- **逐行阅读并理解**生成的代码。
- **在真实环境中测试**（参见 PR 模板中的测试环境部分）。
- **检查安全问题** — AI 模型可能生成存在安全隐患的代码（如路径穿越、注入攻击、凭据泄露等），请仔细审查。
- **验证正确性** — AI 生成的逻辑可能听起来合理但实际上是错误的，请验证行为，而不仅仅是语法。
-
-如果明显可以看出贡献者没有阅读或测试 AI 生成的代码，该 PR 将被直接关闭，不予审查。
-
-### AI 生成代码的质量标准
-
-AI 生成的代码与人工编写的代码遵循**相同的质量要求**：
-
- 必须通过所有 CI 检查（`make check`）。
- 必须符合 Go 惯用写法，并与现有代码库的风格保持一致。
- 不得引入不必要的抽象、死代码或过度设计。
- 须在适当的地方包含或更新测试。
-
-### 安全审查
-
-AI 生成的代码需要格外仔细的安全审查。请特别关注以下方面：
-
- 文件路径处理与沙箱逃逸（项目历史中的 commit `244eb0b` 就是真实案例）
- channel 处理器和 tool 实现中的外部输入校验
- 凭据或密钥的处理
- 命令执行（`exec.Command`、shell 调用等）
-
-如果你不确定某段 AI 生成代码是否安全，请在 PR 中说明——审查者会帮助判断。
-
---
-
-## Pull Request 流程
-
-### 提 PR 前的检查
-
- [ ] 在本地运行 `make check` 并确认通过。
- [ ] 完整填写 PR 模板，包括 AI 披露部分。
- [ ] 在 PR 描述中关联相关 Issue。
- [ ] 保持 PR 专注，避免将不相关的修改混在一起。
-
-### PR 模板各部分说明
-
-PR 模板要求填写：
-
- **描述** — 这个改动做了什么，为什么要做？
- **变更类型** — Bug 修复、新功能、文档或重构。
- **AI 代码生成** — AI 参与情况披露（必填）。
- **关联 Issue** — 此 PR 解决的 Issue 链接。
- **技术背景** — 参考链接和设计理由（纯文档类 PR 可跳过）。
- **测试环境** — 用于测试的硬件、操作系统、模型/提供商和渠道。
- **验证证据** — 可选的日志或截图，用于证明改动有效。
- **检查清单** — 自我审查确认。
-
-### PR 规模
-
-请尽量提交小而易于审查的 PR。一个涉及 5 个文件共 200 行改动的 PR，远比涉及 30 个文件共 2000 行改动的 PR 容易审查。如果你的功能较大，可以考虑将其拆分为一系列逻辑完整的小 PR。
-
---
-
-## 分支策略
-
-### 长期分支
-
- **`main`** — 活跃开发分支。所有功能 PR 均以 `main` 为目标。该分支受保护：禁止直接推送，合并前必须获得至少一名维护者的批准。
- **`release/x.y`** — 稳定发布分支，在某个版本准备发布时从 `main` 切出。这些分支的保护级别高于 `main`。
-
-### 合并到 `main` 的前提条件
-
-PR 必须同时满足以下所有条件，才能被合并：
-
-1. **CI 全部通过** — 所有 GitHub Actions 工作流（lint、test、build）均为绿色。
-2. **获得审查者批准** — 至少一名维护者已批准该 PR。
-3. **无未解决的审查意见** — 所有审查讨论线程均已关闭。
-4. **PR 模板填写完整** — 包括 AI 披露和测试环境信息。
-
-### 谁可以合并
-
-只有维护者才能合并 PR。贡献者不能合并自己的 PR，即使拥有写权限也不行。
-
-### 合并策略
-
-为保持 `main` 历史清晰可读，我们对大多数 PR 使用 **Squash Merge**。每个合并的 PR 变为一个包含 PR 编号的单独 commit，例如：
-
-```
-feat: Add Ollama provider support (#491)
-```
-
-如果一个 PR 包含多个独立、结构清晰、能讲述完整故事的 commit，维护者可视情况使用普通 merge。
-
-### Release 分支
-
-当某个版本准备就绪时，维护者会从 `main` 切出 `release/x.y` 分支。此后：
-
- **新功能不会被回溯（backport）。** Release 分支切出后，不再接收任何新功能。
- **安全修复和关键 Bug 修复会被 cherry-pick 进来。** 若 `main` 上的某个修复属于安全漏洞、数据丢失或崩溃类问题，维护者会将相关 commit cherry-pick 到受影响的 `release/x.y` 分支，并发布补丁版本。
-
-如果你认为 `main` 上的某个修复应该被回溯到某个 release 分支，请在 PR 描述中注明，或单独开一个 Issue 说明。最终决定由维护者做出。
-
-Release 分支的保护级别高于 `main`，在任何情况下均不允许直接推送。
-
---
-
-## 代码审查
-
-### 对贡献者的建议
-
- 在合理时间内回复审查意见。如果需要更多时间，请告知。
- 更新 PR 以响应反馈时，简要说明改动内容（例如："按建议改用了 `sync.RWMutex`"）。
- 如果你不同意某条反馈，请礼貌地阐述你的理由——审查者也可能有判断失误的时候。
- 审查开始后请不要 force push——这会让审查者难以追踪变化。请使用额外的 commit，维护者在合并时会进行 squash。
-
-### 对审查者的建议
-
-审查重点：
-
-1. **正确性** — 代码是否实现了其声称的功能？是否存在边界情况？
-2. **安全性** — 对 AI 生成代码、tool 实现和 channel 处理器尤其需要关注。
-3. **架构** — 实现方式是否与现有设计一致？
-4. **简洁性** — 是否有更简单的方案？是否引入了不必要的复杂度？
-5. **测试** — 改动是否有测试覆盖？现有测试是否仍然有意义？
-
-请给出建设性且具体的反馈。"如果两个 goroutine 同时调用这个函数可能会有竞态条件，建议在这里加一个 mutex" 远比 "这里看起来有问题" 更有帮助。
-
-### 审查者列表
-提交对应PR后，可以参考下表联系对应的审查人员沟通
-
-|Function| Reviewer|
-|---     |---      |
-|Provider|@yinwm   |
-|Channel |@yinwm/@alexhoshina   |
-|Agent   |@lxowalle/@Zhaoyikaiii|
-|Tools   |@lxowalle|
-|SKill   ||
-|MCP     ||
-|Optimization|@lxowalle|
-|Security||
-|AI CI   |@imguoguo|
-|UX      ||
-|Document||
-
-
-
---
-
-## 沟通渠道
-
- **GitHub Issues** — Bug 报告、功能建议、设计讨论。
- **GitHub Discussions** — 一般性问题、想法交流、社区讨论。
- **Pull Request 评论** — 与具体代码相关的反馈。
- **Wechat&Discord** — 当你有至少一个已合并的PR后，我们会邀请你加入开发者交流群
-
-有疑问时，请先开 Issue 讨论，再动手写代码。这几乎没有成本，却能避免大量无效投入。
-
---
-
-## 关于本项目的 AI 驱动起源
-
-PicoClaw 的架构在人工监督下，经由 AI 辅助完成了大量设计和实现工作。如果你发现某处看起来奇怪或过度设计，这可能是该过程留下的痕迹——欢迎提 Issue 讨论。
-
-我们相信，负责任地使用 AI 辅助开发能产生优秀的成果。我们同样相信，人类必须对自己提交的内容负责。这两点并不矛盾。
-
-感谢你的贡献！
--- a/README.fr.md
+++ b/README.fr.md
--- a/README.ja.md
+++ b/README.ja.md
--- a/README.md
+++ b/README.md
@ -3,7 +3,7 @@

  <h1>PicoClaw: Ultra-Efficient AI Assistant in Go</h1>

-  <h3>$10 Hardware · 10MB RAM · 1s Boot · 皮皮虾，我们走！</h3>
+  <h3>$10 Hardware · 10MB RAM · 1s Boot · PicoClaw, Let's Go!</h3>

  <p>
    <img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
@ -17,8 +17,6 @@
    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
  </p>

-[中文](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**
-
 </div>

 ---
@ -43,7 +41,7 @@
 </table>

 > [!CAUTION]
-> **🚨 SECURITY & OFFICIAL CHANNELS / 安全声明**
+> **🚨 SECURITY & OFFICIAL CHANNELS**
 >
 > * **NO CRYPTO:** PicoClaw has **NO** official token/coin. All claims on `pump.fun` or other trading platforms are **SCAMS**.
 >
@ -59,7 +57,7 @@
 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 Launched! Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. 🦐 PicoClaw，Let's Go！
+2026-02-09 🎉 PicoClaw Launched! Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. 🦐 PicoClaw, Let's Go!

 ## ✨ Features

--- a/README.pt-br.md
+++ b/README.pt-br.md
--- a/README.vi.md
+++ b/README.vi.md
--- a/README.zh.md
+++ b/README.zh.md
@ -1,899 +0,0 @@
-<div align="center">
-<img src="assets/logo.webp" alt="PicoClaw" width="512">
-
-<h1>PicoClaw: 基于Go语言的超高效 AI 助手</h1>
-
-<h3>10$硬件 · 10MB内存 · 1秒启动 · 皮皮虾，我们走！</h3>
-
-  <p>
-    <img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
-    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V-blue" alt="Hardware">
-    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
-    <br>
-    <a href="https://picoclaw.io"><img src="https://img.shields.io/badge/Website-picoclaw.io-blue?style=flat&logo=google-chrome&logoColor=white" alt="Website"></a>
-    <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
-  </p>
-
-**中文** | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [English](README.md)
-
-</div>
-
---
-
-🦐 **PicoClaw** 是一个受 [nanobot](https://github.com/HKUDS/nanobot) 启发的超轻量级个人 AI 助手。它采用 **Go 语言** 从零重构，经历了一个“自举”过程——即由 AI Agent 自身驱动了整个架构迁移和代码优化。
-
-⚡️ **极致轻量**：可在 **10 美元** 的硬件上运行，内存占用 **<10MB**。这意味着比 OpenClaw 节省 99% 的内存，比 Mac mini 便宜 98%！
-
-<table align="center">
-<tr align="center">
-<td align="center" valign="top">
-<p align="center">
-<img src="assets/picoclaw_mem.gif" width="360" height="240">
-</p>
-</td>
-<td align="center" valign="top">
-<p align="center">
-<img src="assets/licheervnano.png" width="400" height="240">
-</p>
-</td>
-</tr>
-</table>
-
-注意：人手有限，中文文档可能略有滞后，请优先查看英文文档。
-
-> [!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)，我们将在功能较为收敛后进行资源占用优化.
-
-## 📢 新闻 (News)
-
-2026-02-16 🎉 PicoClaw 在一周内突破了12K star! 感谢大家的关注！PicoClaw 的成长速度超乎我们预期. 由于PR数量的快速膨胀，我们亟需社区开发者参与维护. 我们需要的志愿者角色和roadmap已经发布到了[这里](docs/ROADMAP.md), 期待你的参与！
-
-2026-02-13 🎉 **PicoClaw 在 4 天内突破 5000 Stars！** 感谢社区的支持！由于正值中国春节假期，PR 和 Issue 涌入较多，我们正在利用这段时间敲定 **项目路线图 (Roadmap)** 并组建 **开发者群组**，以便加速 PicoClaw 的开发。
-🚀 **行动号召：** 请在 GitHub Discussions 中提交您的功能请求 (Feature Requests)。我们将在接下来的周会上进行审查和优先级排序。
-
-2026-02-09 🎉 **PicoClaw 正式发布！** 仅用 1 天构建，旨在将 AI Agent 带入 10 美元硬件与 <10MB 内存的世界。🦐 PicoClaw（皮皮虾），我们走！
-
-## ✨ 特性
-
-🪶 **超轻量级**: 核心功能内存占用 <10MB — 比 Clawdbot 小 99%。
-
-💰 **极低成本**: 高效到足以在 10 美元的硬件上运行 — 比 Mac mini 便宜 98%。
-
-⚡️ **闪电启动**: 启动速度快 400 倍，即使在 0.6GHz 单核处理器上也能在 1 秒内启动。
-
-🌍 **真正可移植**: 跨 RISC-V、ARM、MIPS 和 x86 架构的单二进制文件，一键运行！
-
-🤖 **AI 自举**: 纯 Go 语言原生实现 — 95% 的核心代码由 Agent 生成，并经由“人机回环 (Human-in-the-loop)”微调。
-
-|                                | OpenClaw      | NanoBot                  | **PicoClaw**                           |
-| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
-| **语言**                       | TypeScript    | Python                   | **Go**                                 |
-| **RAM**                        | >1GB          | >100MB                   | **< 10MB**                             |
-| **启动时间**</br>(0.8GHz core) | >500s         | >30s                     | **<1s**                                |
-| **成本**                       | Mac Mini $599 | 大多数 Linux 开发板 ~$50 | **任意 Linux 开发板**</br>**低至 $10** |
-
-<img src="assets/compare.jpg" alt="PicoClaw" width="512">
-
-## 🦾 演示
-
-### 🛠️ 标准助手工作流
-
-<table align="center">
-<tr align="center">
-<th><p align="center">🧩 全栈工程师模式</p></th>
-<th><p align="center">🗂️ 日志与规划管理</p></th>
-<th><p align="center">🔎 网络搜索与学习</p></th>
-</tr>
-<tr>
-<td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
-<td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
-<td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
-</tr>
-<tr>
-<td align="center">开发 • 部署 • 扩展</td>
-<td align="center">日程 • 自动化 • 记忆</td>
-<td align="center">发现 • 洞察 • 趋势</td>
-</tr>
-</table>
-
-### 📱 在手机上轻松运行
-
-picoclaw 可以将你10年前的老旧手机废物利用，变身成为你的AI助理！快速指南:
-
-1. 先去应用商店下载安装Termux
-2. 打开后执行指令
-
-```bash
-# 注意: 下面的v0.1.1 可以换为你实际看到的最新版本
-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即可使用！
-<img src="assets/termux.jpg" alt="PicoClaw" width="512">
-
-### 🐜 创新的低占用部署
-
-PicoClaw 几乎可以部署在任何 Linux 设备上！
-
- $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)，用于智能监控。
-
-[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)
-
-🌟 更多部署案例敬请期待！
-
-## 📦 安装
-
-### 使用预编译二进制文件安装
-
-从 [Release 页面](https://github.com/sipeed/picoclaw/releases) 下载适用于您平台的固件。
-
-### 从源码安装（获取最新特性，开发推荐）
-
-```bash
-git clone https://github.com/sipeed/picoclaw.git
-
-cd picoclaw
-make deps
-
-# 构建（无需安装）
-make build
-
-# 为多平台构建
-make build-all
-
-# 构建并安装
-make install
-
-```
-
-## 🐳 Docker Compose
-
-您也可以使用 Docker Compose 运行 PicoClaw，无需在本地安装任何环境。
-
-```bash
-# 1. 克隆仓库
-git clone https://github.com/sipeed/picoclaw.git
-cd picoclaw
-
-# 2. 首次运行 — 自动生成 docker/data/config.json 后退出
-docker compose -f docker/docker-compose.yml --profile gateway up
-# 容器打印 "First-run setup complete." 后自动停止
-
-# 3. 填写 API Key 等配置
-vim docker/data/config.json   # 设置 provider API key、Bot Token 等
-
-# 4. 正式启动
-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`。
-
-```bash
-# 5. 查看日志
-docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
-
-# 6. 停止
-docker compose -f docker/docker-compose.yml --profile gateway down
-```
-
-### Agent 模式 (一次性运行)
-
-```bash
-# 提问
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 等于几？"
-
-# 交互模式
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
-```
-
-### 更新镜像
-
-```bash
-docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
-```
-
-### 🚀 快速开始
-
-> [!TIP]
-> 在 `~/.picoclaw/config.json` 中设置您的 API Key。获取 API Key: [火山引擎 (CodingPlan)](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) (LLM) · [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 次免费查询)。
-
-**1. 初始化 (Initialize)**
-
-```bash
-picoclaw onboard
-
-```
-
-**2. 配置 (Configure)** (`~/.picoclaw/config.json`)
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "model_name": "gpt-5.4",
-      "max_tokens": 8192,
-      "temperature": 0.7,
-      "max_tool_iterations": 20
-    }
-  },
-  "model_list": [
-    {
-      "model_name": "ark-code-latest",
-      "model": "volcengine/ark-code-latest",
-      "api_key": "sk-your-api-key"
-    },
-    {
-      "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
-      "api_key": "your-api-key",
-      "request_timeout": 300
-    },
-    {
-      "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
-      "api_key": "your-anthropic-key"
-    }
-  ],
-  "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "YOUR_BRAVE_API_KEY",
-        "max_results": 5
-      },
-      "tavily": {
-        "enabled": false,
-        "api_key": "YOUR_TAVILY_API_KEY",
-        "max_results": 5
-      }
-    },
-    "cron": {
-      "exec_timeout_minutes": 5
-    }
-  }
-}
-```
-
-> **新功能**: `model_list` 配置格式支持零代码添加 provider。详见[模型配置](#模型配置-model_list)章节。
-> `request_timeout` 为可选项，单位为秒。若省略或设置为 `<= 0`，PicoClaw 使用默认超时（120 秒）。
-
-**3. 获取 API Key**
-
-* **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 请求/月)
-
-> **注意**: 完整的配置模板请参考 `config.example.json`。
-
-**4. 对话 (Chat)**
-
-```bash
-picoclaw agent -m "2+2 等于几？"
-
-```
-
-就是这样！您在 2 分钟内就拥有了一个可工作的 AI 助手。
-
---
-
-## 💬 聊天应用集成 (Chat Apps)
-
-PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方。
-
-> **注意**: 所有 Webhook 类渠道（LINE、WeCom 等）均挂载在同一个 Gateway HTTP 服务器上（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`），无需为每个渠道单独配置端口。
-
-### 核心渠道
-
-| 渠道                 | 设置难度    | 特性说明                                  | 文档链接                                                                                                        |
-| -------------------- | ----------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| **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)                                                                    |
-| **Matrix**           | ⭐⭐ 中等   | 联邦协议，支持自建 homeserver 与公开服务器 | [查看文档](docs/channels/matrix/README.zh.md)                                                                  |
-| **QQ**               | ⭐⭐ 中等   | 官方机器人 API，适合国内社群              | [查看文档](docs/channels/qq/README.zh.md)                                                                       |
-| **钉钉 (DingTalk)**  | ⭐⭐ 中等   | Stream 模式无需公网，企业办公首选         | [查看文档](docs/channels/dingtalk/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 命令注册（启动时自动同步）
-
-PicoClaw 现在使用统一的命令定义来源。启动时会自动将 Telegram 支持的命令（例如 `/start`、`/help`、`/show`、`/list`）注册到 Bot 命令菜单，确保菜单展示与实际行为一致。
-Telegram 侧保留的是命令菜单注册能力；通用命令的实际执行统一走 Agent Loop 中的 commands executor。
-
-如果注册因网络或 API 短暂异常失败，不会阻塞 channel 启动；系统会在后台自动重试。
-
-## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> 加入 Agent 社交网络
-
-只需通过 CLI 或任何集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。
-
-\*\*阅读 `https://clawdchat.ai/skill.md` 并按照说明加入 [ClawdChat.ai](https://clawdchat.ai)
-
-## ⚙️ 配置详解
-
-配置文件路径: `~/.picoclaw/config.json`
-
-### 环境变量
-
-你可以使用环境变量覆盖默认路径。这对于便携安装、容器化部署或将 picoclaw 作为系统服务运行非常有用。这些变量是独立的，控制不同的路径。
-
-| 变量              | 描述                                                                                                                             | 默认路径                  |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
-| `PICOCLAW_CONFIG` | 覆盖配置文件的路径。这直接告诉 picoclaw 加载哪个 `config.json`，忽略所有其他位置。 | `~/.picoclaw/config.json` |
-| `PICOCLAW_HOME`   | 覆盖 picoclaw 数据根目录。这会更改 `workspace` 和其他数据目录的默认位置。          | `~/.picoclaw`             |
-
-**示例：**
-
-```bash
-# 使用特定的配置文件运行 picoclaw
-# 工作区路径将从该配置文件中读取
-PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
-
-# 在 /opt/picoclaw 中存储所有数据运行 picoclaw
-# 配置将从默认的 ~/.picoclaw/config.json 加载
-# 工作区将在 /opt/picoclaw/workspace 创建
-PICOCLAW_HOME=/opt/picoclaw picoclaw agent
-
-# 同时使用两者进行完全自定义设置
-PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
-```
-
-### 工作区布局 (Workspace Layout)
-
-PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/workspace`）：
-
-```
-~/.picoclaw/workspace/
-├── sessions/          # 对话会话和历史
-├── memory/           # 长期记忆 (MEMORY.md)
-├── state/            # 持久化状态 (最后一次频道等)
-├── cron/             # 定时任务数据库
-├── skills/           # 自定义技能
-├── AGENTS.md         # Agent 行为指南
-├── HEARTBEAT.md      # 周期性任务提示词 (每 30 分钟检查一次)
-├── IDENTITY.md       # Agent 身份设定
-├── SOUL.md           # Agent 灵魂/性格
-└── USER.md           # 用户偏好
-
-```
-
-### 技能来源 (Skill Sources)
-
-默认情况下，技能会按以下顺序加载：
-
-1. `~/.picoclaw/workspace/skills`（工作区）
-2. `~/.picoclaw/skills`（全局）
-3. `<current-working-directory>/skills`（内置）
-
-在高级/测试场景下，可通过以下环境变量覆盖内置技能目录：
-
-```bash
-export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
-```
-
-### 统一命令执行策略
-
- 通用斜杠命令通过 `pkg/agent/loop.go` 中的 `commands.Executor` 统一执行。
- Channel 适配器不再在本地消费通用命令；它们只负责把入站文本转发到 bus/agent 路径。Telegram 仍会在启动时自动注册其支持的命令菜单。
- 未注册的斜杠命令（例如 `/foo`）会透传给 LLM 按普通输入处理。
- 已注册但当前 channel 不支持的命令（例如 WhatsApp 上的 `/show`）会返回明确的用户可见错误，并停止后续处理。
-### 心跳 / 周期性任务 (Heartbeat)
-
-PicoClaw 可以自动执行周期性任务。在工作区创建 `HEARTBEAT.md` 文件：
-
-```markdown
-# Periodic Tasks
-
- Check my email for important messages
- Review my calendar for upcoming events
- Check the weather forecast
-```
-
-Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具执行任务。
-
-#### 使用 Spawn 的异步任务
-
-对于耗时较长的任务（网络搜索、API 调用），使用 `spawn` 工具创建一个 **子 Agent (subagent)**：
-
-```markdown
-# Periodic Tasks
-
-## Quick Tasks (respond directly)
-
- Report current time
-
-## Long Tasks (use spawn for async)
-
- Search the web for AI news and summarize
- Check email and report important messages
-```
-
-**关键行为：**
-
-| 特性             | 描述                                     |
-| ---------------- | ---------------------------------------- |
-| **spawn**        | 创建异步子 Agent，不阻塞主心跳进程       |
-| **独立上下文**   | 子 Agent 拥有独立上下文，无会话历史      |
-| **message tool** | 子 Agent 通过 message 工具直接与用户通信 |
-| **非阻塞**       | spawn 后，心跳继续处理下一个任务         |
-
-#### 子 Agent 通信原理
-
-```
-心跳触发 (Heartbeat triggers)
-    ↓
-Agent 读取 HEARTBEAT.md
-    ↓
-对于长任务: spawn 子 Agent
-    ↓                           ↓
-继续下一个任务               子 Agent 独立工作
-    ↓                           ↓
-所有任务完成                 子 Agent 使用 "message" 工具
-    ↓                           ↓
-响应 HEARTBEAT_OK            用户直接收到结果
-
-```
-
-子 Agent 可以访问工具（message, web_search 等），并且无需通过主 Agent 即可独立与用户通信。
-
-**配置：**
-
-```json
-{
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
-  }
-}
-```
-
-| 选项       | 默认值 | 描述                         |
-| ---------- | ------ | ---------------------------- |
-| `enabled`  | `true` | 启用/禁用心跳                |
-| `interval` | `30`   | 检查间隔，单位分钟 (最小: 5) |
-
-**环境变量:**
-
- `PICOCLAW_HEARTBEAT_ENABLED=false` 禁用
- `PICOCLAW_HEARTBEAT_INTERVAL=60` 更改间隔
-
-### 提供商 (Providers)
-
-> [!NOTE]
-> Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，任意渠道的音频消息都将在 Agent 层面自动转录为文字。
-
-| 提供商               | 用途                         | 获取 API Key                                                         |
-| -------------------- | ---------------------------- | -------------------------------------------------------------------- |
-| `gemini`             | LLM (Gemini 直连)            | [aistudio.google.com](https://aistudio.google.com)                   |
-| `zhipu`              | LLM (智谱直连)               | [bigmodel.cn](bigmodel.cn)                                           |
-| `volcengine` | LLM (火山引擎直连)                  | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw)                 |
-| `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)                                   |
-
-### 模型配置 (model_list)
-
-> **新功能！** PicoClaw 现在采用**以模型为中心**的配置方式。只需使用 `厂商/模型` 格式（如 `zhipu/glm-4.7`）即可添加新的 provider——**无需修改任何代码！**
-
-该设计同时支持**多 Agent 场景**，提供灵活的 Provider 选择：
-
- **不同 Agent 使用不同 Provider**：每个 Agent 可以使用自己的 LLM provider
- **模型回退（Fallback）**：配置主模型和备用模型，提高可靠性
- **负载均衡**：在多个 API 端点之间分配请求
- **集中化配置**：在一个地方管理所有 provider
-
-#### 📋 所有支持的厂商
-
-| 厂商                | `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)                                   |
-| **火山引擎（Doubao）**        | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [获取密钥](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw)                        |
-| **神算云**          | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                 |
-| **BytePlus**        | `byteplus/`       | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [获取密钥](https://www.byteplus.com)                        |
-| **LongCat**         | `longcat/`        | `https://api.longcat.chat/openai`                   | OpenAI    | [获取密钥](https://longcat.chat/platform)                        |
-| **Antigravity**     | `antigravity/`    | Google Cloud                                        | 自定义    | 仅 OAuth                                                          |
-| **GitHub Copilot**  | `github-copilot/` | `localhost:4321`                                    | gRPC      | -                                                                 |
-
-#### 基础配置示例
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "ark-code-latest",
-      "model": "volcengine/ark-code-latest",
-      "api_key": "sk-your-api-key"
-    },
-    {
-      "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
-      "api_key": "sk-your-openai-key"
-    },
-    {
-      "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
-      "api_key": "sk-ant-your-key"
-    },
-    {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-zhipu-key"
-    }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "gpt-5.4"
-    }
-  }
-}
-```
-
-#### 各厂商配置示例
-
-**OpenAI**
-
-```json
-{
-  "model_name": "gpt-5.4",
-  "model": "openai/gpt-5.4",
-  "api_key": "sk-..."
-}
-```
-
-**火山引擎（Doubao）**
-
-```json
-{
-  "model_name": "ark-code-latest",
-  "model": "volcengine/ark-code-latest",
-  "api_key": "sk-..."
-}
-```
-
-**智谱 AI (GLM)**
-
-```json
-{
-  "model_name": "glm-4.7",
-  "model": "zhipu/glm-4.7",
-  "api_key": "your-key"
-}
-```
-
-**DeepSeek**
-
-```json
-{
-  "model_name": "deepseek-chat",
-  "model": "deepseek/deepseek-chat",
-  "api_key": "sk-..."
-}
-```
-
-**Anthropic (使用 OAuth)**
-
-```json
-{
-  "model_name": "claude-sonnet-4.6",
-  "model": "anthropic/claude-sonnet-4.6",
-  "auth_method": "oauth"
-}
-```
-
-> 运行 `picoclaw auth login --provider anthropic` 来设置 OAuth 凭证。
-
-**Ollama (本地)**
-
-```json
-{
-  "model_name": "llama3",
-  "model": "ollama/llama3"
-}
-```
-
-**自定义代理/API**
-
-```json
-{
-  "model_name": "my-custom-model",
-  "model": "openai/custom-model",
-  "api_base": "https://my-proxy.com/v1",
-  "api_key": "sk-...",
-  "request_timeout": 300
-}
-```
-
-#### 负载均衡
-
-为同一个模型名称配置多个端点——PicoClaw 会自动在它们之间轮询：
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
-      "api_base": "https://api1.example.com/v1",
-      "api_key": "sk-key1"
-    },
-    {
-      "model_name": "gpt-5.4",
-      "model": "openai/gpt-5.4",
-      "api_base": "https://api2.example.com/v1",
-      "api_key": "sk-key2"
-    }
-  ]
-}
-```
-
-#### 从旧的 `providers` 配置迁移
-
-旧的 `providers` 配置格式**已弃用**，但为向后兼容仍支持。
-
-**旧配置（已弃用）：**
-
-```json
-{
-  "providers": {
-    "zhipu": {
-      "api_key": "your-key",
-      "api_base": "https://open.bigmodel.cn/api/paas/v4"
-    }
-  },
-  "agents": {
-    "defaults": {
-      "provider": "zhipu",
-      "model": "glm-4.7"
-    }
-  }
-}
-```
-
-**新配置（推荐）：**
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-key"
-    }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "glm-4.7"
-    }
-  }
-}
-```
-
-详细的迁移指南请参考 [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md)。
-
-<details>
-<summary><b>智谱 (Zhipu) 配置示例</b></summary>
-
-**1. 获取 API key 和 base URL**
-
- 获取 [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
-
-**2. 配置**
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "model": "glm-4.7",
-      "max_tokens": 8192,
-      "temperature": 0.7,
-      "max_tool_iterations": 20
-    }
-  },
-  "providers": {
-    "zhipu": {
-      "api_key": "Your API Key",
-      "api_base": "https://open.bigmodel.cn/api/paas/v4"
-    }
-  }
-}
-```
-
-**3. 运行**
-
-```bash
-picoclaw agent -m "你好"
-
-```
-
-</details>
-
-<details>
-<summary><b>完整配置示例</b></summary>
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "model": "anthropic/claude-opus-4-5"
-    }
-  },
-  "session": {
-    "dm_scope": "per-channel-peer",
-    "backlog_limit": 20
-  },
-  "providers": {
-    "openrouter": {
-      "api_key": "sk-or-v1-xxx"
-    },
-    "groq": {
-      "api_key": "gsk_xxx"
-    }
-  },
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "123456:ABC...",
-      "allow_from": ["123456789"]
-    },
-    "discord": {
-      "enabled": true,
-      "token": "",
-      "allow_from": [""]
-    },
-    "whatsapp": {
-      "enabled": false
-    },
-    "qq": {
-      "enabled": false,
-      "app_id": "",
-      "app_secret": "",
-      "allow_from": []
-    }
-  },
-  "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "YOUR_BRAVE_API_KEY",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
-      }
-    },
-    "cron": {
-      "exec_timeout_minutes": 5
-    }
-  },
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
-  }
-}
-```
-
-</details>
-
-## CLI 命令行参考
-
-| 命令                      | 描述               |
-| ------------------------- | ------------------ |
-| `picoclaw onboard`        | 初始化配置和工作区 |
-| `picoclaw agent -m "..."` | 与 Agent 对话      |
-| `picoclaw agent`          | 交互式聊天模式     |
-| `picoclaw gateway`        | 启动网关 (Gateway) |
-| `picoclaw status`         | 显示状态           |
-| `picoclaw cron list`      | 列出所有定时任务   |
-| `picoclaw cron add ...`   | 添加定时任务       |
-
-### 定时任务 / 提醒 (Scheduled Tasks)
-
-PicoClaw 通过 `cron` 工具支持定时提醒和重复任务：
-
- **一次性提醒**: "Remind me in 10 minutes" (10分钟后提醒我) → 10分钟后触发一次
- **重复任务**: "Remind me every 2 hours" (每2小时提醒我) → 每2小时触发
- **Cron 表达式**: "Remind me at 9am daily" (每天上午9点提醒我) → 使用 cron 表达式
-
-任务存储在 `~/.picoclaw/workspace/cron/` 中并自动处理。
-
-## 🤝 贡献与路线图 (Roadmap)
-
-欢迎提交 PR！代码库刻意保持小巧和可读。🤗
-
-路线图即将发布...
-
-开发者群组正在组建中，入群门槛：至少合并过 1 个 PR。
-
-用户群组：
-
-Discord: [https://discord.gg/V4sAZ9XWpN](https://discord.gg/V4sAZ9XWpN)
-
-<img src="assets/wechat.png" alt="PicoClaw" width="512">
-
-## 🐛 疑难解答 (Troubleshooting)
-
-### 网络搜索提示 "API 配置问题"
-
-如果您尚未配置搜索 API Key，这是正常的。PicoClaw 会提供手动搜索的帮助链接。
-
-启用网络搜索：
-
-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`:
-
-```json
-{
-  "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "YOUR_BRAVE_API_KEY",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
-      }
-    }
-  }
-}
-```
-
-### 遇到内容过滤错误 (Content Filtering Errors)
-
-某些提供商（如智谱）有严格的内容过滤。尝试改写您的问题或使用其他模型。
-
-### Telegram bot 提示 "Conflict: terminated by other getUpdates"
-
-这表示有另一个机器人实例正在运行。请确保同一时间只有一个 `picoclaw gateway` 进程在运行。
-
---
-
-## 📝 API Key 对比
-
-| 服务 | 免费层级 | 适用场景 |
-| --- | --- | --- |
-| **OpenRouter** | 200K tokens/月 | 多模型聚合 (Claude, GPT-4 等) |
-| **火山引擎 CodingPlan** | 9.9 元/首月 | 最适合国内用户，多种 SOTA 模型（豆包、DeepSeek 等） |
-| **智谱 (Zhipu)** | 200K tokens/月 | 适合中国用户 |
-| **Brave Search** | 2000 次查询/月 | 网络搜索功能 |
-| **Tavily** | 1000 次查询/月 | AI Agent 搜索优化 |
-| **Groq** | 提供免费层级 | 极速推理 (Llama, Mixtral) |
-| **LongCat** | 最多 5M tokens/天 | 推理速度快 (免费额度) |
-
---
-
-<div align="center">
-  <img src="assets/logo.jpg" alt="PicoClaw Meme" width="512">
-</div>
--- a/docs/channels/dingtalk/README.md
+++ b/docs/channels/dingtalk/README.md
@ -0,0 +1,33 @@
+# DingTalk
+
+DingTalk is an enterprise communication platform by Alibaba, widely popular in Chinese workplaces. It uses a streaming SDK to maintain persistent connections.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field         | Type   | Required | Description                               |
+| ------------- | ------ | -------- | ----------------------------------------- |
+| enabled       | bool   | Yes      | Whether to enable the DingTalk channel    |
+| client_id     | string | Yes      | Client ID of the DingTalk application     |
+| client_secret | string | Yes      | Client Secret of the DingTalk application |
+| allow_from    | array  | No       | User ID allowlist, empty means allow all  |
+
+## Setup Process
+
+1. Go to the [DingTalk Open Platform](https://open.dingtalk.com/)
+2. Create an internal enterprise application
+3. Obtain the Client ID and Client Secret from the application settings
+4. Configure OAuth and event subscriptions (if needed)
+5. Fill in the Client ID and Client Secret in the configuration file
--- a/docs/channels/dingtalk/README.zh.md
+++ b/docs/channels/dingtalk/README.zh.md
@ -1,33 +0,0 @@
-# 钉钉
-
-钉钉是阿里巴巴的企业通讯平台，在中国职场中广受欢迎。它采用流式 SDK 来维持持久连接。
-
-## 配置
-
-```json
-{
-  "channels": {
-    "dingtalk": {
-      "enabled": true,
-      "client_id": "YOUR_CLIENT_ID",
-      "client_secret": "YOUR_CLIENT_SECRET",
-      "allow_from": []
-    }
-  }
-}
-```
-
-| 字段          | 类型   | 必填 | 描述                             |
-| ------------- | ------ | ---- | -------------------------------- |
-| enabled       | bool   | 是   | 是否启用钉钉频道                 |
-| client_id     | string | 是   | 钉钉应用的 Client ID             |
-| client_secret | string | 是   | 钉钉应用的 Client Secret         |
-| allow_from    | array  | 否   | 用户ID白名单，空表示允许所有用户 |
-
-## 设置流程
-
-1. 前往 [钉钉开放平台](https://open.dingtalk.com/)
-2. 创建一个企业内部应用
-3. 从应用设置中获取 Client ID 和 Client Secret
-4. 配置OAuth和事件订阅(如需要)
-5. 将 Client ID 和 Client Secret 填入配置文件中
--- a/docs/channels/discord/README.md
+++ b/docs/channels/discord/README.md
@ -0,0 +1,37 @@
+# Discord
+
+Discord is a free voice, video, and text chat application designed for communities. PicoClaw connects to Discord servers via the Discord Bot API, supporting both receiving and sending messages.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"],
+      "group_trigger": {
+        "mention_only": false
+      }
+    }
+  }
+}
+```
+
+| Field         | Type   | Required | Description                                     |
+| ------------- | ------ | -------- | ----------------------------------------------- |
+| enabled       | bool   | Yes      | Whether to enable the Discord channel           |
+| token         | string | Yes      | Discord Bot Token                               |
+| allow_from    | array  | No       | User ID allowlist, empty means allow all        |
+| group_trigger | object | No       | Group trigger settings (e.g., { "mention_only": false }) |
+
+## Setup Process
+
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and create a new application.
+2. Enable Intents:
+   - Message Content Intent
+   - Server Members Intent
+3. Obtain the Bot Token.
+4. Fill in the Bot Token in the configuration file.
+5. Invite the bot to your server and grant necessary permissions (e.g., Send Messages, Read Message History).
--- a/docs/channels/discord/README.zh.md
+++ b/docs/channels/discord/README.zh.md
@ -1,37 +0,0 @@
-# Discord
-
-Discord 是一个专为社区设计的免费语音、视频和文本聊天应用。PicoClaw 通过 Discord Bot API 连接到 Discord 服务器，支持接收和发送消息。
-
-## 配置
-
-```json
-{
-  "channels": {
-    "discord": {
-      "enabled": true,
-      "token": "YOUR_BOT_TOKEN",
-      "allow_from": ["YOUR_USER_ID"],
-      "group_trigger": {
-        "mention_only": false
-      }
-    }
-  }
-}
-```
-
-| 字段         | 类型   | 必填 | 描述                             |
-| ------------ | ------ | ---- | -------------------------------- |
-| enabled      | bool   | 是   | 是否启用 Discord 频道            |
-| token        | string | 是   | Discord 机器人 Token             |
-| allow_from   | array  | 否   | 用户ID白名单，空表示允许所有用户 |
-| group_trigger | object | 否   | 群组触发设置（示例: { "mention_only": false }） |
-
-## 设置流程
-
-1. 前往 [Discord 开发者门户](https://discord.com/developers/applications) 创建一个新的应用
-2. 启用 Intents:
-   - Message Content Intent
-   - Server Members Intent
-3. 获取 Bot Token
-4. 将 Bot Token 填入配置文件中
-5. 邀请机器人加入服务器并授予必要权限(例如发送消息、读取消息历史等)
--- a/docs/channels/line/README.md
+++ b/docs/channels/line/README.md
@ -0,0 +1,38 @@
+# LINE
+
+PicoClaw supports LINE through the LINE Messaging API and Webhook callbacks.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field                | Type   | Required | Description                                |
+| -------------------- | ------ | -------- | ------------------------------------------ |
+| enabled              | bool   | Yes      | Whether to enable the LINE channel         |
+| channel_secret       | string | Yes      | Channel Secret for LINE Messaging API      |
+| channel_access_token | string | Yes      | Channel Access Token for LINE Messaging API|
+| webhook_path         | string | No       | Webhook path (default: /webhook/line)      |
+| allow_from           | array  | No       | User ID allowlist, empty means allow all   |
+
+## Setup Process
+
+1. Go to the [LINE Developers Console](https://developers.line.biz/console/) and create a provider and a Messaging API Channel.
+2. Obtain the Channel Secret and Channel Access Token.
+3. Configure Webhook:
+   - LINE requires Webhooks to use the HTTPS protocol. You will need to deploy an HTTPS-enabled server or use a reverse proxy tool like ngrok to expose your local server to the public internet.
+   - PicoClaw now uses a shared Gateway HTTP server to receive webhook callbacks for all channels, listening by default at 127.0.0.1:18790.
+   - Set the Webhook URL to `https://your-domain.com/webhook/line`, and then reverse proxy your external domain to the local Gateway (default port 18790).
+   - Enable the Webhook and verify the URL.
+4. Fill in the Channel Secret and Channel Access Token in the configuration file.
--- a/docs/channels/line/README.zh.md
+++ b/docs/channels/line/README.zh.md
@ -1,38 +0,0 @@
-# Line
-
-PicoClaw 通过 LINE Messaging API 配合 Webhook 回调功能实现对 LINE 的支持。
-
-## 配置
-
-```json
-{
-  "channels": {
-    "line": {
-      "enabled": true,
-      "channel_secret": "YOUR_CHANNEL_SECRET",
-      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_path": "/webhook/line",
-      "allow_from": []
-    }
-  }
-}
-```
-
-| 字段                 | 类型   | 必填 | 描述                                       |
-| -------------------- | ------ | ---- | ------------------------------------------ |
-| enabled              | bool   | 是   | 是否启用 LINE Channel                      |
-| channel_secret       | string | 是   | LINE Messaging API 的 Channel Secret       |
-| channel_access_token | string | 是   | LINE Messaging API 的 Channel Access Token |
-| webhook_path         | string | 否   | Webhook 的路径 (默认为 /webhook/line)      |
-| allow_from           | array  | 否   | 用户ID白名单，空表示允许所有用户           |
-
-## 设置流程
-
-1. 前往 [LINE Developers Console](https://developers.line.biz/console/) 创建一个服务提供商和一个 Messaging API Channel
-2. 获取 Channel Secret 和 Channel Access Token
-3. 配置Webhook:
-   - LINE 要求 Webhook 必须使用 HTTPS 协议，因此需要部署一个支持 HTTPS 的服务器，或者使用反向代理工具如 ngrok 将本地服务器暴露到公网
-   - PicoClaw 现在使用共享的 Gateway HTTP 服务器来接收所有渠道的 webhook 回调，默认监听地址为 127.0.0.1:18790
-   - 将 Webhook URL 设置为 `https://your-domain.com/webhook/line`，然后将外部域名反向代理到本机的 Gateway（默认端口 18790）
-   - 启用 Webhook 并验证 URL
-4. 将 Channel Secret 和 Channel Access Token 填入配置文件中
--- a/docs/channels/maixcam/README.md
+++ b/docs/channels/maixcam/README.md
@ -0,0 +1,31 @@
+# MaixCam
+
+MaixCam is a channel dedicated to connecting Sipeed MaixCAM and MaixCAM2 AI camera devices. It uses TCP sockets for bidirectional communication, supporting edge AI deployment scenarios.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "maixcam": {
+      "enabled": true,
+      "server_address": "0.0.0.0:8899",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field          | Type   | Required | Description                               |
+| -------------- | ------ | -------- | ----------------------------------------- |
+| enabled        | bool   | Yes      | Whether to enable the MaixCam channel     |
+| server_address | string | Yes      | TCP server listening address and port     |
+| allow_from     | array  | No       | Device ID allowlist, empty means allow all|
+
+## Use Cases
+
+The MaixCam channel enables PicoClaw to run as an AI backend for edge devices:
+
+- **Smart Monitoring**: MaixCAM sends image frames, and PicoClaw analyzes them using vision models.
+- **IoT Control**: Devices send sensor data, and PicoClaw coordinates responses.
+- **Offline AI**: Deploy PicoClaw on a local network for low-latency inference.
--- a/docs/channels/maixcam/README.zh.md
+++ b/docs/channels/maixcam/README.zh.md
@ -1,31 +0,0 @@
-# MaixCam
-
-MaixCam 是专用于连接矽速科技 MaixCAM 与 MaixCAM2 AI 摄像设备的通道。它采用 TCP 套接字实现双向通信，支持边缘 AI 部署场景。
-
-## 配置
-
-```json
-{
-  "channels": {
-    "maixcam": {
-      "enabled": true,
-      "server_address": "0.0.0.0:8899",
-      "allow_from": []
-    }
-  }
-}
-```
-
-| 字段           | 类型   | 必填 | 描述                             |
-| -------------- | ------ | ---- | -------------------------------- |
-| enabled        | bool   | 是   | 是否启用 MaixCam 频道            |
-| server_address | string | 是   | TCP 服务器监听地址和端口         |
-| allow_from     | array  | 否   | 设备ID白名单，空表示允许所有设备 |
-
-## 使用场景
-
-MaixCam 通道使 PicoClaw 能够作为边缘设备的 AI 后端运行：
-
- **智能监控** ：MaixCAM 发送图像帧，PicoClaw 通过视觉模型进行分析
- **物联网控制** ：设备发送传感器数据，PicoClaw 协调响应
- **离线AI** ：在本地网络部署 PicoClaw 实现低延迟推理
--- a/docs/channels/matrix/README.zh.md
+++ b/docs/channels/matrix/README.zh.md
@ -1,59 +0,0 @@
-# Matrix 通道配置指南
-
-## 1. 配置示例
-
-在 `config.json` 中添加：
-
-```json
-{
-  "channels": {
-    "matrix": {
-      "enabled": true,
-      "homeserver": "https://matrix.org",
-      "user_id": "@your-bot:matrix.org",
-      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
-      "device_id": "",
-      "join_on_invite": true,
-      "allow_from": [],
-      "group_trigger": {
-        "mention_only": true
-      },
-      "placeholder": {
-        "enabled": true,
-        "text": "Thinking... 💭"
-      },
-      "reasoning_channel_id": ""
-    }
-  }
-}
-```
-
-## 2. 参数说明
-
-| 字段                 | 类型     | 必填 | 说明 |
-|----------------------|----------|------|------|
-| enabled              | bool     | 是   | 是否启用 Matrix 通道 |
-| homeserver           | string   | 是   | Matrix 服务器地址（例如 `https://matrix.org`） |
-| user_id              | string   | 是   | 机器人 Matrix 用户 ID（例如 `@bot:matrix.org`） |
-| access_token         | string   | 是   | 机器人 access token |
-| device_id            | string   | 否   | 设备 ID（可选） |
-| join_on_invite       | bool     | 否   | 是否自动加入邀请房间 |
-| allow_from           | []string | 否   | 白名单用户（Matrix 用户 ID） |
-| group_trigger        | object   | 否   | 群聊触发策略（支持 `mention_only` / `prefixes`） |
-| placeholder          | object   | 否   | 占位消息配置 |
-| reasoning_channel_id | string   | 否   | 思维链输出目标通道 |
-
-## 3. 当前支持
-
- 文本消息收发
- 图片/音频/视频/文件消息入站下载（写入 MediaStore / 本地路径回退）
- 音频消息按统一标记进入现有转写流程（`[audio: ...]`）
- 图片/音频/视频/文件消息出站发送（上传到 Matrix 媒体库后发送）
- 群聊触发规则（支持仅 @ 提及时响应）
- Typing 状态（`m.typing`）
- 占位消息（`Thinking... 💭`）+ 最终回复替换
- 自动加入邀请房间（可关闭）
-
-## 4. TODO
-
- 富媒体细节增强（如 image/video 的尺寸、缩略图等 metadata）
--- a/docs/channels/onebot/README.md
+++ b/docs/channels/onebot/README.md
@ -0,0 +1,31 @@
+# OneBot
+
+OneBot is an open protocol standard for QQ bots, providing a unified interface for various QQ bot implementations (e.g., go-cqhttp, Mirai). It uses WebSockets for communication.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "enabled": true,
+      "ws_url": "ws://localhost:8080",
+      "access_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field        | Type   | Required | Description                               |
+| ------------ | ------ | -------- | ----------------------------------------- |
+| enabled      | bool   | Yes      | Whether to enable the OneBot channel      |
+| ws_url       | string | Yes      | WebSocket URL of the OneBot server        |
+| access_token | string | No       | Access token for the OneBot server        |
+| allow_from   | array  | No       | User ID allowlist, empty means allow all  |
+
+## Setup Process
+
+1. Deploy a OneBot-compatible implementation (e.g., NapCat).
+2. Configure the OneBot implementation to enable WebSocket services and set an access token (if required).
+3. Fill in the WebSocket URL and access token in the configuration file.
--- a/docs/channels/onebot/README.zh.md
+++ b/docs/channels/onebot/README.zh.md
@ -1,31 +0,0 @@
-# OneBot
-
-OneBot 是一个面向 QQ 机器人的开放协议标准，为多种 QQ 机器人实现（例如 go-cqhttp、Mirai）提供了统一的接口。它使用 WebSocket 进行通信。
-
-## 配置
-
-```json
-{
-  "channels": {
-    "onebot": {
-      "enabled": true,
-      "ws_url": "ws://localhost:8080",
-      "access_token": "",
-      "allow_from": []
-    }
-  }
-}
-```
-
-| 字段         | 类型   | 必填 | 描述                             |
-| ------------ | ------ | ---- | -------------------------------- |
-| enabled      | bool   | 是   | 是否启用 OneBot 频道             |
-| ws_url       | string | 是   | OneBot 服务器的 WebSocket URL    |
-| access_token | string | 否   | 连接 OneBot 服务器的访问令牌     |
-| allow_from   | array  | 否   | 用户ID白名单，空表示允许所有用户 |
-
-## 设置流程
-
-1. 部署一个 OneBot 兼容的实现(例如napcat)
-2. 配置 OneBot 实现以启用 WebSocket 服务并设置访问令牌(如果需要)
-3. 将 WebSocket URL 和访问令牌填入配置文件中
--- a/docs/channels/qq/README.md
+++ b/docs/channels/qq/README.md
@ -0,0 +1,32 @@
+# QQ
+
+PicoClaw supports QQ via the official bot API of the QQ Open Platform.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field      | Type   | Required | Description                              |
+| ---------- | ------ | -------- | ---------------------------------------- |
+| enabled    | bool   | Yes      | Whether to enable the QQ channel         |
+| app_id     | string | Yes      | App ID of the QQ bot application         |
+| app_secret | string | Yes      | App Secret of the QQ bot application     |
+| allow_from | array  | No       | User ID allowlist, empty means allow all |
+
+## Setup Process
+
+1. Go to the [QQ Open Platform](https://q.qq.com/) and create a bot.
+2. Obtain the App ID and App Secret from the dashboard.
+3. Enable bot sandbox mode and add users and groups to the sandbox.
+4. Fill in the App ID and App Secret in the configuration file.
--- a/docs/channels/qq/README.zh.md
+++ b/docs/channels/qq/README.zh.md
@ -1,32 +0,0 @@
-# QQ
-
-PicoClaw 通过 QQ 开放平台的官方机器人 API 提供对 QQ 的支持。
-
-## 配置
-
-```json
-{
-  "channels": {
-    "qq": {
-      "enabled": true,
-      "app_id": "YOUR_APP_ID",
-      "app_secret": "YOUR_APP_SECRET",
-      "allow_from": []
-    }
-  }
-}
-```
-
-| 字段       | 类型   | 必填 | 描述                             |
-| ---------- | ------ | ---- | -------------------------------- |
-| enabled    | bool   | 是   | 是否启用 QQ Channel              |
-| app_id     | string | 是   | QQ 机器人应用的 App ID           |
-| app_secret | string | 是   | QQ 机器人应用的 App Secret       |
-| allow_from | array  | 否   | 用户ID白名单，空表示允许所有用户 |
-
-## 设置流程
-
-1. 前往 [QQ 开放平台](https://q.qq.com/) 创建一个机器人
-2. 通过仪表盘获取 App ID 和 App Secret
-3. 开启机器人沙箱模式, 将用户和群添加到沙箱中
-4. 将 App ID 和 App Secret 填入配置文件中
--- a/docs/channels/slack/README.md
+++ b/docs/channels/slack/README.md
@ -0,0 +1,33 @@
+# Slack
+
+Slack is a leading enterprise-grade instant messaging platform. PicoClaw uses Slack's Socket Mode for real-time bidirectional communication, eliminating the need to configure public Webhook endpoints.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "bot_token": "xoxb-...",
+      "app_token": "xapp-...",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field      | Type   | Required | Description                                               |
+| ---------- | ------ | -------- | --------------------------------------------------------- |
+| enabled    | bool   | Yes      | Whether to enable the Slack channel                       |
+| bot_token  | string | Yes      | Bot User OAuth Token for the Slack bot (starts with xoxb-)|
+| app_token  | string | Yes      | Socket Mode App Level Token for the Slack app (starts with xapp-)|
+| allow_from | array  | No       | User ID allowlist, empty means allow all                  |
+
+## Setup Process
+
+1. Go to the [Slack API](https://api.slack.com/) and create a new Slack application.
+2. Enable Socket Mode and obtain an App Level Token.
+3. Add Bot Token Scopes (e.g., `chat:write`, `im:history`, etc.).
+4. Install the application to your workspace and obtain the Bot User OAuth Token.
+5. Fill in the Bot Token and App Token in the configuration file.
--- a/docs/channels/slack/README.zh.md
+++ b/docs/channels/slack/README.zh.md
@ -1,33 +0,0 @@
-# Slack
-
-Slack 是全球领先的企业级即时通讯平台。PicoClaw 采用 Slack 的 Socket Mode 实现实时双向通信，无需配置公开的 Webhook 端点。
-
-## 配置
-
-```json
-{
-  "channels": {
-    "slack": {
-      "enabled": true,
-      "bot_token": "xoxb-...",
-      "app_token": "xapp-...",
-      "allow_from": []
-    }
-  }
-}
-```
-
-| 字段       | 类型   | 必填 | 描述                                                     |
-| ---------- | ------ | ---- | -------------------------------------------------------- |
-| enabled    | bool   | 是   | 是否启用 Slack 频道                                      |
-| bot_token  | string | 是   | Slack 机器人的 Bot User OAuth Token (以 xoxb- 开头)      |
-| app_token  | string | 是   | Slack 应用的 Socket Mode App Level Token (以 xapp- 开头) |
-| allow_from | array  | 否   | 用户ID白名单，空表示允许所有用户                         |
-
-## 设置流程
-
-1. 前往 [Slack API](https://api.slack.com/) 创建一个新的 Slack 应用
-2. 启用 Socket Mode 并获取 App Level Token
-3. 添加 Bot Token Scopes(例如`chat:write`、`im:history`等)
-4. 安装应用到工作区并获取 Bot User OAuth Token
-5. 将 Bot Token 和 App Token 填入配置文件中
--- a/docs/channels/telegram/README.md
+++ b/docs/channels/telegram/README.md
@ -0,0 +1,33 @@
+# Telegram
+
+The Telegram Channel uses the Telegram Bot API with long polling to enable bot-based communication. It supports text messages, media attachments (photos, voice, audio, documents), voice transcription via Groq Whisper, and a built-in command processor.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
+      "allow_from": ["123456789"],
+      "proxy": ""
+    }
+  }
+}
+```
+
+| Field      | Type   | Required | Description                                               |
+| ---------- | ------ | -------- | --------------------------------------------------------- |
+| enabled    | bool   | Yes      | Whether to enable the Telegram channel                    |
+| token      | string | Yes      | Telegram Bot API Token                                    |
+| allow_from | array  | No       | User ID allowlist, empty means allow all                  |
+| proxy      | string | No       | Proxy URL for connecting to Telegram API (e.g., http://127.0.0.1:7890)|
+
+## Setup Process
+
+1. Search for `@BotFather` on Telegram.
+2. Send the `/newbot` command and follow the prompts to create a new bot.
+3. Obtain the HTTP API Token.
+4. Fill in the Token in the configuration file.
+5. (Optional) Configure `allow_from` to restrict the user IDs allowed to interact (obtain IDs via `@userinfobot`).
--- a/docs/channels/telegram/README.zh.md
+++ b/docs/channels/telegram/README.zh.md
@ -1,33 +0,0 @@
-# Telegram
-
-Telegram Channel 通过 Telegram 机器人 API 使用长轮询实现基于机器人的通信。它支持文本消息、媒体附件（照片、语音、音频、文档）、通过 Groq Whisper 进行语音转录以及内置命令处理器。
-
-## 配置
-
-```json
-{
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
-      "allow_from": ["123456789"],
-      "proxy": ""
-    }
-  }
-}
-```
-
-| 字段       | 类型   | 必填 | 描述                                                      |
-| ---------- | ------ | ---- | --------------------------------------------------------- |
-| enabled    | bool   | 是   | 是否启用 Telegram 频道                                    |
-| token      | string | 是   | Telegram 机器人 API Token                                 |
-| allow_from | array  | 否   | 用户ID白名单，空表示允许所有用户                          |
-| proxy      | string | 否   | 连接 Telegram API 的代理 URL (例如 http://127.0.0.1:7890) |
-
-## 设置流程
-
-1. 在 Telegram 中搜索 `@BotFather`
-2. 发送 `/newbot` 命令并按照提示创建新机器人
-3. 获取 HTTP API Token
-4. 将 Token 填入配置文件中
-5. (可选) 配置 `allow_from` 以限制允许互动的用户 ID (可通过 `@userinfobot` 获取 ID)
--- a/docs/design/issue-783-investigation-and-fix-plan.md
+++ b/docs/design/issue-783-investigation-and-fix-plan.md
@ -0,0 +1,61 @@
+# Issue #783 Investigation and Fix Implementation Document
+
+## 1. Problem Clarification (Confirmed)
+
+- Phenomenon: When `agents.*.model.primary/fallbacks` use `model_name` aliases (e.g., `step-3.5-flash`), the fallback chain parses the alias as a real `provider/model`, resulting in a potentially empty `provider` and an incorrect `model`.
+- Root Cause: `ResolveCandidates` only performs `ParseModelRef` on strings without first mapping aliases to real `model` fields via `model_list`.
+- Impact:
+  - Fallback execution might send the alias directly to an OpenAI-compatible provider, triggering an `Unknown Model` error.
+  - When `defaults.provider` is empty, the logs show an empty `provider=` value.
+
+## 2. Objectives
+
+- Fix fallback candidate resolution: Prioritize resolving aliases through `model_list`.
+- Maintain backward compatibility: If no match is found in `model_list`, fall back to the existing `ParseModelRef` logic.
+- Add supplementary tests: Cover aliases, nested path models (e.g., `openrouter/stepfun/...`), and empty default providers.
+- Verify code style: Ensure consistency with the current repository's style (naming, error handling, test structure).
+
+## 3. Online Best Practices Research Conclusions (Completed)
+
+- [x] Researched recommended handling of the `model` field by OpenAI-compatible gateways (e.g., OpenRouter).
+- [x] Researched best practices for multi-provider/fallback design (candidate resolution, log observability).
+- [x] Mapped external recommendations to actionable constraints for this repository.
+
+External Reference Key Points (from official documentation of OpenRouter/LiteLLM/Cloudflare AI Gateway, etc.):
+
+- Prefer explicit configuration; do not rely on string splitting to infer the provider.
+- Model identifiers for gateways should retain full path semantics to avoid truncation causing "Unknown Model" errors.
+- Fallback and primary paths should share the same resolution strategy to avoid cases where the main path works but the fallback path fails.
+
+Reference Links:
+
+- OpenRouter Provider Routing: https://openrouter.ai/docs/guides/routing/provider-selection
+- OpenRouter Model Fallbacks: https://openrouter.ai/docs/guides/routing/model-fallbacks
+- OpenRouter Chat Completion API: https://openrouter.ai/docs/api-reference/chat-completion
+- LiteLLM Router Architecture: https://docs.litellm.ai/docs/router_architecture
+- Cloudflare AI Gateway Chat Completion: https://developers.cloudflare.com/ai-gateway/usage/chat-completion/
+
+Actionable Constraints for This Repository:
+
+- Map `model_name -> model_list.model` during the fallback candidate construction phase.
+- Retain legacy parsing behavior when no mapping is found to ensure compatibility.
+- Use new tests to lock down scenarios involving "aliases + nested model paths + empty default providers."
+
+## 4. Implementation Steps (Executed Sequentially)
+
+- [x] Step 1: Align with existing code patterns and locate minimal change points (`pkg/agent` + `pkg/providers`).
+- [x] Step 2: Implement "model_list-based fallback candidate resolution."
+- [x] Step 3: Add/update unit tests to cover the issue scenarios.
+- [x] Step 4: Perform code style consistency review (against existing file styles).
+- [x] Step 5: Run quality gates (LSP + `make check`).
+
+## 5. Execution Record
+
+- Status: Completed
+- Changes implemented:
+  - `pkg/providers/fallback.go`: Added `ResolveCandidatesWithLookup` while keeping `ResolveCandidates` for backward compatibility.
+  - `pkg/agent/instance.go`: Prioritized resolving aliases via `model_list` before building fallback candidates; complemented models without protocols with the default `openai/` prefix before parsing.
+  - `pkg/providers/fallback_test.go`: Added tests for alias resolution and deduplication.
+  - `pkg/agent/instance_test.go`: Added tests for agent-side alias resolution to nested model paths and models without protocols.
+- Style alignment check (Completed): Consistent with existing patterns in `pkg/providers/fallback_test.go` and `pkg/providers/model_ref_test.go`.
+- Quality verification (Completed): All checks passed after running `make generate` followed by `make check`.
--- a/docs/design/issue-783-investigation-and-fix-plan.zh.md
+++ b/docs/design/issue-783-investigation-and-fix-plan.zh.md
@ -1,61 +0,0 @@
-# Issue #783 调研与修复执行文档
-
-## 1. 问题澄清（已确认）
-
- 现象：当 `agents.*.model.primary/fallbacks` 使用 `model_name` 别名（如 `step-3.5-flash`）时，fallback 链路将别名当作真实 `provider/model` 解析，导致 `provider` 可能为空、`model` 可能错误。
- 根因：`ResolveCandidates` 仅对字符串做 `ParseModelRef`，未先通过 `model_list` 将别名映射到真实 `model` 字段。
- 影响：
-  - fallback 执行可能把别名直接发给 OpenAI-compatible provider，触发 `Unknown Model`。
-  - `defaults.provider` 为空时，日志出现 `provider=` 空值。
-
-## 2. 本次目标
-
- 修复 fallback 候选解析：优先通过 `model_list` 解析别名。
- 兼容旧行为：若未命中 `model_list`，继续走原有 `ParseModelRef` 兜底。
- 补充测试：覆盖别名、嵌套路径模型（如 `openrouter/stepfun/...`）、空默认 provider。
- 验证代码风格：与当前仓库风格保持一致（命名、错误处理、测试结构）。
-
-## 3. 联网最佳实践调研结论（已完成）
-
- [x] 查阅 OpenAI-compatible 网关（如 OpenRouter）对 `model` 字段的推荐处理。
- [x] 查阅多 provider/fallback 设计最佳实践（候选解析、日志可观测性）。
- [x] 将外部建议映射为本仓库可执行约束。
-
-外部参考要点（来自 OpenRouter/LiteLLM/Cloudflare AI Gateway 等官方文档）：
-
- 优先显式配置，不依赖字符串切分推断 provider。
- 对网关模型标识应保留完整路径语义，避免截断导致 Unknown Model。
- fallback 与 primary 应复用同一解析策略，避免“主路径正确、降级路径错误”。
-
-参考链接：
-
- OpenRouter Provider Routing: https://openrouter.ai/docs/guides/routing/provider-selection
- OpenRouter Model Fallbacks: https://openrouter.ai/docs/guides/routing/model-fallbacks
- OpenRouter Chat Completion API: https://openrouter.ai/docs/api-reference/chat-completion
- LiteLLM Router Architecture: https://docs.litellm.ai/docs/router_architecture
- Cloudflare AI Gateway Chat Completion: https://developers.cloudflare.com/ai-gateway/usage/chat-completion/
-
-与本仓库对应的可执行约束：
-
- 在 fallback candidate 构建阶段先做 `model_name -> model_list.model` 映射。
- 未命中映射时保留旧解析行为，保证兼容性。
- 用新增测试锁定“别名 + 嵌套模型路径 + 空默认 provider”场景。
-
-## 4. 实施步骤（顺序执行）
-
- [x] Step 1: 对齐现有代码模式，定位最小改动点（`pkg/agent` + `pkg/providers`）。
- [x] Step 2: 实现“基于 model_list 的 fallback 候选解析”。
- [x] Step 3: 增加/更新单元测试，覆盖 issue 场景。
- [x] Step 4: 代码风格一致性复核（与现有文件风格对照）。
- [x] Step 5: 运行质量门禁（LSP + `make check`）。
-
-## 5. 执行记录
-
- 状态：已完成
- 已完成改动：
-  - `pkg/providers/fallback.go`：新增 `ResolveCandidatesWithLookup`，并保持 `ResolveCandidates` 向后兼容。
-  - `pkg/agent/instance.go`：在构建 fallback candidates 前，优先通过 `model_list` 解析别名，并对无协议模型补齐默认 `openai/` 前缀后再解析。
-  - `pkg/providers/fallback_test.go`：新增别名解析与去重测试。
-  - `pkg/agent/instance_test.go`：新增 agent 侧别名解析到嵌套模型路径、无协议模型解析测试。
- 风格对齐检查（完成）：与 `pkg/providers/fallback_test.go`、`pkg/providers/model_ref_test.go` 现有模式一致。
- 质量验证（完成）：先 `make generate`，后 `make check` 全量通过。
--- a/pkg/channels/README.zh.md
+++ b/pkg/channels/README.zh.md