openclaw-botonline 0.1.4

package/docs/start/clawd.md

@@ -0,0 +1,227 @@
+---
+summary: "运行 Clawdbot 作为个人助手的端到端指南，包含安全警告"
+read_when:
+  - 新建助手实例
+  - 审查安全/权限影响
+---
+# 使用 Clawdbot 构建个人助手（Clawd 风格）
+
+Clawdbot 是一个用于 **Pi** 代理的 WhatsApp + Telegram + Discord + iMessage 网关。插件增加了 Mattermost 支持。本指南是 "个人助手" 设置：一个专用的 WhatsApp 号码，行为类似于您始终在线的代理。
+
+## ⚠️ 安全第一
+
+您将代理置于以下位置：
+- 在您的机器上运行命令（取决于您的 Pi 工具设置）
+- 读取/写入工作区中的文件
+- 通过 WhatsApp/Telegram/Discord/Mattermost（插件）发送消息
+
+保守开始：
+- 始终设置 `channels.whatsapp.allowFrom`（永远不要在您的个人 Mac 上运行面向全世界开放的服务）。
+- 为助手使用专用的 WhatsApp 号码。
+- 心跳现在默认每 30 分钟一次。在信任设置之前禁用，方法是设置 `agents.defaults.heartbeat.every: "0m"`。
+## 先决条件
+
+- Node **22+**
+- Clawdbot 在 PATH 中可用（推荐：全局安装）
+- 助手的第二个电话号码（SIM/eSIM/预付费）
+
+```bash
+npm install -g openclaw-cn@latest
+# 或：pnpm add -g openclaw-cn@latest
+```
+
+从源码（开发）：
+
+```bash
+git clone https://github.com/clawdbot/clawdbot.git
+cd clawdbot
+pnpm install
+pnpm ui:build # 首次运行时自动安装 UI 依赖
+pnpm build
+pnpm link --global
+```
+
+## 双手机设置（推荐）
+
+您需要这样：
+
+```
+您的手机（个人）              第二部手机（助手）
+┌─────────────────┐           ┌─────────────────┐
+│  您的 WhatsApp  │  ──────▶  │  助手 WA        │
+│  +1-555-YOU     │  消息     │  +1-555-CLAWD   │
+└─────────────────┘           └────────┬────────┘
+                                       │ 通过二维码连接
+                                       ▼
+                              ┌─────────────────┐
+                              │  您的 Mac       │
+                              │  (clawdbot)      │
+                              │    Pi 代理      │
+                              └─────────────────┘
+```
+
+如果您将个人 WhatsApp 与 Clawdbot 关联，每条发给您的消息都会变成 "代理输入"。这很少是您想要的结果。
+## 5分钟快速开始
+
+1) 配对 WhatsApp Web（显示二维码；用助手手机扫描）：
+
+```bash
+openclaw-cn channels login
+```
+
+2) 启动网关（保持运行）：
+
+```bash
+openclaw-cn gateway --port 18789
+```
+
+3) 在 `~/.openclaw/openclaw.json` 中放置最小配置：
+
+```json5
+{
+  channels: { whatsapp: { allowFrom: ["+15555550123"] } }
+}
+```
+
+现在从您的白名单手机向助手号码发送消息。
+
+入门完成后，我们会自动打开带有网关令牌的仪表板并打印令牌化链接。稍后重新打开：`openclaw-cn dashboard`。
+## 给代理一个工作空间（AGENTS）
+
+Clawd 从其工作空间目录读取操作指令和 "记忆"。
+
+默认情况下，Clawdbot 使用 `~/clawd` 作为代理工作空间，并将在设置/首次代理运行时自动创建它（以及初始的 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`）。`BOOTSTRAP.md` 仅在工作空间全新时创建（删除后不应再出现）。
+
+提示：将此文件夹视为 Clawd 的 "记忆" 并将其设为 git 仓库（理想情况下是私有的），以便备份您的 `AGENTS.md` + 记忆文件。如果安装了 git，全新的工作空间会自动初始化。
+
+```bash
+openclaw-cn setup
+```
+
+完整的工作空间布局 + 备份指南：[代理工作空间](/concepts/agent-workspace)
+记忆工作流程：[记忆](/concepts/memory)
+
+可选：使用 `agents.defaults.workspace` 选择不同的工作空间（支持 `~`）。
+
+```json5
+{
+  agent: {
+    workspace: "~/clawd"
+  }
+}
+```
+
+如果您已经从仓库部署自己的工作空间文件，您可以完全禁用引导文件创建：
+
+```json5
+{
+  agent: {
+    skipBootstrap: true
+  }
+}
+```
+## 将其转变为 "助手" 的配置
+
+Clawdbot 默认为良好的助手设置，但通常您需要调整：
+- `SOUL.md` 中的个性/指令
+- 思考默认值（如需要）
+- 心跳（一旦信任它）
+
+示例：
+
+```json5
+{
+  logging: { level: "info" },
+  agent: {
+    model: "anthropic/claude-opus-4-5",
+    workspace: "~/clawd",
+    thinkingDefault: "high",
+    timeoutSeconds: 1800,
+    // 从 0 开始；稍后启用。
+    heartbeat: { every: "0m" }
+  },
+  channels: {
+    whatsapp: {
+      allowFrom: ["+15555550123"],
+      groups: {
+        "*": { requireMention: true }
+      }
+    }
+  },
+  routing: {
+    groupChat: {
+      mentionPatterns: ["@clawd", "clawd"]
+    }
+  },
+  session: {
+    scope: "per-sender",
+    resetTriggers: ["/new", "/reset"],
+    reset: {
+      mode: "daily",
+      atHour: 4,
+      idleMinutes: 10080
+    }
+  }
+}
+```
+## 会话和记忆
+
+- 会话文件：`~/.openclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl`
+- 会话元数据（令牌使用情况、最后路由等）：`~/.openclaw/agents/<agentId>/sessions/sessions.json`（旧版：`~/.openclaw/sessions/sessions.json`）
+- `/new` 或 `/reset` 为此聊天启动一个新会话（可通过 `resetTriggers` 配置）。如果单独发送，代理会回复简短问候以确认重置。
+- `/compact [instructions]` 压缩会话上下文并报告剩余的上下文预算。
+## 心跳（主动模式）
+
+默认情况下，Clawdbot 每 30 分钟运行一次心跳，提示为：
+`如果存在 HEARTBEAT.md，则阅读它（工作区上下文）。严格遵循它。不要从之前的聊天中推断或重复旧任务。如果没有需要注意的事情，回复 HEARTBEAT_OK。`
+设置 `agents.defaults.heartbeat.every: "0m"` 以禁用。
+
+- 如果 `HEARTBEAT.md` 存在但实际上是空的（只有空白行和像 `# 标题` 这样的 markdown 标题），Clawdbot 会跳过心跳运行以节省 API 调用。
+- 如果文件缺失，心跳仍会运行，模型决定做什么。
+- 如果代理回复 `HEARTBEAT_OK`（可选择带短填充；参见 `agents.defaults.heartbeat.ackMaxChars`），Clawdbot 会抑制该心跳的出站传递。
+- 心跳运行完整的代理回合 — 较短的间隔会消耗更多令牌。
+
+```json5
+{
+  agent: {
+    heartbeat: { every: "30m" }
+  }
+}
+```
+## 媒体输入和输出
+
+传入附件（图像/音频/文档）可以通过模板呈现给您的命令：
+- `{{MediaPath}}`（本地临时文件路径）
+- `{{MediaUrl}}`（伪 URL）
+- `{{Transcript}}`（如果启用了音频转录）
+
+代理的传出附件：在单独一行包含 `MEDIA:<path-or-url>`（无空格）。例如：
+
+```
+这是截图。
+MEDIA:/tmp/screenshot.png
+```
+
+Clawdbot 提取这些并随文本一起作为媒体发送。
+## 操作清单
+
+```bash
+openclaw-cn status          # 本地状态（凭据、会话、排队事件）
+openclaw-cn status --all    # 完整诊断（只读、可粘贴）
+openclaw-cn status --deep   # 添加网关健康检查（Telegram + Discord）
+openclaw-cn health --json   # 网关健康快照（WS）
+```
+
+日志位于 `/tmp/clawdbot/` 下（默认：`clawdbot-YYYY-MM-DD.log`）。
+
+## 下一步
+
+- WebChat：[WebChat](/web/webchat)
+- 网关操作：[网关运行手册](/gateway)
+- Cron + 唤醒：[Cron 作业](/automation/cron-jobs)
+- macOS 菜单栏伴侣：[Clawdbot macOS 应用](/platforms/macos)
+- iOS 节点应用：[iOS 应用](/platforms/ios)
+- Android 节点应用：[Android 应用](/platforms/android)
+- Windows 状态：[Windows (WSL2)](/platforms/windows)
+- Linux 状态：[Linux 应用](/platforms/linux)
+- 安全：[安全](/gateway/security)

package/docs/start/getting-started.md

@@ -0,0 +1,196 @@
+---
+summary: "初学者指南：从零到第一条消息（向导、认证、通道、配对）"
+read_when:
+  - 零基础首次设置
+  - 想要最快地从安装 → 入门 → 发送首条消息
+---
+
+# 开始使用
+
+目标：尽可能快地从**零** → **首次可用聊天**（使用合理默认值）。
+
+推荐路径：使用**CLI 入门向导**（`openclaw-cn onboard`）。它会设置：
+- 模型/认证（推荐 OAuth）
+- 网关设置
+- 通道（WhatsApp/Telegram/Discord/Mattermost（插件）/...）
+- 配对默认值（安全私信）
+- 工作区引导 + 技能
+- 可选后台服务
+
+如果您想了解更深层的参考页面，请跳转至：[向导](/start/wizard)，[设置](/start/setup)，[配对](/start/pairing)，[安全](/gateway/security)。
+
+沙盒说明：`agents.defaults.sandbox.mode: "non-main"` 使用 `session.mainKey`（默认为`"main"`），
+因此群组/频道会话会被沙盒化。如果希望主代理始终
+在主机上运行，请设置明确的每个代理覆盖：
+
+```json
+{
+  "routing": {
+    "agents": {
+      "main": {
+        "workspace": "~/clawd",
+        "sandbox": { "mode": "off" }
+      }
+    }
+  }
+}
+```
+
+## 0) 前提条件
+
+- Node `>=22`
+- `pnpm`（可选；如果从源码构建则推荐）
+- **推荐：** 用于网络搜索的 Brave Search API 密钥。最简单的路径：
+  `openclaw-cn configure --section web`（存储 `tools.web.search.apiKey`）。
+  参见 [Web 工具](/tools/web)。
+
+macOS：如果计划构建应用程序，请安装 Xcode / CLT。仅 CLI + 网关的话，Node 就足够了。
+Windows：使用 **WSL2**（推荐 Ubuntu）。强烈推荐 WSL2；原生 Windows 未经测试，问题更多，工具兼容性也较差。请先安装 WSL2，然后在 WSL 内运行 Linux 步骤。参见 [Windows (WSL2)](/platforms/windows)。
+
+## 1) 安装 CLI（推荐）
+
+```bash
+curl -fsSL https://clawd.org.cn/install.sh | bash
+```
+
+安装程序选项（安装方法、非交互式、来自 GitHub）：[安装](/install)。
+
+Windows（PowerShell）：
+
+```powershell
+iwr -useb https://clawd.org.cn/install.ps1 | iex
+```
+
+替代方案（全局安装）：
+
+```bash
+npm install -g openclaw-cn@latest
+```
+
+```bash
+pnpm add -g openclaw-cn@latest
+```
+
+## 2) 运行入门向导（并安装服务）
+
+```bash
+openclaw-cn onboard --install-daemon
+```
+
+您将选择：
+- **本地与远程**网关
+- **认证**：OpenAI Code（Codex）订阅（OAuth）或 API 密钥。对于 Anthropic 我们推荐使用 API 密钥；也支持 `claude setup-token`。
+- **提供商**：WhatsApp QR 登录、Telegram/Discord 机器人令牌、Mattermost 插件令牌等。
+- **守护进程**：后台安装（launchd/systemd；WSL2 使用 systemd）
+  - **运行时**：Node（推荐；WhatsApp/Telegram 必需）。**不推荐**使用 Bun。
+- **网关令牌**：向导默认生成一个（即使在回环地址上）并存储在 `gateway.auth.token` 中。
+
+向导文档：[向导](/start/wizard)
+
+### 认证：其存储位置（重要）
+
+- **推荐的 Anthropic 路径：** 设置一个 API 密钥（向导可以将其存储以供服务使用）。如果您想重用 Claude Code 凭据，也支持 `claude setup-token`。
+
+- OAuth 凭据（旧版导入）：`~/.openclaw/credentials/oauth.json`
+- 认证配置文件（OAuth + API 密钥）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+
+无头/服务器提示：先在普通机器上完成 OAuth，然后将 `oauth.json` 复制到网关主机。
+
+## 3) 启动网关
+
+如果您在入门过程中安装了服务，网关应该已经在运行：
+
+```bash
+openclaw-cn gateway status
+```
+
+手动运行（前台）：
+
+```bash
+openclaw-cn gateway --port 18789 --verbose
+```
+
+仪表板（本地回环）：`http://127.0.0.1:18789/`
+如果配置了令牌，请将其粘贴到控制界面设置中（存储为 `connect.params.auth.token`）。
+
+⚠️ **Bun 警告（WhatsApp + Telegram）：** Bun 在这些
+渠道上有已知问题。如果您使用 WhatsApp 或 Telegram，请使用 **Node** 运行网关。
+## 3.5) 快速验证（2 分钟）
+
+```bash
+openclaw-cn status
+openclaw-cn health
+```
+
+## 4) 配对 + 连接您的首个聊天界面
+
+### WhatsApp（二维码登录）
+
+```bash
+openclaw-cn channels login
+```
+
+通过 WhatsApp → 设置 → 已连接的设备 扫描。
+
+WhatsApp 文档：[WhatsApp](/channels/whatsapp)
+
+### Telegram / Discord / 其他
+
+向导可以为您写入令牌/配置。如果您更喜欢手动配置，请从以下开始：
+- Telegram：[Telegram](/channels/telegram)
+- Discord：[Discord](/channels/discord)
+- Mattermost（插件）：[Mattermost](/channels/mattermost)
+
+**Telegram 私信提示：** 您的首次私信会返回一个配对码。批准它（参见下一步）或机器人不会响应。
+## 5) 私信安全（配对审批）
+
+默认策略：未知私信会收到一个短代码，消息在获得批准前不会被处理。
+如果您的首次私信没有得到回复，请批准配对：
+
+```bash
+openclaw-cn pairing list whatsapp
+openclaw-cn pairing approve whatsapp <code>
+```
+
+配对文档：[配对](/start/pairing)
+
+## 从源码运行（开发）
+
+如果您正在修改 Clawdbot 本身，请从源码运行：
+
+```bash
+git clone https://github.com/clawdbot/clawdbot.git
+cd clawdbot
+pnpm install
+pnpm ui:build # 首次运行时自动安装 UI 依赖
+pnpm build
+openclaw-cn onboard --install-daemon
+```
+
+如果您还没有全局安装，请从仓库中通过 `pnpm openclaw-cn ...` 运行入门步骤。
+
+网关（来自此仓库）：
+
+```bash
+node dist/entry.js gateway --port 18789 --verbose
+```
+
+## 7) 端到端验证
+
+在新的终端中，发送一条测试消息：
+
+```bash
+openclaw-cn message send --target +15555550123 --message "Hello from Clawdbot"
+```
+
+如果 `openclaw-cn health` 显示 "no auth configured"，请返回向导并设置 OAuth/密钥认证 — 代理在没有它的情况下无法响应。
+
+提示：`openclaw-cn status --all` 是最佳的可粘贴只读调试报告。
+健康检查：`openclaw-cn health`（或 `openclaw-cn status --deep`）向运行中的网关请求健康快照。
+
+## 下一步（可选，但很棒）
+
+- macOS 菜单栏应用 + 语音唤醒：[macOS 应用](/platforms/macos)
+- iOS/Android 节点（Canvas/摄像头/语音）：[节点](/nodes)
+- 远程访问（SSH 隧道 / Tailscale 服务）：[远程访问](/gateway/remote) 和 [Tailscale](/gateway/tailscale)
+- 始终在线 / VPN 设置：[远程访问](/gateway/remote)，[exe.dev](/platforms/exe-dev)，[Hetzner](/platforms/hetzner)，[macOS 远程](/platforms/mac/remote)

package/docs/start/hubs.md

@@ -0,0 +1,182 @@
+---
+summary: "链接到每个 Clawdbot 文档的中心"
+read_when:
+  - 您想要完整的文档地图
+---
+# 文档中心
+
+使用这些中心来发现每一页，包括左侧导航中未出现的深入探讨和参考文档。
+
+## 从此开始
+
+- [索引](/)
+- [开始使用](/start/getting-started)
+- [入门](/start/onboarding)
+- [向导](/start/wizard)
+- [设置](/start/setup)
+- [仪表板（本地网关）](http://127.0.0.1:18789/)
+- [帮助](/help)
+- [配置](/gateway/configuration)
+- [配置示例](/gateway/configuration-examples)
+- [Clawdbot 助手 (Clawd)](/start/clawd)
+- [展示](/start/showcase)
+- [背景故事](/start/lore)
+
+## 安装 + 更新
+
+- [Docker](/install/docker)
+- [Nix](/install/nix)
+- [更新 / 回滚](/install/updating)
+- [Bun 工作流（实验性）](/install/bun)
+
+## 核心概念
+
+- [架构](/concepts/architecture)
+- [网络中心](/network)
+- [代理运行时](/concepts/agent)
+- [代理工作区](/concepts/agent-workspace)
+- [记忆](/concepts/memory)
+- [代理循环](/concepts/agent-loop)
+- [流式传输 + 分块](/concepts/streaming)
+- [多代理路由](/concepts/multi-agent)
+- [压缩](/concepts/compaction)
+- [会话](/concepts/session)
+- [会话（别名）](/concepts/sessions)
+- [会话修剪](/concepts/session-pruning)
+- [会话工具](/concepts/session-tool)
+- [队列](/concepts/queue)
+- [斜杠命令](/tools/slash-commands)
+- [RPC 适配器](/reference/rpc)
+- [TypeBox 模式](/concepts/typebox)
+- [时区处理](/concepts/timezone)
+- [存在性](/concepts/presence)
+- [发现 + 传输](/gateway/discovery)
+- [Bonjour](/gateway/bonjour)
+- [通道路由](/concepts/channel-routing)
+- [群组](/concepts/groups)
+- [群组消息](/concepts/group-messages)
+- [模型故障转移](/concepts/model-failover)
+- [OAuth](/concepts/oauth)
+
+## 提供商 + 入口
+
+- [聊天通道中心](/channels)
+- [模型提供商中心](/providers/models)
+- [WhatsApp](/channels/whatsapp)
+- [Telegram](/channels/telegram)
+- [Telegram (grammY 笔记)](/channels/grammy)
+- [Slack](/channels/slack)
+- [Discord](/channels/discord)
+- [Mattermost](/channels/mattermost) (插件)
+- [Signal](/channels/signal)
+- [iMessage](/channels/imessage)
+- [位置解析](/channels/location)
+- [WebChat](/web/webchat)
+- [Webhooks](/automation/webhook)
+- [Gmail Pub/Sub](/automation/gmail-pubsub)
+
+## 网关 + 操作
+
+- [网关运行手册](/gateway)
+- [网关配对](/gateway/pairing)
+- [网关锁定](/gateway/gateway-lock)
+- [后台进程](/gateway/background-process)
+- [健康](/gateway/health)
+- [心跳](/gateway/heartbeat)
+- [诊断](/gateway/doctor)
+- [日志](/gateway/logging)
+- [沙盒](/gateway/sandboxing)
+- [仪表板](/web/dashboard)
+- [控制界面](/web/control-ui)
+- [远程访问](/gateway/remote)
+- [远程网关 README](/gateway/remote-gateway-readme)
+- [Tailscale](/gateway/tailscale)
+- [安全](/gateway/security)
+- [故障排除](/gateway/troubleshooting)
+
+## 工具 + 自动化
+
+- [工具概览](/tools)
+- [OpenProse](/prose)
+- [CLI 参考](/cli)
+- [执行工具](/tools/exec)
+- [提升模式](/tools/elevated)
+- [Cron 作业](/automation/cron-jobs)
+- [Cron 与心跳](/automation/cron-vs-heartbeat)
+- [思考 + 详细](/tools/thinking)
+- [模型](/concepts/models)
+- [子代理](/tools/subagents)
+- [代理发送 CLI](/tools/agent-send)
+- [终端 UI](/tui)
+- [浏览器控制](/tools/browser)
+- [浏览器（Linux 故障排除）](/tools/browser-linux-troubleshooting)
+- [投票](/automation/poll)
+
+## 节点、媒体、语音
+
+- [节点概述](/nodes)
+- [摄像头](/nodes/camera)
+- [图像](/nodes/images)
+- [音频](/nodes/audio)
+- [位置命令](/nodes/location-command)
+- [语音唤醒](/nodes/voicewake)
+- [通话模式](/nodes/talk)
+
+## 平台
+
+- [平台概述](/platforms)
+- [macOS](/platforms/macos)
+- [iOS](/platforms/ios)
+- [Android](/platforms/android)
+- [Windows (WSL2)](/platforms/windows)
+- [Linux](/platforms/linux)
+- [Web 界面](/web)
+
+## macOS 伴侣应用（高级）
+
+- [macOS 开发设置](/platforms/mac/dev-setup)
+- [macOS 菜单栏](/platforms/mac/menu-bar)
+- [macOS 语音唤醒](/platforms/mac/voicewake)
+- [macOS 语音叠加](/platforms/mac/voice-overlay)
+- [macOS WebChat](/platforms/mac/webchat)
+- [macOS Canvas](/platforms/mac/canvas)
+- [macOS 子进程](/platforms/mac/child-process)
+- [macOS 健康](/platforms/mac/health)
+- [macOS 图标](/platforms/mac/icon)
+- [macOS 日志](/platforms/mac/logging)
+- [macOS 权限](/platforms/mac/permissions)
+- [macOS 远程](/platforms/mac/remote)
+- [macOS 签名](/platforms/mac/signing)
+- [macOS 发布](/platforms/mac/release)
+- [macOS 网关 (launchd)](/platforms/mac/bundled-gateway)
+- [macOS XPC](/platforms/mac/xpc)
+- [macOS 技能](/platforms/mac/skills)
+- [macOS Peekaboo](/platforms/mac/peekaboo)
+
+## 工作区 + 模板
+
+- [技能](/tools/skills)
+- [ClawdHub](/tools/clawdhub)
+- [技能配置](/tools/skills-config)
+- [默认 AGENTS](/reference/AGENTS.default)
+- [模板：AGENTS](/reference/templates/AGENTS)
+- [模板：BOOTSTRAP](/reference/templates/BOOTSTRAP)
+- [模板：HEARTBEAT](/reference/templates/HEARTBEAT)
+- [模板：IDENTITY](/reference/templates/IDENTITY)
+- [模板：SOUL](/reference/templates/SOUL)
+- [模板：TOOLS](/reference/templates/TOOLS)
+- [模板：USER](/reference/templates/USER)
+
+## 实验（探索性）
+
+- [入门配置协议](/experiments/onboarding-config-protocol)
+- [Cron 强化笔记](/experiments/plans/cron-add-hardening)
+- [群组策略强化笔记](/experiments/plans/group-policy-hardening)
+- [研究：记忆](/experiments/research/memory)
+- [模型配置探索](/experiments/proposals/model-config)
+
+## 测试 + 发布
+
+- [测试](/reference/test)
+- [发布清单](/reference/RELEASING)
+- [设备型号](/reference/device-models)