Openclaw Smart Search

统一智能搜索技能，整合多个搜索引擎（百炼 MCP、Tavily、Serper、Exa、Firecrawl），自动选择最佳引擎并融合结果

Security Scan

功能总体与“统一智能搜索”匹配, 但有几处不一致与隐含的密钥-handling 风险——在安装/配置主密钥和与 mcporter 交互方面需要额外审查。

Purpose & Capability

技能声明整合 5 个搜索引擎并使用 node + mcporter（用于百炼），代码包含多个引擎适配器和密钥管理模块 — 要求的二进制（node, mcporter）与描述匹配。异常点：注册表顶级元数据报告“Required env vars: none”，但 SKILL.md 和源码明确依赖 OPENCLAW_MASTER_KEY（用于加密密钥存储）。这种元数据不一致需要修正或说明。

Instruction Scope

SKILL.md 与脚本指导用户在本地生成并设置主密钥、将主密钥写入 .env（setup-wizard 将 .env 写入技能目录），并将 API Keys 加密存储到 ~/.openclaw/secrets/smart-search.json.enc。这些步骤本身与功能相关，但存在敏感操作（生成/写入主密钥、检测/读取 mcporter 配置路径、调用 mcporter 命令、写入本地加密文件）。尤其值得注意：setup-wizard 自动在技能目录写入 .env（可能暴露主密钥，取决于目录权限）；setup-bailian 会尝试读取 mcporter 的配置路径（包括 /etc 路径），这会访问其他工具的配置文件。总体上指令范围接近功能，但在密钥存储/位置和对系统路径的读取上存在风险点。

Install Mechanism

安装说明仅通过 npm 安装 TypeScript 运行时/依赖（typescript, ts-node, @types/node, dotenv），没有从不受信任的外部 URL 下载可执行文件。相对低风险且与 Node.js 项目一致。

Credentials

技能需要一个主密钥（OPENCLAW_MASTER_KEY）用于 AES-256-GCM 加密，这是合理的。但注册表元数据未列出该 env var while SKILL.md 和脚本都依赖它 — 元数据不一致会误导用户。脚本/指南鼓励将主密钥写入 .env 或 shell 启动脚本；setup-wizard 会在技能目录生成并写入 .env 文件（潜在明文存储），且没有明确在写入时设置严格权限。这让主密钥可能被意外暴露。技能也会读取/检测多个 API KEY 环境变量（BAILIAN_API_KEY 等），这种行为与其功能相关且可接受。

Persistence & Privilege

技能未请求 always: true，并且只在用户显式安装/运行时活动。它写入自己的加密配置文件到 ~/.openclaw/secrets 和技能目录的 .env，但没有证据显示它修改其他技能或系统范围的代理配置。

What to consider before installing

This skill mostly does what it claims (combines multiple search engines) but pay attention to key handling before installing: - Metadata mismatch: the registry summary claims no required env vars but SKILL.md and code require OPENCLAW_MASTER_KEY. Treat OPENCLAW_MASTER_KEY as required. - Inspect where the master key is stored: setup-wizard writes a .env inside the skill directory (./.env). That can expose the master key if the skill directory is not protected. Prefer to set OPENCLAW_MASTER_KEY in your user shell or a proper secret manager and do not leave .env in the repo. - Review src/key-manager.ts before trusting automatic setup: ensure encryption is implemented correctly and that no code transmits keys to external endpoints. Verify the encrypted file (~/.openclaw/secrets/smart-search.json.enc) is created with 0o600 and that the code does not print keys or upload them. - mcporter interaction: the Bailian setup will look for mcporter configs (including /etc paths) and will call mcporter. That is consistent with integrating Bailian but may read other local config files — only run if you expect mcporter integration. - Avoid running setup scripts that auto-generate and write keys until you confirm where they write them and with what permissions. If you run setup, afterwards check file permissions (chmod 600) and remove any stray .env or unencrypted key files. Recommended steps before installing: 1. Inspect src/key-manager.ts and setup scripts for any network calls that might send secrets off-host. 2. Set OPENCLAW_MASTER_KEY in your environment or a dedicated secret manager rather than relying on automatic .env writes. 3. After setup, verify ~/.openclaw/secrets/smart-search.json.enc exists and has 0o600 permissions. 4. If you don't use Bailian/mcporter, skip setup-bailian and only configure engines you trust. If anything seems unexpected, don't proceed and ask the maintainer to clarify the metadata and .env write behavior.

Smart Search - 统一智能搜索

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

快速开始

1. 安装依赖

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

cd ~/.agents/skills/smart-search
npm install

2. 配置 API Key

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

npm run setup

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

方式二：逐个配置

npm run key:set bailian
npm run key:set tavily
npm run key:set serper
npm run key:set exa
npm run key:set firecrawl

方式三：从文件导入

创建 api-keys.json：

{
  "bailian": "sk-xxx",
  "tavily": "tvly-xxx",
  "serper": "xxx",
  "exa": "xxx",
  "firecrawl": "fc-xxx"
}

然后运行：

npm run key:import ./api-keys.json

3. 测试搜索

npm run search "OpenClaw 新功能"

CLI 使用方式

基本搜索

# 在技能目录下执行
cd ~/.agents/skills/smart-search
npm run search "搜索内容"

带参数搜索

# 指定结果数量
npm run search "OpenClaw 新功能" -- --count=10

# 学术搜索（优先使用 Exa）
npm run search "LLM Agent planning" -- --intent=academic

# 技术搜索
npm run search "TypeScript 最佳实践" -- --intent=technical

# 新闻搜索
npm run search "最新 AI 动态" -- --intent=news

# 指定语言
npm run search "OpenClaw" -- --language=zh

参数说明

参数	说明	默认值
--count=<n>	返回结果数量	10
--language=<zh|en>	语言偏好	auto
--intent=<type>	搜索意图	general
--timeout=<ms>	超时时间	5000

intent 可选值:

• general - 通用搜索
• academic - 学术搜索（优先 Exa）
• technical - 技术搜索（优先 Exa）
• news - 新闻搜索（优先 Tavily）

API Key 管理

配置向导

npm run setup

交互式配置所有引擎。

查看状态

npm run key:status

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

添加引擎

npm run key:set exa

轮换 Key

npm run key:rotate bailian

支持的搜索引擎

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

引擎	状态	免费额度	用途	配置命令
百炼 MCP	✅ 已实现	2000 次/月	中文搜索	npm run key:set bailian
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
• 文件位置: ~/.openclaw/secrets/smart-search.json.enc
• 文件权限: 0o600（仅所有者可读写）
• 密钥派生: PBKDF2（10 万轮迭代）

故障排查

查看所有引擎状态

npm run key:status

测试单个引擎

npm run key:get bailian
npm run search "test"

重新配置

# 删除旧配置
rm ~/.openclaw/secrets/smart-search.json.enc

# 重新配置
npm run setup

---

🔑 密钥管理

主密钥配置

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

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

# 生成强随机密钥
openssl rand -base64 32

# 设置环境变量
export OPENCLAW_MASTER_KEY="your-generated-key-at-least-32-characters"

或在 .env 文件中配置：

OPENCLAW_MASTER_KEY=your-generated-key-at-least-32-characters

方式二：.env 文件

# 复制示例文件
cp .env.example .env

# 编辑配置
nano .env

⚠️ 安全要求：

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

密钥轮换

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

# 查看当前状态
npm run key:status

# 轮换指定引擎
npm run key:rotate bailian

# 完全重新配置
rm ~/.openclaw/secrets/smart-search.json.enc
npm run setup

加密技术细节

项目	说明
加密算法	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 字符
• ✅ 使用强随机字符串
• ✅ 通过环境变量设置
• ✅ 不要提交到版本控制

设置方法：

# Linux/macOS
export OPENCLAW_MASTER_KEY="your-32-char-secure-random-string-here"

# 或添加到 ~/.bashrc 或 ~/.zshrc（推荐）
echo 'export OPENCLAW_MASTER_KEY="your-key"' >> ~/.bashrc
source ~/.bashrc

# Windows PowerShell
$env:OPENCLAW_MASTER_KEY="your-32-char-secure-random-string-here"

# 或添加到 $PROFILE
echo '$env:OPENCLAW_MASTER_KEY="your-key"' >> $PROFILE

生成安全的主密钥：

# Linux/macOS
openssl rand -base64 32

# 或使用 Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

安全警告：

• ⚠️ 不要在终端打印密钥
• ⚠️ 不要提交到 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，但这不是安全问题：

安全实践：

// ✅ 安全：使用 spawn，参数作为数组传递
spawn('mcporter', ['call', 'WebSearch.bailian_web_search', `query=${query}`], {
  shell: false,  // 不通过 shell 执行
  stdio: ['pipe', 'pipe', 'pipe']
});

// ❌ 不安全：使用 exec，参数经过 shell 解析
exec(`mcporter call ... query="${query}"`);  // 有注入风险

代码位置：

• 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() 验证
5. ✅ 无用户输入直接传递给 shell

参考：

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

故障排查

问题: "Salt not found in config file"

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

解决方案:

# 删除旧配置文件
rm ~/.openclaw/secrets/smart-search.json.enc

# 重新配置
npm run setup

问题: "OPENCLAW_MASTER_KEY environment variable is required"

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

解决方案:

# 设置环境变量
export OPENCLAW_MASTER_KEY="your-32-char-secure-random-string"

# 或添加到 ~/.bashrc
echo 'export OPENCLAW_MASTER_KEY="your-key"' >> ~/.bashrc
source ~/.bashrc