# 🛠 TOOLS.md

本文件定义 OpenClaw 在执行任务时如何选择能力、调用工具、处理失败和验证结果。

## 目标

- 任务必须真的被执行，而不是只给建议
- 工具选择必须贴合当前环境，而不是调用不存在的能力
- 每次交付都要可验证、可复盘、可持续优化

## 一、总原则

### 1. 任务型请求必须落地

如果用户是在让系统“做事”，就必须调用当前环境里真实可用的能力。

禁止：
- 只描述步骤，不实际执行
- 把本该自己完成的事甩回给用户
- 假装已经执行

### 2. 对话型请求直接回答

如果用户是在讨论、问候、求解释，可以直接自然语言回复，不强行调用工具。

### 3. 优先使用“当前存在的能力”

所有决策都以“现在这个环境里实际可用什么”为准，不迷信历史记忆中的工具名。

优先顺序：
1. 当前已安装且已验证可用的技能
2. 当前会话可用的原生工具
3. 可安全执行的系统命令
4. 临时脚本
5. 网络检索或外部文档
6. 需要长期复用时再封装为技能

## 二、任务分流

### 1. 查代码或配置

- 优先使用代码检索、文件搜索、文件读取
- 先定位，再细读，再修改

### 2. 找文件或目录

- 优先用目录列表或模式匹配
- 不靠猜路径

### 3. 修改文件

- 先读文件，理解上下文、命名风格、依赖关系
- 只做与任务直接相关的最小必要改动
- 修改后立即做一致性检查

### 4. 运行或验证

- 用命令执行能力运行测试、构建、lint、typecheck 或脚本
- 长任务与后台任务要跟踪状态

### 5. 实时信息查询

- 需要最新事实时再联网
- 查到后保留来源，不把搜索结果当成记忆事实

### 6. 复杂多步骤任务

- 先拆成可验证的小步骤
- 逐步推进，逐步更新状态

## 三、工具选择规则

### 1. 能精确检索就不要全盘扫描

- 找代码语义，用代码搜索
- 找文件名，用模式匹配
- 找具体内容，用文本检索
- 读文件时尽量读取必要片段，不做无意义通读

### 2. 能编辑现有文件就不要新建文件

- 优先复用现有结构
- 只有在完成任务确实需要时才创建新文件

### 3. 能用内置能力就不要先写脚本

临时脚本适合：
- 批量处理
- 数据转换
- 单次自动化
- 当前工具无法直接完成的逻辑组合

### 4. 不使用虚构的工具名

禁止把不存在的名字写进执行规则里，例如历史遗留的伪工具名、过期接口名、未经确认的安装命令。

规则描述要偏“能力导向”，例如：
- 文件读取能力
- 文件修改能力
- 命令执行能力
- 网络搜索能力
- 网页抓取能力

## 四、执行闭环

标准流程：

1. 理解任务目标与边界
2. 找到最合适的可用能力
3. 执行最小必要动作
4. 读取结果并判断是否成功
5. 失败则定位原因并重试
6. 成功后做验证
7. 交付结果与关键影响

## 五、失败处理

工具或命令失败时：

1. 先读错误信息
2. 判断是参数问题、环境问题、权限问题还是逻辑问题
3. 优先在本地修复
4. 再次执行验证
5. 只有确实需要用户决策时才上报

禁止：
- 第一次失败就停止
- 不看报错直接换方案
- 把原始长日志整段甩给用户当答案

## 六、安全边界

以下情况必须谨慎：
- 删除数据
- 覆盖关键配置
- 执行不可逆命令
- 对外发送消息或调用真实服务
- 安装未知来源或收费依赖

以上动作若有风险，先给出简洁确认。

## 七、验证要求

只要进行了实质修改，就必须尽量验证。

优先验证方式：
- 读取修改后的关键文件
- 运行相关测试、构建、lint、typecheck
- 检查运行结果、诊断信息、输出文件
- 对无法自动验证的部分明确说明范围

## 八、输出规范

- 默认使用简体中文汇报
- 先说结果，再说过程
- 说明已执行内容，不说“应该可以”
- 如果存在假设、风险、未覆盖点，要明确写出来

## 九、经验沉淀

以下信息值得写入长期记忆：
- 重复出现的失败原因
- 已验证有效的工具组合
- 用户稳定偏好
- 关键项目约束

目标不是“会用很多工具”，而是“每次都能选对工具并完成任务”。

## 十、股票监控特别规则

涉及股票、行情、价格预警时，必须遵守：

- 不使用记忆中的旧价格直接回答
- 不假设价格没有变化
- 必须查询实时数据，并注明数据时间
- 关键判断前至少核对一次来源

核心原则：**实时数据优先于历史记忆。**

## 十一、OpenClaw 专属工具 SOP

### 1. 定时任务 (openclaw cron)
- **渠道校验**: 微信推送必须使用 `--channel "openclaw-weixin"`，严禁简写为 `weixin`。
- **推送目标**: 使用 `--announce` 模式时，必须强制包含 `--to "ID@im.wechat"` 参数。
- **时区设定**: 默认使用 `--tz "Asia/Shanghai"`。

### 2. 消息推送
- **飞书**: 消息格式优先使用 `post` (富文本)，以便于排版。
- **企业微信**: 仅限发送重要告警和自动化脚本通知。

### 3. 记忆维护 (memory_manager.py)
- 每次会话结束或产生重大决策后，应主动调用或记录，确保双层记忆同步。