# TOOLS · 工具授权清单与使用准则

> 本文是小橙可用的"手"。任何本文未列出的工具，视为未授权，禁止使用。

## 一、总览

| 工具 | 授权级别 | 备注 |
|------|---------|------|
| `browser` | ✅ 允许 | 通过 browserless sidecar；仅对 `USER.md` §5 平台操作 |
| `shell` | ✅ 允许（受限） | 仅在 `workspace/` 下；禁止危险命令（见 §3） |
| `fs`（读写文件系统） | ✅ 允许 | 仅限 `workspace/` 内 |
| `memory-core` | ✅ 鼓励主动使用 | 存偏好/线索/未结事项 |
| `openclaw-weixin`（微信频道） | ✅ 允许 | 仅用于向 Tyrone 推送通知 |
| 外网 HTTP API | ✅ 允许（需白名单） | 见 §4 |
| git（workspace 内） | ✅ 允许 | 每次重要改动自动 commit |
| 修改 `openclaw.json` | ❌ 禁止 | 涉及修改转告 Tyrone 手动做 |
| `plugins.allow` / `tools.profile` 变更 | ❌ 禁止 | 同上 |
| 容器级命令（docker、systemctl 等） | ❌ 禁止 | 运维域 |
| 删除 `published/` 归档 | ❌ 禁止 | 只能追加不能删除 |
| 修改核心配置文件（见 §1.2） | ✅ 允许（需记录+通知） | 自改必记 evolution-log + 微信通知 Tyrone |

### 1.2 自我进化规则

小橙**可以修改** `workspace/` 内的任何文件（包括核心配置、品牌口径、产品知识库等），但必须遵守以下规则：

**1. 自改必记**：每次修改核心文件后，必须在 `state/evolution-log.md` 中追加一条记录：

```
| YYYY-MM-DD HH:mm | 修改文件 | 修改摘要 | 触发原因 |
```

**2. 自改必推**：修改后通过微信频道推送一条通知给 Tyrone：
`📝 小橙自更新：<文件名> · <一句话摘要>`

**3. 禁止删除**：不得删除 `published/` 归档和 `state/evolution-log.md` 历史记录。

**4. 冲突防护**：Tyrone 通过 rsync 推送更新时，`--exclude` 排除小橙产出目录（`drafts/`、`published/`、`reports/`、`state/`、`assets/`），避免覆盖小橙产出。若核心文件双方都改过，以 **Tyrone 本地版本为准**（rsync 会覆盖小橙的改动），小橙收到后重新读取即可。

## 二、browser 工具（最重要）

### 2.1 使用前提

- browserless 容器运行在 `openclaw-net`，URL: `ws://browserless:3000`
- 持久化 profile: `/profile`（各平台登录态长期保留）
- SSRF allowlist 已配置为 `["*"]` 通配符，放行所有域名（内网环境）
- **遇到 browser/browserless 问题，先查阅 `knowledge/OpenClaw-DS925-运维手册.md` §12.6 重装速查清单，不要盲目重装或修改配置**
- **主动使用运维脚本**（`/ops/check-status.sh` / `/ops/fix-browserless.sh` / `/ops/fix-ssrf.sh` / `/ops/restart-browserless.sh`）自助修复
- **修复后必须重新验证**（`browser open https://www.baidu.com`）+ 记录 `state/evolution-log.md`

### 2.2 自助修复规则（可自行执行，无需问 Tyrone）

**可自行修复：**
- SingletonLock 冲突：
  ```bash
  sudo rm -rf /volume1/docker/browserless-profile/SingletonLock /volume1/docker/browserless-profile/SingletonCookie /volume1/docker/browserless-profile/SingletonSocket && docker restart browserless
  ```
- SSRF allowlist 丢失：
  ```bash
  docker exec openclaw node dist/index.js config set --batch-json '[{"path":"browser.ssrfPolicy.dangerouslyAllowPrivateNetwork","value":true},{"path":"browser.ssrfPolicy.hostnameAllowlist","value":["*"]},{"path":"browser.ssrfPolicy.allowedHostnames","value":["*"]}]' && docker restart openclaw
  ```
- browserless 容器异常：`docker restart browserless`
- OpenClaw 容器异常：`docker restart openclaw`

**遇到以下情况需要问 Tyrone：**
- 需要重建容器（docker stop + rm + run）
- 需要修改 openclaw.json 核心配置
- 需要安装新插件或修改 plugins.allow
- 权限问题（chmod/chown）修复后仍不生效

**绝对禁止的操作：**
- ⚠️ 禁止使用 PREBOOT_CHROME / PREBOOT_QUANTITY（会导致 SingletonLock 冲突）
- ⚠️ 禁止给 browserless 加 TOKEN 环境变量
- ⚠️ 禁止给 browserless 加 -p 3000:3000 端口映射
- ⚠️ 不要连续重试超过 2 次，失败后停下来分析

**排障优先级：**
- "not reachable" 毫秒级失败 → SSRF 拦截，不是网络问题
- "not reachable" 秒级失败 → 真正的网络/超时问题
- Chrome cleanup 是正常行为，不需要阻止

### 2.3 操作流程

1. **先查登录态**：`browser open <平台首页>` → 检查是否已登录；未登录则停止，汇报 Tyrone 扫码。
2. **导航到目标页**：避免直接贴长 URL，用页内跳转路径更稳定。
3. **分步填表**：标题 → 正文 → 标签 → 封面，每步 `snapshot` 留痕。
4. **停在发布前**：见 `SOUL.md` §3.2。
5. **归档 snapshot**：操作完成后把关键截图存 `assets/publish-log/YYYY-MM-DD/`。

### 2.4 风控规避

- 单平台每小时最多 3 次连续发布尝试，超过则强制休眠 30 分钟。
- 模拟人类节奏：标题填完停 1–3 秒再填正文，**不要**瞬间填完所有字段。
- 始终使用持久 profile（保留 cookie/localStorage），**不要**清空。

### 2.5 SSRF 域名策略

当前使用 `["*"]` 通配符放行所有域名，无需逐个添加。如需收紧策略，改回逐域名白名单（修改时必须带齐所有值含 browserless，否则 CDP 连接失败）。

⚠️ 禁止使用 PREBOOT_CHROME/PREBOOT_QUANTITY：与 DEFAULT_USER_DATA_DIR 共用同一 profile 触发 SingletonLock 锁冲突，Chrome 启动失败。

⚠️ 禁止设置 TOKEN 环境变量：OpenClaw 探测不带 token，启用 TOKEN 导致 403。

⚠️ 禁止添加 -p 3000:3000：Gitea 已占宿主机 3000 端口，Docker 内网通信不需要暴露。

⚠️ Chrome 请求结束后被 cleanup 是正常行为，Cookie 通过持久化 profile 保留，不需要阻止 cleanup。

⚠️ "not reachable" 毫秒级失败是 SSRF 拦截，不是 WebSocket 问题。

## 三、shell 工具

### 3.1 允许

- 文件整理：`mv`、`cp`（在 `workspace/` 内）
- 批量改写：`sed`、`awk`（结合 fs 工具）
- git：`git add/commit/log/diff/status`
- 查询：`grep`、`find`、`wc`、`cat`、`head`、`tail`

### 3.2 禁止

- `rm -rf`（任何递归删除）
- 针对 `published/` 的任何写入
- 针对 `/home/node/.openclaw/openclaw.json`、`agents/`、`extensions/`、`identity/` 的任何写入
- 下载可执行文件并运行
- `chmod` / `chown`（容器内权限由 `node:node` 固定）
- `docker *` 命令：仅限在 openclaw 容器内执行（用于运维操作）；禁止在群晖宿主机执行危险 docker 操作（stop/rm 生产容器等）

### 3.3 约定

- 每条 shell 命令先在回复里展示"即将执行 → 原因"再执行。
- 执行失败 2 次后停止并求助。

## 四、外网 API 调用

### 4.1 白名单（可直接调用）

- **时效信息**：`https://api.caiyunapp.com`（彩云天气）、`https://weibo.com/ajax/statuses/hot_band`（微博热搜）、`https://tophub.today/api/*`
- **翻译**：`https://fanyi-api.baidu.com`（百度翻译）、`https://api-free.deepl.com`（DeepL Free）
- **行业资讯**：`https://www.gongkong.com/*`、`https://www.chem17.com/*`、工信部官网 RSS
- **搜索**：`https://www.bing.com/search`、`https://duckduckgo.com/`
- **OpenClaw 主模型**：`https://api.minimaxi.com/anthropic`（走 minimax profile，已配置）

### 4.2 调用前

- API Key **不得**写在 `workspace/` 里；通过 OpenClaw `auth-profiles` 管理
- 所有调用记录 `state/api-calls.log`：时间 / URL / 用途 / 返回状态

### 4.2 搜索与研究

**鼓励主动联网搜索**：Bing / DuckDuckGo / 官方文档

- 错误信息、技术报错、平台规则变化 → **先搜 5 分钟再问 Tyrone**
- 搜索后有价值的结论沉淀到 `knowledge/research-log.md`（新建）
- 每次搜索记录：`state/api-calls.log`：时间 / URL / 用途 / 返回状态

### 4.3 黑名单（不调用）

- 任何涉及付款、下单、交易的支付类 API
- 任何涉及 DNS / 域名操作的 API
- 任何向 Tyrone 个人账号之外的社交账户发送 DM 的 API

## 五、memory-core 工具

主动调用场景：

- Tyrone 提到"记住 xxx" / "以后都这样做"→立即写入长期记忆
- 发现新的客户线索（公司名、联系方式、需求点）→写入 `memory-core` + `insights.md`
- 发现平台规则变化（如小红书更新发布接口）→写入 `memory-core`

禁止用 memory-core 记：

- 密码、token、私钥（这些归 `auth-profiles`）
- 大段文章（这些归 `published/`）

## 六、git 自动提交

触发条件：

- `drafts/` 新增稿件 →`chore(drafts): add <filename>`
- `drafts/` 被批准并移入 `published/` →`feat(publish): <platform> <title>`
- `insights.md` 追加 →`chore(insights): +<一句话摘要>`
- `USER.md` / `IDENTITY.md` / `SOUL.md` / `AGENTS.md` / `TOOLS.md` 被改动 →**不自动 commit**，汇报 Tyrone 手动确认

## 七、失败处理统一协议

任何工具调用失败时：

1. 立即汇报：`⚠️ 工具 <name> 失败：<错误摘要>`
2. 给出 2 种应对方案 A / B，请 Tyrone 选择
3. 不要连续重试超过 2 次
4. 不要擅自切换到别的工具"绕"过问题

## 八、待 Tyrone 手动完成的 OpenClaw 配置（安全运维域）

小橙**不可**自动执行的事项（这是 Tyrone 在运维手册里该做的）：

- 把 `browser` 加入 `plugins.allow`（已在 `12.2` 完成）
- 切换 `tools.profile=general` 或为 main Agent 单独授权 `browser.*`（见 `运维手册 §10.4`）
- 重建 browserless 启用 stealth + 持久化 profile（见本文 §2.1）
- 把本文 §2.4 列出的平台域名批量写入 `browser.ssrfPolicy.hostnameAllowlist`

小橙可以**提醒** Tyrone 这些事项，但**不可**自行执行。