Smart Search - 统一智能搜索

重要说明: 本技能仅支持 CLI 方式调用，不提供 HTTP API。

快速开始

1. 安装依赖

点击技能卡片上的 Install 按钮，或手动运行：

CODEBLOCK0

2. 配置 API Key

方式一：使用配置向导（推荐）

CODEBLOCK1

交互式输入 API Key，会自动加密存储到 ~/.openclaw/secrets/smart-search.json.enc。

方式二：逐个配置

CODEBLOCK2

方式三：从文件导入

创建 api-keys.json：
CODEBLOCK3

然后运行：
CODEBLOCK4

3. 测试搜索

CODEBLOCK5

CLI 使用方式

基本搜索

CODEBLOCK6

带参数搜索

CODEBLOCK7

参数说明

参数	说明	默认值
INLINECODE2	返回结果数量	10
INLINECODE3

语言偏好 | auto | | --intent=<type> | 搜索意图 | general | | --timeout=<ms> | 超时时间 | 5000 |

intent 可选值:

• - general - 通用搜索
• INLINECODE7 - 学术搜索（优先 Exa）
• INLINECODE8 - 技术搜索（优先 Exa）
• INLINECODE9 - 新闻搜索（优先 Tavily）

API Key 管理

配置向导

CODEBLOCK8

交互式配置所有引擎。

查看状态

CODEBLOCK9

显示所有引擎的配置状态和配额使用情况。

添加引擎

CODEBLOCK10

轮换 Key

CODEBLOCK11

支持的搜索引擎

所有 5 个搜索引擎均已完整实现：

引擎	状态	免费额度	用途	配置命令
百炼 MCP	✅ 已实现	2000 次/月	中文搜索	INLINECODE10
Tavily

✅ 已实现 | 1000 次/月 | 高级搜索 | npm run key:set tavily |
| Serper | ✅ 已实现 | 2500 次/月 | Google 结果 | npm run key:set serper |
| Exa | ✅ 已实现 | 1000 次/月 | 学术/技术搜索 | npm run key:set exa |
| Firecrawl | ✅ 已实现 | 500 页/月 | 网页抓取 | npm run key:set firecrawl |

总计: 约 7500 次/月搜索额度 🔍

智能路由策略

• - 中文查询 → 百炼（中文优化）
• 英文查询 → Serper（Google 结果）
• 学术意图 → 添加 Exa
• 技术意图 → 添加 Exa
• 新闻意图 → 添加 Tavily
• 自动降级 → 引擎失败时自动切换备用引擎

技术细节

• - 加密: AES-256-GCM
• 文件位置: INLINECODE15
• 文件权限: 0o600（仅所有者可读写）
• 密钥派生: PBKDF2（10 万轮迭代）

故障排查

查看所有引擎状态

CODEBLOCK12

测试单个引擎

CODEBLOCK13

重新配置

CODEBLOCK14

---

🔑 密钥管理

主密钥配置

Smart Search 使用 AES-256-GCM 加密存储 API Keys，需要配置主密钥。

方式一：环境变量（推荐）

CODEBLOCK15

或在 .env 文件中配置：

CODEBLOCK16

方式二：.env 文件

CODEBLOCK17

⚠️ 安全要求：

• - 主密钥至少 32 个字符
• 使用随机生成的密钥，不要使用密码或短语
• 不要将 .env 文件提交到版本控制
• 生产环境应使用密钥管理服务

密钥轮换

定期轮换 API Key 以增强安全性：

CODEBLOCK18

加密技术细节

项目	说明
加密算法	AES-256-GCM
密钥派生

PBKDF2-SHA256 | | 迭代次数 | 100,000 轮 | | 盐值 | 随机生成 16 字节盐，与加密配置一起存储 | | 存储位置 | ~/.openclaw/secrets/smart-search.json.enc | | 文件权限 | 0o600（仅所有者可读写） |

---

🔐 安全性

数据安全

• - API Key 存储: 使用 AES-256-GCM 加密存储
• 文件权限: 配置文件权限为 0o600（仅所有者可读写）
• 无日志记录: API Key 不会记录到日志中
• 隐私保护: API Key 本地加密存储，搜索请求直接发送到各搜索引擎官方 API

输入验证

• - 命令注入防护: 所有用户输入经过严格验证和转义
• 长度限制: 搜索关键词最大长度 500 字符
• 特殊字符过滤: 自动过滤危险字符（;, &, |, ` `, $, 等） - **类型验证**: 所有参数经过类型检查 ### 最佳实践 1. ✅ 定期轮换 API Key 2. ✅ 使用环境变量存储 Master Key 3. ✅ 不要分享加密配置文件 4. ✅ 在受信任的环境中运行 5. ✅ 定期更新依赖包 ### 审计 - **访问日志**: 记录所有 API Key 的访问（不记录 Key 本身） - **错误日志**: 记录错误但不包含敏感信息 - **可配置**: 可以禁用日志记录 --- ## 🔐 安全说明 ### 主密钥（OPENCLAW_MASTER_KEY） **要求**： - ✅ 至少 32 字符 - ✅ 使用强随机字符串 - ✅ 通过环境变量设置 - ✅ 不要提交到版本控制 **设置方法**： CODEBLOCK19 **生成安全的主密钥**： CODEBLOCK20 **安全警告**： - ⚠️ 不要在终端打印密钥 - ⚠️ 不要提交到 Git - ⚠️ 不要分享给他人 - ⚠️ 定期轮换密钥 ### 密钥管理实现 **加密算法**： - AES-256-GCM（认证加密） - PBKDF2 密钥派生（10 万轮迭代） - 随机盐（16 字节，每次加密都不同） **密钥生命周期**： 1. 主密钥通过环境变量提供 2. 使用 PBKDF2 派生加密密钥 3. 随机盐与加密数据一起存储 4. API Key 加密存储在 ~/.openclaw/secrets/smart-search.json.enc 5. 文件权限：0o600（仅所有者可读写） **代码位置**： - 密钥管理：src/key-manager.ts - 输入验证：src/utils/sanitize.ts - 安全执行：src/engines/bailian.ts（使用 spawn，shell: false） ### 安全最佳实践 1. ✅ 定期轮换 API Key 2. ✅ 使用环境变量存储 Master Key 3. ✅ 不要分享加密配置文件 4. ✅ 在受信任的环境中运行 5. ✅ 定期更新依赖包 6. ✅ 在权限有限的用户账户中运行 7. ✅ 检查依赖：npm audit 8. ✅ 运行测试：npm test ### 安全审计 **已完成的修复**： - ✅ Shell 注入修复（v1.0.3）- 使用 spawn 替代 exec - ✅ 输入验证增强（v1.0.3）- 白名单 + 注入检测 - ✅ 密钥管理完善（v1.0.3）- 环境变量 + 加密 - ✅ 随机盐生成（v1.0.3）- 每次加密都使用新盐 - ✅ 自动加载 .env（v1.0.11）- 不需要手动 source **ClawHub 安全扫描**： - ✅ 无硬编码密钥 - ✅ 无恶意网络调用 - ✅ 依赖包安全 - ✅ 代码符合声明的目的 ### Shell 命令执行安全说明 **静态分析警告说明**： ClawHub 静态分析工具检测到代码中使用 child_process，但这**不是安全问题**： **安全实践**： CODEBLOCK21 **代码位置**： - src/engines/bailian.ts - 使用 spawn() + shell: false - scripts/doctor.ts - 使用 spawnSync() 检查依赖 - scripts/setup-bailian.ts - 使用 spawnSync() 检查配置 **为什么安全**： 1. ✅ 使用 spawn() 而非exec() 2. ✅ 参数作为数组传递，不经过 shell 解析 3. ✅ 设置 shell: false 明确禁用 shell 4. ✅ 所有输入经过 validateSearchQuery()` 验证

1. 5. ✅ 无用户输入直接传递给 shell

参考：

• - Node.js 安全最佳实践：https://nodejs.org/en/docs/guides/security/#child-processes
• OWASP 命令注入防护：https://cheatsheetseries.owasp.org/cheatsheets/InjectionPreventionCheat_Sheet.html

故障排查

问题: "Salt not found in config file"

原因: v1.0.3 的安全修复使用随机盐，旧配置文件不兼容

解决方案:
CODEBLOCK22

问题: "OPENCLAWMASTERKEY environment variable is required"

原因: 未设置主密钥环境变量

解决方案:
CODEBLOCK23