TOOLS.md标准模板

2026-04-04 17:22:30 +08:00
parent d5e698f2c6
commit e618298e28
8 changed files with 658 additions and 224 deletions
--- a/openclaw/Agents/TOOLS.md
+++ b/openclaw/Agents/TOOLS.md
@@ -0,0 +1,609 @@
+```table-of-contents
+```
+
+# TOOLS管理
+
+## 1.统一SSH管理
+
+- **所有服务器**: 包括macmini、ubuntu1、ubuntu2、NAS
+
+- **管理方式**: 通过SSH统一管理，不存储sudo密码
+
+- **权限原则**: 遵循最小权限原则
+
+  
+
+## 2.管理流程
+
+1. 所有服务器操作都通过SSH进行
+
+2. 不存储任何服务器的sudo密码
+
+3. 需要sudo权限的操作通过SSH执行
+
+4. 保持所有服务器的管理方式一致
+
+  
+  
+
+## 3.文件编辑注意事项
+
+- **所有重要文件**: 使用 `exec + echo` 追加内容，避免 edit 工具在文件末尾无换行时失败
+
+- **edit工具使用准则**: edit依赖精确文本匹配，任何空白字符差异都会导致失败。建议：先 read 文件确认内容，用 write 重写整个文件更可靠（特别是 memory、SOUL、IDENTITY 等重要文件）
+
+  
+
+## 4.FRP (frpc 客户端) 管理
+
+### 安装目录
+
+  
+
+| 服务器     | FRP目录                             |
+| ------- | --------------------------------- |
+| macmini | /opt/frp/frp_0.65.0_darwin_arm64  |
+| ubuntu1 | /opt/frp/frp_0.65.0_linux_amd64   |
+| ubuntu2 | /opt/frp/frp_0.65.0_linux_amd64   |
+
+  
+
+### 配置文件
+
+- **文件名**: `frpc.toml`（在FRP目录下）
+
+- **作用**: 定义所有通过frp反向代理的应用及端口映射 (localPort ↔ remotePort)
+
+  
+
+### Mac Mini 管理方式（launchd）
+
+  
+
+**启动方式**: launchd plist（`KeepAlive: true`，崩溃自动重启）
+
+  
+
+**plist 位置**: `~/Library/LaunchAgents/com.homebrew.frpc.plist`
+
+  
+
+**管理命令**:
+
+```bash
+
+# 重启
+
+launchctl unload ~/Library/LaunchAgents/com.homebrew.frpc.plist && launchctl load ~/Library/LaunchAgents/com.homebrew.frpc.plist
+
+  
+
+# 停止（KeepAlive 会自动重启，需先 unload）
+
+launchctl unload ~/Library/LaunchAgents/com.homebrew.frpc.plist
+
+  
+
+# 查看状态
+
+launchctl list | grep frpc
+
+  
+
+# 查看日志
+
+tail -f /opt/frp/frp_0.65.0_darwin_arm64/frpc.log
+
+```
+
+  
+
+**正常状态标志**: 日志中显示 `[name] start proxy success`
+
+  
+
+### Ubuntu1/2 管理方式（systemd --user）
+
+```bash
+
+ssh ubuntu1 'systemctl --user restart frpc'
+
+ssh ubuntu2 'systemctl --user restart frpc'
+
+ssh ubuntu1 'systemctl --user status frpc'
+
+ssh ubuntu2 'systemctl --user status frpc'
+
+```
+
+不需要密码，开机自启（linger 已启用）
+
+  
+
+### 查看配置
+
+```bash
+
+# 读取frpc.toml了解端口映射
+
+cat /opt/frp/frp_0.65.0_xxx/frpc.toml
+
+```
+
+  
+
+## 5.FRP端口映射查询格式 (2026-03-14)
+
+  
+
+用户会这样提问:
+
+- "ubuntu1上frp的列表"
+
+- "macmini的frp配置"
+
+- "查看ubuntu2的frpc.toml"
+
+格式: 扫描frpc.toml文件，列出proxies相关配置
+
+输出格式: 表格 (名称 | 类型 | localPort | remotePort)
+
+  
+
+查询示例: ssh到对应服务器 -> cat /opt/frp/frp_0.65.0_xxx/frpc.toml
+
+  
+
+## 6.FRP状态检查 (2026-04-04)
+
+用户可能说: "检查frp状态"
+
+**检查方法**:
+
+1. 如果是macmini服务器：
+
+   - `launchctl list | grep frpc` 查看进程状态
+
+   - `tail /opt/frp/frp_0.65.0_darwin_arm64/frpc.log` 查看代理启动情况
+
+2. 如果是ubuntu服务器：
+
+   - `systemctl --user status frpc`
+
+  
+
+**正常状态标志**:
+
+- 所有 proxy 启动成功时会显示: `[xxx] [name] start proxy success`
+
+- 例如: `2026-04-04 16:43:01.276 [I] [client/control.go:172] [1a254958e6553119] [macmini-ssh] start proxy success`
+
+  
+
+**重启命令** (如果需要):
+
+1. 如果是macmini服务器：
+
+```bash
+
+launchctl unload ~/Library/LaunchAgents/com.homebrew.frpc.plist && launchctl load ~/Library/LaunchAgents/com.homebrew.frpc.plist
+
+```
+
+2. 如果是ubuntu服务器：
+
+```bash
+
+systemctl --user restart frpc
+
+```
+
+  
+
+## 7.VPS2 (x-UI 科学上网)
+
+- **IP**: 104.194.92.188
+
+- **SSH**: `ssh vps2`
+
+- **管理命令**: `x-ui`
+
+- **用途**: x-UI 面板管理，用于科学上网
+
+- 结果展示用列表方式，方便阅读
+
+  
+  
+
+## 8.网络测试策略 (2026-03-15)
+
+用户可能说: "网络测试"、"检查服务器科学上网"
+
+**测试项目**:
+
+1. 国内直连baidu (https://www.baidu.com)
+
+2. 国外直连 Google (https://www.google.com)
+
+3. 国外通过代理访问 Google (socks5://127.0.0.1:10808)
+
+  
+
+**测试命令模板**:
+
+**国内访问直连**
+
+```
+
+curl -v https://www.baidu.com
+
+```
+
+  
+
+**国外访问直连**
+
+```
+
+curl -v https://www.google.com
+
+```
+
+  
+
+**国外访问通过代理连**
+
+这是最快、最直接的方法。我们可以强制 `curl` 使用 SOCKS5 代理去访问 Google 的状态页。
+
+**执行命令：**
+
+```
+
+curl -x socks5h://127.0.0.1:10808 -v https://www.google.com
+
+```
+
+- **参数解释：**
+
+    - `-x socks5h://`：指定使用 SOCKS5 代理。注意加个 `h`，这表示让代理服务器去解析域名（防止本地 DNS 污染导致测试失败）。
+
+    - `-v`：(Verbose) 显示详细连接过程。
+
+- **判断标准：**    
+
+    - 如果看到 `HTTP/2 200` 或者大量的 HTML 文本，说明**代理成功**。
+
+    - 如果显示 `Connection refused` 或 `Timeout`，说明**端口未开放或 V2Ray 未运行**。
+
+  
+
+**服务器列表与代理端口**:
+
+  
+
+| 服务器 | IP | 代理端口 | 备注 |
+
+|--------|-----|---------|------|
+
+| MacMini | 192.168.3.189 | 10808 | V2RayN |
+
+| Ubuntu1 | 192.168.3.47 | 10808 | 需SSH后测试 |
+
+| Ubuntu2 | 192.168.3.45 | 10808 | 需SSH后测试 |
+
+| NAS | 192.168.3.17 | 20170 | 仅监听127.0.0.1 |
+
+| VPS1 | 192.227.222.142 | - | 直连正常 |
+
+| VPS2 | 104.194.92.188 | - | 直连正常 |
+
+  
+
+**输出格式**: 列表方式，方便阅读
+
+  
+
+**网络测试输出格式**
+
+用户要求格式示例:
+
+• 服务器名
+
+  • 国内访问直连: ✅/❌
+
+  • 国外访问直连: ✅/❌
+
+  • 国外访问通过代理XXX连: ✅/❌
+
+  
+
+## 9.OpenClaw 命令路径 (2026-03-27)
+
+  
+
+| 服务器      | OpenClaw 路径                              |
+
+| -------- | ---------------------------------------- |
+
+| Mac mini | `/opt/homebrew/bin/openclaw`             |
+
+| Ubuntu1  | `/home/shenwei/.npm-global/bin/openclaw` |
+
+| Ubuntu2  | `/home/shenwei/.npm-global/bin/openclaw` |
+
+  
+
+## 10.NAS Docker 代理配置 (2026-03-27)
+
+- **配置文件**: `/etc/systemd/system/pkg-ContainerManager-dockerd.service.d/http-proxy.conf`
+
+- **用途**: Synology NAS 上 Docker 守护进程的代理设置
+
+- **修改后需执行**: `sudo systemctl daemon-reload && sudo systemctl restart docker`
+
+  
+
+## 11.sag (TTS 语音生成) (2026-03-27)
+
+### 安装
+
+```bash
+
+brew install steipete/tap/sag
+
+```
+
+  
+
+### API Key 配置
+
+- 位置: `~/.openclaw/.env`
+
+- 环境变量: `ELEVENLABS_API_KEY`
+
+### 生成语音并发送到 Telegram
+
+```bash
+
+# 1. 生成 MP3 文件
+
+source ~/.openclaw/.env
+
+sag --api-key "$ELEVENLABS_API_KEY" -o /tmp/voice.mp3 "要转换的文字"
+
+  
+
+# 2. 发送到 Telegram (voice note)
+
+message --account <telegram bot> --chatId <user_id> --filePath /tmp/voice.mp3 --message "文字" --buttons []
+
+```
+
+### 使用规则
+
+- 所有用 sag 生成的语音都必须通过 Telegram voice note 发送给我
+
+- 使用 当前agent对应的telegram bot 账号发送
+
+- 文件临时保存在 /tmp/ 目录
+
+  
+
+### OpenCode
+
+- **路径**: `/Users/weishen/.opencode/bin/opencode`
+
+- **版本**: 1.2.27
+
+- **用法**: 开发任务必须通过它执行
+
+  
+  
+
+## 12.OpenClaw Gateway 重启步骤
+
+  
+
+### Mac Mini (2026-03-30 新方法)
+
+使用 `launchctl` 管理 OpenClaw Gateway 服务：
+
+`launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist && launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist`
+
+  
+  
+
+### Ubuntu1/2 服务器 (2026-03-28)
+
+#### 完整操作流程
+
+  
+
+**1. SSH 登录并重启**
+
+```bash
+
+ssh ubuntu1 'systemctl --user restart openclaw-gateway'
+
+ssh ubuntu2 'systemctl --user restart openclaw-gateway'
+
+```
+
+  
+
+**2. 查看启动状态**
+
+```bash
+
+ssh ubuntu1 'systemctl --user status openclaw-gateway'
+
+ssh ubuntu2 'systemctl --user status openclaw-gateway'
+
+```
+
+  
+
+**3. 检查 OpenClaw 健康状态**
+
+```bash
+
+ssh ubuntu1 '/home/shenwei/.npm-global/bin/openclaw status'
+
+ssh ubuntu2 '/home/shenwei/.npm-global/bin/openclaw status'
+
+```
+
+  
+
+### 快捷命令组合 (单行执行)
+
+```bash
+
+# Ubuntu1
+
+ssh ubuntu1 'systemctl --user restart openclaw-gateway && systemctl --user status openclaw-gateway && /home/shenwei/.npm-global/bin/openclaw status'
+
+  
+
+# Ubuntu2
+
+ssh ubuntu2 'systemctl --user restart openclaw-gateway && systemctl --user status openclaw-gateway && /home/shenwei/.npm-global/bin/openclaw status'
+
+```
+
+  
+
+## 13.AgentMail (邮件收发与自动化) (2026-04-04 更新)
+
+  
+
+### 📂 技能目录
+
+```
+
+~/.openclaw/skills/agentmail/
+
+├── scripts/           # 可直接使用的 Python 脚本
+
+│   ├── check_inbox.py   # 查看收件箱
+
+│   ├── send_email.py    # 发送邮件
+
+│   └── setup_webhook.py # 配置 Webhook
+
+└── references/       # 参考文档
+
+    ├── API.md         # API 完整文档
+
+    ├── EXAMPLES.md    # 使用示例
+
+    └── WEBHOOKS.md   # Webhook 配置指南
+
+```
+
+  
+
+### 快速使用
+
+  
+
+#### 查看收件箱
+
+```bash
+
+unset HTTP_PROXY && unset HTTPS_PROXY && unset http_proxy && unset https_proxy
+
+python3 ~/.openclaw/skills/agentmail/scripts/check_inbox.py --inbox star-agent@agentmail.to --limit 10
+
+```
+
+  
+
+#### 发送邮件
+
+```bash
+
+python3 ~/.openclaw/skills/agentmail/scripts/send_email.py \
+
+  --inbox star-agent@agentmail.to \
+
+  --to "recipient@example.com" \
+
+  --subject "主题" \
+
+  --text "正文内容"
+
+```
+
+  
+
+### API Key 配置
+
+- 位置: `~/.openclaw/.env`
+
+- 环境变量: `AGENTMAIL_API_KEY=your_key_here`
+
+  
+
+### 附件处理
+
+附件需要用 Python 代码下载，参考：
+
+```bash
+
+cat ~/.openclaw/skills/agentmail/references/API.md
+
+cat ~/.openclaw/skills/agentmail/references/EXAMPLES.md
+
+```
+
+  
+
+### ⚠️ 注意事项
+
+- **代理问题**：遇到 SOCKS 代理错误时，先 `unset HTTP_PROXY && unset HTTPS_PROXY`
+
+- **临时文件存放**：下载的附件和临时脚本请放在 `~/.openclaw/temp/<agentId>/` 目录，不要放在 workspace 下
+
+- **参考文档**：详细用法见 `references/API.md` 和 `references/EXAMPLES.md`
+
+  
+  
+
+## 14.Docker命令路径 (2026-04-04)
+
+| 服务器 | 命令 | 说明 |
+
+|--------|------|------|
+
+| macmini | `docker` | 直接可用（已在 PATH） |
+
+| macmini (SSH) | `/Applications/Docker.app/Contents/Resources/bin/docker` | SSH 时用完整路径 |
+
+| ubuntu1/2 | `docker` | 直接可用 |
+
+  
+
+**使用方式**:
+
+```bash
+
+# macmini 本地
+
+docker ps
+
+  
+
+# macmini SSH
+
+ssh macmini '/Applications/Docker.app/Contents/Resources/bin/docker ps'
+
+  
+
+# ubuntu1/2 SSH
+
+ssh ubuntu1 'docker ps'
+
+ssh ubuntu2 'docker ps'
+
+```
--- a/openclaw/Agents/TOOLs.md
+++ b/openclaw/Agents/TOOLs.md
@@ -1,89 +0,0 @@
-# TOOLS.md - Local Notes
-
-  
-
-## 笔记路径
-
-  
-
- **Obsidian 笔记目录**: /Users/weishen/Workspace/nexus
-
- **xinghui 专用笔记**: /Users/weishen/Workspace/nexus/openclaw/xinghui
-
-  
-
-Skills define _how_ tools work. This file is for _your_ specifics — the stuff that's unique to your setup.
-
-  
-
-## What Goes Here
-
-  
-
-Things like:
-
-  
-
- Camera names and locations
-
- SSH hosts and aliases
-
- Preferred voices for TTS
-
- Speaker/room names
-
- Device nicknames
-
- Anything environment-specific
-
-  
-
-## Examples
-
-  
-
-```markdown
-
-### Cameras
-
-  
-
- living-room → Main area, 180° wide angle
-
- front-door → Entrance, motion-triggered
-
-  
-
-### SSH
-
-  
-
- home-server → 192.168.1.100, user: admin
-
-  
-
-### TTS
-
-  
-
- Preferred voice: "Nova" (warm, slightly British)
-
- Default speaker: Kitchen HomePod
-
-```
-
-  
-
-## Why Separate?
-
-  
-
-Skills are shared. Your setup is yours. Keeping them apart means you can update skills without losing your notes, and share skills without leaking your infrastructure.
-
-  
-
---
-
-  
-
-Add whatever helps you do your job. This is your cheat sheet.