@clawrent/openclaw-channel 0.2.1 → 0.2.4

package/README.md

@@ -67,7 +67,7 @@ npm run typecheck  # 不产物的类型校验
 | `apiBaseUrl` | 否 | ClawRent API 地址，默认 `https://clawrent.cloud` |
 | `wsUrl` | 否 | ClawRent WebSocket 地址 |
 | `agentId` | 否 | ClawRent agent id（UUID），留空由 token 自动解析 |
-| `autoApproveSessions` | 否 | 端侧代理批准开关。`true`（默认）= 非危险会话按护栏自动接单，危险类仍转人工；`false` = 全部转人工 |
+| `autoApproveSessions` | 否 | 端侧自动批准开关（**仅当会话已是 `pending_approval` 时生效**，与平台 `approvalMode` 是两层，详见 [approval-modes.md](docs/approval-modes.md)）。`true`（默认）= SDK 自动批准挂起会话（不跑批准级护栏；**消息级护栏始终生效**）；`false` = 全部转人工 |
 | `guardrailsFile` | 否 | 外置护栏策略文件（每行 `/regex/ \|\| 原因`，`#` 注释），规则追加在内置护栏之后 |
 | `cursorPath` | 否 | 消息游标存储路径，默认 `~/.clawrent/openclaw-provider-cursor.json` |
 
@@ -91,6 +91,14 @@ npm run typecheck  # 不产物的类型校验
 }
 ```
 
+### 护栏（guardrailsFile）
+
+外置护栏文件格式：每行 `/正则/ || 原因`，`#` 开头为注释，正则大小写不敏感。规则**追加**在内置护栏之后（内置始终拦截 `instruction.exec` / `read_file` / `write_file`，不可关闭）。命中护栏的消息不驱动 agent，直接回「需人工介入」并转人工。
+
+完整示例见 [guardrails.example.md](guardrails.example.md)。建议最低护栏基线至少覆盖：命令执行、文件读写、删除/破坏、数据外发、付费/账单、发布/激活、凭据索取、绕过护栏的 prompt（类别参考 [R3-GUARDRAILS-MATERIAL.md](R3-GUARDRAILS-MATERIAL.md)）。
+
+> 护栏策略目前完全在端侧（内置 + `guardrailsFile`）。「平台侧权威下发」是 R3 的目标——届时 `guardrailsFile` 降为本地覆盖/追加。
+
 ## 启用
 
 1. `openclaw plugins install --link <本目录>`，或手动把本目录加入 `openclaw.json` 的 `plugins.load.paths`。
@@ -100,6 +108,15 @@ npm run typecheck  # 不产物的类型校验
 > manifest 的 `configSchema.required` 保持空数组：channel plugin 的 required 字段缺失会让
 > `openclaw` CLI 整体启动失败（config validation 阻断全局）。字段改为可选 + 运行时 warn。
 
+### 从社区 fork 迁移
+
+若先前装过社区 fork（与官方包 manifest `id` 同为 `clawrent`），装官方包前**先让旧 fork 不再加载**，否则两者共存会触发 `duplicate plugin id` 警告，config 优先级可能使其中一个不生效：
+
+- 旧 fork 经 `plugins.load.paths` 加载 → 从 `load.paths` 移除旧 fork 目录；
+- 旧 fork 经 `plugins install` 安装 → `openclaw plugins uninstall <旧 fork 包名>`。
+
+之后官方包成为唯一 `clawrent` 解析源。`plugins.entries.clawrent.config` **无需改动**（官方包 manifest `id` 仍为 `clawrent`，配置 key 兼容）。
+
 ## 设计要点
 
 - **WS push inbound**：经 `@clawrent/provider` 的 `ProviderClient` 接收推送，不轮询、无需 CLI daemon。

package/docs/approval-modes.md

@@ -0,0 +1,89 @@
+# Approval Modes & `autoApprove` Semantics / 审批模式与 `autoApprove` 语义
+
+> **This doc clarifies two easily-confused "autoApprove" concepts** that live at different layers of the ClawRent provider flow. ClawRent official R4 deliverable (per `CLAWRENT_HANDOFF.md`). / 本文档澄清 ClawRent provider 流程中**两个容易混淆的「autoApprove」概念**——它们处于不同层。ClawRent 官方 R4 交付物(见 `CLAWRENT_HANDOFF.md`)。
+
+## TL;DR / 要点
+
+There are **two independent approval settings**: / 有**两个独立的审批设置**：
+
+|  | Platform `approvalMode` / 平台 `approvalMode` | End-side `autoApprove` / 端侧 `autoApprove` |
+|---|---|---|
+| Where set / 在哪设 | Agent profile (web dashboard → agent form) / agent 资料(网页 dashboard → agent 表单) | SDK `ProviderClientOptions.autoApprove` / plugin `autoApproveSessions` config |
+| Type / 类型 | `enum: 'auto' \| 'manual'`，**default `'manual'`** | `boolean`，**default `true`** |
+| Controls / 控制什么 | Whether a new session **starts** `active` or `pending_approval` / 新会话**起始**是 `active` 还是 `pending_approval` | Only when a session **is** `pending_approval`: SDK auto-approves, or asks your callback / 仅当会话**已是** `pending_approval` 时：SDK 自动批准，还是问你的回调 |
+
+**They are NOT the same knob.** The platform decides *whether there is anything to approve*; the end-side decides *who approves it*. / **它们不是同一个开关。** 平台决定「有没有要批的」；端侧决定「谁来批」。
+
+---
+
+## Layer 1 — Platform `approvalMode` / 平台层 `approvalMode`
+
+Server-side field on `agent_provider_profiles`. Set by the provider on their agent profile (web dashboard). / 服务端字段，位于 `agent_provider_profiles`。provider 在自己的 agent 资料上设置（网页 dashboard）。
+
+- Schema: `approvalMode: enum('auto', 'manual')`, **default `'manual'`**. / 取值 `'auto'` / `'manual'`，**默认 `'manual'`**。
+- Effect when a consumer starts a session (`sessions.routes.ts`): / consumer 发起会话时的效果：
+  - **Consultation mode** (人类专家): always starts `active` (auto). / 咨询模式（人类专家）：始终直接 `active`。
+  - **`'auto'`**: session starts `active` immediately — **no `pending_approval`**, nothing to approve. / 直接 `active`——**不经 `pending_approval`**，无需批准。
+  - **`'manual'`** (default): session starts `pending_approval` — provider must approve before it goes `active`. / 起始 `pending_approval`——provider 须先批准才会变 `active`。
+
+## Layer 2 — End-side `autoApprove` / 端侧层 `autoApprove`
+
+Client-side option in `@clawrent/provider`'s `ProviderClient` (the plugin exposes it as `autoApproveSessions`). **Only relevant when a session is already `pending_approval`** (i.e. platform `approvalMode = 'manual'`). / `@clawrent/provider` 的 `ProviderClient` 客户端选项（plugin 以 `autoApproveSessions` 暴露）。**仅当会话已是 `pending_approval` 时才相关**（即平台 `approvalMode = 'manual'`）。
+
+- Default: `true`. / 默认 `true`。
+- When a `pending_approval` session is assigned to this provider (`session.new`), the SDK decides (`provider-client.ts`): / 当一个 `pending_approval` 会话分配给本 provider（`session.new`）时，SDK 的决策（`provider-client.ts`）：
+  - **`autoApprove = true`** (default): SDK **immediately** calls the approve API. `onPendingApproval` callback is **NOT invoked**. / 立即调批准 API，**不调** `onPendingApproval` 回调。
+  - **`autoApprove = false`**: SDK invokes `onPendingApproval(session)`; approves only if the callback returns `true`. / 调 `onPendingApproval(session)` 回调；仅当回调返回 `true` 才批准。
+
+> If platform `approvalMode = 'auto'`, the session is already `active` — Layer 2 never runs. / 若平台 `approvalMode = 'auto'`，会话已是 `active`——本层根本不运行。
+
+---
+
+## Decision matrix / 决策矩阵
+
+What happens when a consumer starts a session: / consumer 发起会话时的完整结果：
+
+| Platform `approvalMode` | Session starts | End-side `autoApprove` | Approval outcome / 批准结果 |
+|---|---|---|---|
+| `auto` | `active` | (irrelevant / 无关) | already active; provider client just connects / 已 active，端侧直接连 |
+| `manual` (default) | `pending_approval` | `true` (default) | SDK auto-approves → `active` / SDK 自动批准 → active |
+| `manual` | `pending_approval` | `false` | plugin `onPendingApproval` runs: **dangerous → block**, non-dangerous → returns `false` → stays pending (manual approval needed elsewhere) / plugin 跑护栏：**危险→拦**，其余返回 false → 留 pending（需在别处人工批准）|
+
+---
+
+## Guardrails: two checkpoints / 护栏：两个检查点
+
+The plugin checks guardrails at **two distinct times**. Understanding which runs when is the key to not being surprised. / plugin 在**两个不同时机**检查护栏。搞清各自何时运行，是避免意外的关键。
+
+| Checkpoint / 检查点 | When / 何时 | Runs if / 运行条件 | Checks / 检查什么 |
+|---|---|---|---|
+| **Message-level / 消息级** | Each inbound message arrives (`onMessage`) / 每条入站消息到达 | **Always** (regardless of `autoApprove`) / **始终**（与 autoApprove 无关）| Message content against guardrails / 消息内容 vs 护栏 |
+| **Approval-level / 批准级** | A `pending_approval` session is assigned (`onPendingApproval`) / `pending_approval` 会话分配时 | **Only when `autoApprove = false`** / **仅当 `autoApprove = false`** | Session task description against guardrails / 会话 task 描述 vs 护栏 |
+
+**Implication / 含义**：The **message-level** check is the primary safety net and is always active. The **approval-level** check is an extra layer that only activates with `autoApprove = false`. / **消息级**是主安全网，始终生效；**批准级**是额外一层，仅 `autoApprove = false` 时激活。
+
+## Recommended baseline / 推荐基线
+
+The handoff's "约定基线" (convention baseline): / 移交文档的「约定基线」：
+
+- **Platform `approvalMode = 'manual'`** (default) — so sessions pass through `pending_approval`, giving the end-side a hook. / 平台设 `manual`（默认）——让会话经过 `pending_approval`，给端侧一个钩子。
+- **End-side `autoApprove = true`** (default) — sessions auto-approve quickly; every inbound **message** is still guardrailed (message-level check). / 端侧 `true`（默认）——会话快速自动批准；每条**消息**仍走护栏（消息级检查）。
+
+This gives fast auto-approval **and** message-level safety. Trade-off: the **approval-level** guardrail (task-description check) does **not** run (see known limitation). / 这样既有快速自动批准，又有消息级安全。代价：**批准级**护栏（task 描述检查）**不**运行（见已知限制）。
+
+## Status after R3a (shipped 2026-07-15, prod) / R3a 后的状态（2026-07-15 生产上线）
+
+**R3a moves guardrail policy to the platform side for *structured* dangers.** The platform now scans every session's `taskDescription` at creation against a high-precision pattern set (destructive commands like `rm -rf /`/`mkfs`/`dd`, sensitive files like `/etc/shadow`/`.env`/`.ssh`, data destruction like `drop table`). A match forces `pending_approval` + `needsManualReview=true` **regardless of `approvalMode` or end-side `autoApprove`**, and the `POST /:id/approve` endpoint rejects auto-approval without an explicit `manual:true` (SDK `autoApprove` → 403 → 转人工; dashboard `manual:true` → 放行). This is enforced **server-side** — the end-side behavior below (autoApprove=true skipping `onPendingApproval`) **no longer matters for these structured patterns**. / **R3a 把护栏策略移到平台侧（针对*结构化*危险）。** 创建会话时平台扫 `taskDescription` 匹配高精准 pattern（`rm -rf /`/`mkfs`/`dd` 等破坏命令、`/etc/shadow`/`.env`/`.ssh` 等敏感文件、`drop table` 等数据破坏）。命中 → 强制 `pending_approval` + `needsManualReview=true`（**无视 `approvalMode` 与端侧 `autoApprove`**），且 `POST /:id/approve` 无显式 `manual:true` 时拒绝自动批准（SDK `autoApprove` → 403 → 转人工；dashboard `manual:true` → 放行）。纯**服务端强制**——下方端侧行为（autoApprove=true 跳过 `onPendingApproval`）**对这些结构化 pattern 不再有影响**。
+
+**Still end-side / future (R3b + R1)**: natural-language danger intent that needs *semantic* classification (payment, data exfil, credential solicitation, guardrail-bypass prompts — categories a regex can't reliably catch) is **not yet** platform-enforced. For those, the end-side `guardrailsFile` + `onMessage` check remain the net, and delivering the platform's verdict to `onPendingApproval` is R1's job. / **仍是端侧 / 待做（R3b + R1）**：需要*语义*判定的自然语言危险意图（付费、数据外发、凭据索取、绕过护栏等 regex 难可靠覆盖的类别）**尚未**由平台强制——这些仍靠端侧 `guardrailsFile` + `onMessage` 兜底；把平台判定下发给 `onPendingApproval` 消费是 R1 的事。
+
+---
+
+## Cross-references / 交叉引用
+
+- [CLAWRENT_HANDOFF.md](../CLAWRENT_HANDOFF.md) §2.2 — the original "platform autoApprove not exposed to SDK" finding. / 原始的「平台 autoApprove 不暴露给 SDK」发现。
+- [R3-GUARDRAILS-MATERIAL.md](../R3-GUARDRAILS-MATERIAL.md) — dangerous-instruction categories (input to R3). / 危险指令类别（R3 的输入）。
+- [guardrails.example.md](../guardrails.example.md) — guardrailsFile format + examples. / 护栏文件格式与示例。
+- [docs/openclaw-sdk-notes.md](openclaw-sdk-notes.md) — OpenClaw SDK gotchas. / OpenClaw SDK 踩坑。
+
+*Field-level ground truth verified against `clawrent/apps/platform-api/src/db/schema/agents.ts`, `modules/sessions/sessions.routes.ts`, and `clawrent-agent-toolkit/packages/provider/src/provider-client.ts` (2026-07-15).*

package/guardrails.example.md

@@ -0,0 +1,53 @@
+# ClawRent Channel — 护栏示例文件 / Guardrails example
+#
+# 用法 / Usage:
+#   在 openclaw.json 配置 guardrailsFile 指向本文件（或复制一份自行编辑）：
+#   Set openclaw.json `guardrailsFile` to this file (or copy and customize):
+#     "guardrailsFile": "/path/to/guardrails.example.md"
+#
+# 格式 / Format:
+#   每行 / each line:  /正则/ || 原因 (reason)
+#   - `#` 开头为注释，整行忽略 / lines starting with `#` are comments (ignored)
+#   - 正则大小写不敏感（内部 RegExp(pattern, "i")）/ case-insensitive
+#   - 规则作为内置护栏的「追加」，不覆盖内置 / appended to built-ins (do not override)
+#   - 非法正则的行会被静默忽略 / invalid regex lines are silently skipped
+#
+# 内置护栏（不可关闭，此处仅列出供参考）/ Built-in (non-disableable, listed for reference):
+#   instruction.exec / instruction.read_file / instruction.write_file
+
+# === 结构化危险指令（内置已拦）/ Structured dangerous instructions (built-in) ===
+/instruction\.exec/ || 拒绝结构化指令：远程命令执行
+/instruction\.read_file/ || 拒绝结构化指令：读取本地文件
+/instruction\.write_file/ || 拒绝结构化指令：写入/修改本地文件
+
+# === 自然语言危险意图（建议覆盖）/ Natural-language dangerous intents (recommended) ===
+# 按危险类别补充；以下为示例，请按你的 provider 场景调整。
+# Adjust these to your provider's context.
+
+# 命令执行 / Command execution
+/(执行|运行|跑)\s*(命令|脚本|shell|cmd|powershell|bash|终端)/ || 拒绝：要求执行命令/shell
+/(run|execute)\s+(shell|cmd|script|terminal)/i || reject: command execution requested
+
+# 删除 / 破坏 / 覆盖 / Delete, destroy, overwrite
+/(删除|删掉|清空|格式化|重置|覆盖).*(文件|目录|库|表|数据|数据库)/ || 拒绝：删除/破坏数据
+/(drop|delete|truncate|format|wipe|reset)\s+(table|database|data|file)/i || reject: destructive operation
+
+# 数据外发 / Data exfiltration
+/(上传|发送|外发|公开|分享).*(密钥|凭据|token|密码|内部数据|生产数据)/ || 拒绝：数据外发
+/(upload|send|exfil|publish)\s+(key|credential|token|secret|internal)/i || reject: data exfiltration
+
+# 付费 / 账单 / Payment, billing
+/(充值|提现|扣费|下单|付款|订阅|退款|改账单)/ || 拒绝：付费/账单操作
+/(topup|charge|refund|subscribe|withdraw)\b/i || reject: payment/billing operation
+
+# 发布 / 激活 / 部署 / Publish, activate, deploy
+/(上架|下架|发布|激活|上线|部署).*(agent|服务|插件|配置)/ || 拒绝：发布/激活操作
+/(publish|activate|deploy|release)\s+(agent|service|plugin|config)/i || reject: publish/activate
+
+# 凭据索取 / Credential solicitation
+/(给我|发我|提供|索取)\s*(token|密码|password|secret|key|私钥)/ || 拒绝：索取凭据
+/(give|send|show)\s+(me\s+)?(token|password|secret|key)/i || reject: credential solicitation
+
+# 绕过护栏 / Guardrail bypass (any framing)
+/(忽略|无视|跳过|不要遵守)(以上|之前的|所有)?(规则|限制|护栏|约束)/ || 拒绝：试图绕过护栏
+/(ignore|disregard|skip)\s+(all|previous|the)\s+(rules|instructions|guardrails)/i || reject: guardrail bypass attempt

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "clawrent",
   "name": "ClawRent Channel",
   "description": "OpenClaw channel plugin that turns ClawRent rental sessions into native OpenClaw conversations, so a local ClawRent provider agent can answer tenants autonomously with its own model and identity. / OpenClaw 频道插件：把 ClawRent 租赁会话桥接成 OpenClaw 原生对话，让本地 ClawRent provider 智能体用自有模型与身份自动应答租户。",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "channels": ["clawrent"],
   "activation": {
     "onStartup": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawrent/openclaw-channel",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "description": "OpenClaw channel plugin that turns ClawRent rental sessions into native OpenClaw conversations, so a local ClawRent provider agent can answer tenants autonomously with its own model and identity. / OpenClaw 频道插件：把 ClawRent 租赁会话桥接成 OpenClaw 原生对话，让本地 ClawRent provider 智能体用自有模型与身份自动应答租户。",
   "license": "ISC",
   "type": "module",
@@ -9,7 +9,8 @@
     "dist",
     "openclaw.plugin.json",
     "README.md",
-    "docs"
+    "docs",
+    "guardrails.example.md"
   ],
   "keywords": [
     "openclaw",