OpenHuman Skill Setup Agent 深度解析：从社区技能发现、安装到安全审批的完整实战指南

导读

Skill Setup Agent 是 OpenHuman 内置的一名"技能管理专员"：它负责在 OpenHuman Community、HermesHub 与 ClawHub 三大社区技能仓库之间检索、浏览、安装、列出与卸载 Agent 技能（Skill），并以内联审批卡片的形式让用户在对话中直接确认安装。阅读本文后，你将掌握 Skill Setup Agent 的完整角色定义、三大技能来源与检索策略、端到端安装工作流，以及它背后由 ApprovalGate 审批网关、SSRF 防护与原子写入构成的技能安装安全机制，并能直接使用仓库中的 CLI 命令和 Agent 配置复现整套流程。

---

一、Skill Setup Agent 是什么

Skill Setup Agent 是 OpenHuman 内置（built-in）的子代理（worker agent），专门承担技能发现、安装与生命周期管理职责。其系统提示词位于 prompt.md，核心定位是：

一名从社区仓库中发现、安装并管理 Agent 技能的专家（specialist in discovering, installing, and managing agent skills from community registries）。

它是一个"专职代理"，意味着当用户需要查找、安装、更新或移除技能时，编排代理（orchestrator）会将任务委派给它，而不是让主代理自己处理——这正是 agent.toml 中 delegate_name = "setup_skills" 与 when_to_use 描述的含义：

id = "skill_setup"
display_name = "Skill Setup Agent"
delegate_name = "setup_skills"
when_to_use = "Skill discovery and installation specialist — browses community skill registries (OpenHuman, HermesHub, ClawHub), searches for skills by keyword or category, installs skills from remote sources, and manages installed skills. Use when the user wants to find, install, update, or remove agent skills."

该 Agent 在 catalog/agent/mod.rs 中被声明为 skill_setup 模块，其提示词构建器位于 prompt.rs：ARCHETYPE 常量通过 include_str!("prompt.md") 把提示词原文件嵌入二进制，然后在运行时依次拼接用户文件上下文（render_user_files）、可用工具列表（render_tools）、安全前言（render_safety）与工作区上下文（render_workspace），最终组成发给模型的实际系统提示词。这意味着 prompt.md 只是"骨架"，最终生效的提示词会随当前会话上下文动态扩展。

关键运行参数

agent.toml 中除身份信息外还定义了以下运行时行为，理解这些参数有助于判断该 Agent 在真实会话中的行为边界：

配置项	值	含义
temperature	0.3	较低采样温度，让技能安装这类对确定性要求高的任务尽量输出稳定结果
max_iterations	10	单个任务最多允许 10 轮工具调用循环，防止在检索/安装上无限空转
sandbox_mode	none	不启用沙箱执行（技能安装本身由审批网关与路径校验保护）
agent_tier	worker	属于"工人"层级，接受编排代理的委派执行具体任务
omit_identity	true	不注入主代理身份信息，保持专职代理的独立角色
omit_memory_context	true	不注入长期记忆上下文，专注技能目录检索
omit_safety_preamble	false	仍保留安全前言
[model] hint	chat	模型提示偏好 chat 型交互

该 Agent 被授予的命名工具（named tools）包括：

[tools]
named = [
    "list_workflows",
    "describe_workflow",
    "skill_registry_browse",
    "skill_registry_search",
    "skill_registry_sources",
    "skill_registry_install",
    "skill_registry_uninstall",
    "install_workflow_from_url",
    "uninstall_workflow",
    "ask_user_clarification",
]

二、三大技能来源（Registry）

Skill Setup Agent 从三个社区仓库发现技能：

1. OpenHuman Community — OpenHuman 官方精选技能，托管于 tinyhumansai/skill-registry；
2. HermesHub — Hermes 生态的社区技能（内置 built-in 与可选 optional 两类）；
3. ClawHub — OpenClaw 技能市场，提示词中标注其规模为 13,000+ 技能。

从源码实现看，这三个来源并不需要分别请求三个接口。 ops.rs 的注释明确指出：目录数据来自 HermesHub 聚合 JSON API 单端点，该端点同时聚合了 HermesHub（built-in + optional）、ClawHub、skills.sh、LobeHub 与 browse.sh 的技能条目。默认目录地址为：

https://hermes-agent.nousresearch.com/docs/api/skills.json

也就是说，Skill Setup Agent 提示词中列出的"三大注册表"最终通过一个聚合端点统一提供，而 tools.rs 中的 skill_registry_sources 工具会在运行时列出当前目录中实际存在的所有上游来源（如 built-in、ClawHub、skills.sh、LobeHub、browse.sh 等）。

目录条目的数据结构

每个目录条目（CatalogEntry，见 types.rs）包含以下字段：

• id：唯一 slug（如 apple-notes、docker-manager）；
• name：展示名称；
• description：简介；
• source：上游来源（built-in / optional / ClawHub / skills.sh / LobeHub / browse.sh）；
• category：分类标签；
• author / version / license：作者、版本与许可证（可选）；
• tags / platforms：用于检索的标签与平台提示；
• download_url：可直接下载 SKILL.md 的 URL（无直接下载时为空字符串）；
• source_url：人类可访问的来源页面（GitHub blob/tree、LobeHub、ClawHub 等）；
• docs_path：Hermes 目录中的文档路径；
• commands / env_vars：技能依赖的 CLI 命令与环境变量。

值得注意的实现细节：download_url 的推导遵循明确优先级（见 ops.rs）：

1. 优先使用 OPENHUMAN_SKILL_REGISTRY_DOWNLOAD_BASE_URL 环境变量覆盖（测试场景）；
2. 其次使用 docsPath（针对 Hermes 官方 bundled/optional 技能，映射到 NousResearch/hermes-agent 仓库的 skills/ 与 optional-skills/ 目录）；
3. 再次使用 sourceUrl：若指向 GitHub blob/tree 页面，则改写为 raw.githubusercontent.com 对应的 SKILL.md 地址；非 GitHub 的 portal 页（ClawHub/LobeHub/skills.sh 等）无法推导出直接下载地址。

对无法直接下载的 portal-only 社区技能，install_from_catalog 会返回可操作的错误信息（附上 source_url 供用户自行查看），而不是请求一个必然 404 的 URL——这一行为源于 issue #3741 的历史教训：早期实现把所有社区技能都强制模板化到 NousResearch/hermes-agent 路径上，导致几乎全部社区安装请求都 404。

三、六项核心能力

Skill Setup Agent 的系统提示词明确列出了六项能力：

• Browse：跨所有注册表浏览可用技能；
• Search：按关键词、分类或标签检索技能；
• Install：从远程 SKILL.md URL 安装技能；
• List：列出当前已安装技能；
• Uninstall：卸载不再需要的技能；
• Describe：详细描述已安装技能。

这些能力与 agent.toml 授予的工具一一对应，其中 skill_registry_* 系列工具由 tools.rs 实现，属于 LLM 可调用的技能注册表领域工具。各工具的关键语义如下：

skill_registry_browse

浏览聚合技能目录，返回全部技能及其元数据。支持 force_refresh 布尔参数（默认 false）：设为 true 时绕过缓存、强制从 Hermes API 重新拉取。该工具被标记为并发安全（is_concurrency_safe 返回 true）。

skill_registry_search

按关键词检索，匹配范围为技能名称、描述、标签、分类和作者，并可选地按 source 或 category 过滤：

{
  "query": "git",
  "source": "ClawHub",
  "category": "devops"
}

从 ops.rs 的实现看，query 会统一转小写后对 name、description、tags、category 与 author 做子串包含匹配，source 与 category 过滤器使用大小写不敏感的比较。重要的是，搜索/过滤读取永远不会使用过期缓存（走 browse_catalog_fresh 路径），以保证检索结果反映最新目录。

skill_registry_install

按 entry_id（slug）从目录安装技能：先从缓存目录中查找该条目，再调用 ops::install_from_catalog 下载 SKILL.md 并安装到本地。该工具的 permission_level 为 Write，且 external_effect 返回 true——这意味着它会经过全局 ApprovalGate 审批网关（详见第五节）。

安装成功后的返回结果包含：url（实际下载地址）、stdout、stderr 与 new_skills（本次新增的技能 slug 列表）。

skill_registry_sources

列出目录中存在的不同上游来源集合（built-in、ClawHub、skills.sh、LobeHub、browse.sh 等），无参数。底层实现（ops.rs）会浏览目录并按来源去重排序。

skill_registry_uninstall

按技能 slug 卸载已安装的**用户作用域（user-scope）**技能。底层复用 ops_install_part_01.rs 中的 uninstall_workflow：它只支持用户级卸载，会做路径规范化、拒绝符号链接、要求目标目录中存在 SKILL.md，并依次在 ~/.openhuman/workflows/、~/.openhuman/skills/ 与旧版 ~/.agents/skills/ 三个根目录中解析实际安装位置。返回 name、removed_path（实际删除的绝对路径）与 scope。

四、标准工作流：从检索到安装确认

系统提示词定义了一套清晰的端到端工作流，这是 Skill Setup Agent 在真实对话中必须遵守的交互协议：

1. 检索：当用户要求查找技能时，跨注册表执行搜索；
2. 呈现结果：清晰展示每个候选技能的名称、描述、来源注册表与安装数；
3. 确认选择：若多个技能匹配，询问用户希望安装哪一个（或哪几个）；
4. 安装并确认：安装所选技能并确认其已添加。安装会触发内联审批卡片（inline approval card），用户直接在聊天界面中批准即可——Agent 不会跳转到其他页面，也不会丢给用户一堆手动安装步骤；
5. 处理拒绝或失败：如果用户拒绝审批卡片，或安装失败，Agent 应当如实承认并建议替代方案。不得静默重试同一安装——一次被拒绝或失败就足够了。

这套"先检索 → 展示 → 询问 → 审批 → 一次性执行"的协议刻意避免了两类常见错误：一是绕过审批直接执行安装，二是在失败后反复重试同一操作造成骚扰。

从 Agent 架构角度看，这一工作流与 skill_registry_search → skill_registry_install → 审批卡片的调用链完全对应，并且 ask_user_clarification 工具的存在（见 agent.toml 的 [tools] 列表）保证了在多候选场景下 Agent 能主动向用户澄清意图。

五、安全机制：审批网关与安装防护

ApprovalGate：安装前的内联审批

提示词强调"安装会触发内联审批卡片"，其底层实现是 OpenHuman 的 ApprovalGate。根据 security/approval/README.md 的说明，ApprovalGate 是运行在 Agent 与任何 external_effect = true 工具之间的异步中间件（issue #1339）：它拦截工具调用、检查用户的 "Always allow" 允许列表、在 SQLite 中持久化一条 pending 记录、发布 ApprovalRequested 事件让 UI 弹出提示、将工具调用 future 挂起在 oneshot 通道上，等用户通过 UI（或聊天中键入 yes/no）经由 approval_decide RPC 作出决定后再继续执行。拒绝与超时（10 分钟 TTL）都会 fail-closed——即默认不执行。

tools.rs 的 SkillRegistryInstallTool 注释进一步揭示了细节（issue #3993）：

• 在交互式聊天会话中，用户会看到内联审批卡片，批准后才真正写入磁盘；
• 在后台/定时（cron）任务中（没有 APPROVAL_CHAT_CONTEXT 任务局部变量），审批网关会被绕过——这与所有其他外部副作用工具的行为保持一致。

测试 tools_tests.rs 明确断言了这一行为："#3993: installs must raise an inline approval card before writing."

ApprovalGate 的实现位于 security/approval/gate.rs，包含 init_global/try_global、intercept/intercept_audited、decide、list_pending、list_recent_decisions 等接口；当 ApprovalGate::try_global() 返回 None（未安装网关）时，工具/执行框架会把其视为"无审批"，与整个系统的行为约定一致。

安装管道的多层防护

技能安装走的是经过加固的 workflows URL 安装器（ops_install_part_01.rs 的 install_workflow_from_url）。仓库注释（catalog/README.md）明确指出：

Production installs still go through the hardened workflows URL installer.

该安装器内置了多层防护：

• URL 校验：安装前对 URL 进行校验与规范化；
• SSRF 第二层防护：即使 URL 主机名看起来是公网的，也会提前解析主机，若解析出的任何 IP 是回环/私网/链路本地地址则拒绝（DNS-to-private-IP 攻击面）；已知局限是未完全阻断 DNS rebinding（需要固定 SocketAddr 并传给 reqwest 自定义 resolver）；
• 超时控制：安装超时默认 60 秒（目录安装传参 timeout_secs: Some(60)），请求客户端按超时时间构建；
• 响应体限制与双重校验：下载前检查 Content-Length，下载完成后再次校验缓冲长度，防止撒谎的响应头；
• Frontmatter 校验：SKILL.md 的 frontmatter 必须包含 name 与 description（符合 agentskills.io 规范）；
• slug 派生与幂等：优先使用 metadata.id 作为 slug，否则取净化后的 name；目标目录已有 SKILL.md 时视为幂等成功；其他目录冲突则直接失败，绝不静默覆盖已有文件；
• 原子写入：先在目标目录写 SKILL.md.tmp，成功后再 rename 为最终文件；
• 安装后重发现：成功后重新发现整个技能目录，返回本次新增的技能 slug 列表；
• 本地 HTTP 限制：仅当设置 OPENHUMAN_SKILL_INSTALL_ALLOW_LOCAL_HTTP=1 时允许从 localhost 安装，且仅用于本地测试夹具。

卸载的防御性处理

uninstall_workflow（ops_install_part_01.rs）同样有防御逻辑：拒绝包含路径分隔符（/、\）或 .. 的技能名、限制名称最大长度、解析真实主目录、规范化路径、拒绝符号链接、要求 SKILL.md 存在，并在三个历史根目录中按顺序解析实际位置。

六、目录缓存与启动刷新：底层性能设计

由于聚合目录包含数万条目（源码注释提及约 9 万条记录、单次下载约 80 秒），ops.rs 做了精细的缓存与并发设计，这些设计直接决定了 Skill Setup Agent 的响应体验：

• single-flight 锁（FETCH_LOCK）：同一时刻只允许一个目录拉取请求；React StrictMode 双调用、skills 浏览器挂载时的多次读取等并发请求会合并到同一次网络请求上，其余调用者复用刚落盘的缓存；
• fresh / stale 双状态缓存：新鲜缓存直接返回；过期缓存（browse 场景）立即返回旧数据并后台单次 revalidate（stale-while-revalidate，速度优先）；搜索/过滤场景拒绝过期数据，回落到 fresh 拉取（准确性优先）；
• 启动后台刷新：核心启动时通过 start_boot_catalog_refresh 异步强制刷新目录，不阻塞核心就绪；可用 OPENHUMAN_SKILL_REGISTRY_REFRESH_ON_BOOT=0 关闭（支持 0/false/no/off 等取值）。

环境变量速查

环境变量	作用
OPENHUMAN_SKILL_REGISTRY_CATALOG_URL	覆盖目录 JSON 端点地址（默认 HermesHub 聚合 API）
OPENHUMAN_SKILL_REGISTRY_DOWNLOAD_BASE_URL	覆盖技能下载基址（测试场景，模板为 {base}/{name}/SKILL.md）
OPENHUMAN_SKILL_REGISTRY_REFRESH_ON_BOOT	设为 0 关闭启动时的后台目录刷新
OPENHUMAN_SKILL_INSTALL_ALLOW_LOCAL_HTTP	设为 1 允许从 localhost HTTP 安装（仅限本地测试）

这些变量的具体读取与默认值逻辑可参见 ops.rs 与 ops_install_part_01.rs。

七、命令行快速上手

虽然日常使用中 Skill Setup Agent 通过对话完成技能管理，但技能注册表领域也提供了等价的 CLI 入口（见 catalog/README.md 的 production smoke 示例），便于脚本化与调试：

# 查看 skill_registry 域支持的子命令 schema
openhuman skill_registry schemas

# 浏览全部技能（--force_refresh true 绕过缓存强制拉取）
openhuman skill_registry browse --force_refresh true

# 按关键词搜索（如 git 相关技能）
openhuman skill_registry search --query git

# 列出目录中所有上游来源
openhuman skill_registry sources

# 按 entry_id 安装技能
openhuman skill_registry install --entry_id git-helper

# 卸载已安装技能（用户作用域）
openhuman skill_registry uninstall --name git-helper

八、重要规则速览

系统提示词的最后一部分是 Agent 必须遵守的硬性规则，无论是接入方集成还是使用者理解其行为边界都值得逐条关注：

1. 始终展示来源注册表：每个技能都要标明来自 OpenHuman、HermesHub 还是 ClawHub；
2. 警告未经验证的技能：社区技能可能未经安全审计，Agent 必须向用户提示风险；
3. 未经用户确认绝不安装：任何安装都必须经过用户确认（配合审批卡片）；
4. ClawHub 无直连安装时的替代方案：对无法直接安装的 ClawHub 技能，要解释 OpenClaw CLI 这一替代途径；
5. 列出已安装技能时标明作用域：区分 user 作用域与 project 作用域。

九、从源码到实践：如何把 Skill Setup Agent 接入你的会话

综合以上分析，Skill Setup Agent 的实际工作链路可以概括为：

用户请求 → orchestrator 委派(delegate_name=setup_skills)
        → skill_setup Agent（prompt.md 骨架 + 动态 tools/safety/workspace 上下文）
        → skill_registry_search（fresh 目录）→ 展示结果并 ask_user_clarification
        → skill_registry_install（ApprovalGate 内联审批卡 → 用户批准）
        → install_workflow_from_url（URL 校验 → SSRF 防护 → 下载 → frontmatter 校验 → 原子写入）
        → 重发现技能目录，返回 new_skills

想深入阅读源码的读者，推荐按以下路径继续探索：

• 系统提示词本体：prompt.md；
• Agent 配置与工具授权：agent.toml；
• 提示词动态构建器：prompt.rs；
• 注册表工具实现：tools.rs 与对应的单元测试 tools_tests.rs；
• 目录获取/缓存/搜索/安装业务逻辑：ops.rs 与 ops_tests.rs；
• 目录条目数据模型：types.rs；
• 加固的 URL 安装器与卸载实现：ops_install_part_01.rs；
• 审批网关机制：security/approval/README.md 与 security/approval/gate.rs。

结语

Skill Setup Agent 是 OpenHuman 技能生态的"前台导购"：它把三大社区注册表的数万技能统一到一次聚合检索中，用"搜索 → 展示 → 询问 → 审批 → 一次性执行"的克制工作流替代了粗暴的自动安装，同时由 ApprovalGate 审批网关与多层加固的 URL 安装器兜底安全底线。理解它的提示词、工具授权与底层实现，不仅有助于你高效地通过对话管理技能，也能为在自研 Agent 中设计"受审批约束的外部副作用工具"提供一份可参考的工程范式。