企业官网建设流程全解析

OpenClaw Skills 实战：Gemini CLI 无头模式技能（SKILL.md）解析与 OpenClaw 技能加载机制

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

本文基于 OpenClaw 仓库中内置的skills/gemini/SKILL.md，系统讲解如何用 Gemini CLI 的无头（headless）一次性模式完成提问、摘要、JSON 生成与内容路由，并深入结合 OpenClaw 的技能加载源码，说明requires.bins门控、install安装规格、bundled 技能根目录发现等机制是如何把一个 SKILL.md 变成 Agent 可用的能力的。读完本文，你既能直接复制命令使用 Gemini CLI，也能理解 OpenClaw 是如何发现、校验并暴露这个技能的。

技能定位：Gemini CLI 无头一次性提示

skills/gemini/SKILL.md是一份"bundled skill"（随 OpenClaw 安装包一起发布的技能），其核心目标是：让 Agent 以无头一次性模式（headless one-shot mode）调用 Gemini，覆盖三类典型任务——一次性问答（one-shot prompts）、内容摘要（summaries）、结构化内容生成（generation），以及技能（skills）、钩子（hooks）、MCP 服务的管理，或将任务路由到 Gemma 系列模型。

技能的第一条关键约定是：

位置参数文本会进入交互模式；无头执行必须使用-p/--prompt。

也就是说，直接gemini "你好"会启动一个交互式会话，而脚本化、Agent 化的用法必须显式传入-p，确保进程执行完即退出，适合被 OpenClaw 的exec工具调用。

快速上手命令

原文档给出的 Quick start 全部命令如下，均可直接复制运行：

# 基础一次性提问 gemini -p "Answer this question..." # 指定模型 gemini -m <model> -p "Prompt..." # 要求返回 JSON（便于程序解析） gemini -p "Return JSON" --output-format json # stdin 内容会附加到 -p 提示之后 cat notes.md | gemini -p "Summarize"

几个使用要点：

• -m <model>用于在默认模型之外显式选择模型，这也是原文档描述中 "Gemma routing"（把请求路由到 Gemma 等模型）的落点；
• --output-format json使输出成为可解析的 JSON，Agent 侧可以稳定提取字段而不是解析自由文本；
• stdin 管道是摘要类任务的关键入口：cat notes.md | gemini -p "Summarize"中，管道内容会被追加到-p指定的提示之后，因此提示词只写任务指令、把待处理内容从标准输入喂入即可，避免长文本拼进命令行参数。

扩展管理命令族

Gemini CLI 自带一组子命令用于扩展能力，技能中要求 Agent 熟记这一命令族：

gemini --list-extensions # 列出已安装的扩展 gemini extensions <command> # 管理扩展 gemini skills <command> # 管理 Gemini 侧的技能 gemini hooks <command> # 管理钩子 gemini mcp <command> # 管理 MCP 服务

这里要区分两个层面的"skill"：Gemini CLI 自己的gemini skills是它内置的技能机制；而本文档所在的skills/gemini/是OpenClaw 的技能，用于教会 OpenClaw 的 Agent 如何驱动 Gemini CLI 这个外部工具。两者名称相同但职责不同——OpenClaw 技能是"操作手册"，Gemini 技能是"CLI 自身能力"。

前置条件：依赖门控与安装规格

SKILL.md的 YAML frontmatter 不只是描述文字，它被 OpenClaw 的技能加载器解析为机器可执行的元数据：

--- name: gemini description: "Gemini CLI one-shot prompts, summaries, generation, skills, hooks, MCP, or Gemma routing." homepage: https://ai.google.dev/ metadata: openclaw: emoji: "✨" requires: { "bins": ["gemini"] } install: - id: brew kind: brew formula: gemini-cli bins: ["gemini"] label: "Install Gemini CLI (brew)" ---

requires.bins：二进制存在性门控

requires: { "bins": ["gemini"] }声明了这个技能的前置条件：系统 PATH 中必须存在gemini可执行文件。从源码结构看，技能在加载时会根据环境、配置和二进制存在性进行过滤（见 Skills 总览 中 "filters them at load time based on environment, config, and binary presence" 的说明）。这意味着：

• 未安装 Gemini CLI 的机器上，该技能不会进入 Agent 的可用技能列表，Agent 也就不会去尝试调用不存在的命令；
• 安装gemini之后，技能自动变为可用，无需改任何 OpenClaw 配置。

install 规格：可执行的安装声明

metadata.openclaw.install数组中声明了一个kind: brew的安装项，formula: gemini-cli。加载器对安装规格有严格的白名单式校验——从 frontmatter.ts 的parseInstallSpec可以看到：

• 支持的kind限定为brew、node、go、uv、download五种（parseInstallSpec）；
• brew 公式必须通过normalizeSafeBrewFormula的安全模式校验（不允许以-开头、不允许\\和..），公式gemini-cli通过BREW_FORMULA_PATTERN正则（L34）；
• kind === "brew"时若没有formula则整个规格被丢弃（L184-L186），所以formula: gemini-cli是这个安装项有效的关键；
• bins字段则用于安装完成后的验证：安装成功的判据是gemini出现在 PATH 中，与requires.bins形成闭环。

这一机制让"缺依赖 → 声明安装方式 → 安装 → 门控通过 → 技能激活"成为一条数据驱动的链路，技能作者只需要在 frontmatter 里声明，而不需要编写安装脚本。

认证与安全注意事项

原文档 Notes 部分给出两条必须遵守的运行时约定：

1. 认证：如果需要登录，先交互式运行一次gemini并按登录流程完成授权，之后再使用-p无头模式。因为 OAuth 等登录流程需要浏览器交互，无法在无头进程中完成；
2. 安全：避免使用--yolo参数。该参数会放开 Gemini CLI 的自动执行限制，在 Agent 自动化调用场景下等于给模型直接执行任意操作的权限，OpenClaw 的技能文档明确建议回避。

OpenClaw 如何发现并加载这个技能

技能文件放在仓库根目录的 skills/gemini/SKILL.md，与1password/、himalaya/、summarize/等数十个 bundled 技能并列。它被加载的路径由源码保证：

1. bundled 技能根目录解析：bundled-dir.ts 的resolveBundledSkillsDir按序尝试：环境变量OPENCLAW_BUNDLED_SKILLS_DIR覆盖 →bun --compile单文件可执行文件同级的skills/目录 → 以模块位置向上回溯最多 6 层寻找形如技能的skills/目录（looksLikeSkillsDir要求目录内存在.md文件或包含SKILL.md的子目录，见 L7-L28）。仓库内skills/目录每个子目录都含SKILL.md，满足该判定。

2. 加载优先级：bundled 技能处于优先级第 5 档（低于工作区技能<workspace>/skills、项目.agents/skills、个人~/.agents/skills和托管技能目录，高于skills.load.extraDirs与插件技能，见 docs/tools/skills.md 的加载顺序表）。因此如果你在工作区放一个同名skills/gemini/SKILL.md，会覆盖内置版本——这是定制该技能的官方方式，例如补充你账号可用的模型列表或团队约定。

3. frontmatter 解析：frontmatter.ts 的parseSkillFrontmatter先解析 YAML 块并抛错于格式非法（L25-L32），随后resolveSkillManifestMetadata提取emoji、homepage、requires、install、os、always等字段（L203-L223）；resolveSkillInvocationPolicy则解析user-invocable（默认 true）与disable-model-invocation（默认 false）两个调用策略开关，决定技能是否可被斜杠命令直接调用、是否可被模型自主调用。本技能未设置这两项，即默认同时支持用户/gemini斜杠调用与模型自主调用。

4. 加载验证：写入或更新后运行openclaw skills list即可确认gemini出现在列表中（前提是gemini二进制已安装，否则会被门控过滤）。OpenClaw 默认监听技能根目录下的SKILL.md变更；若你修改了 bundled 版本或想立即生效，可/new开新会话或openclaw gateway restart。

一个典型的 Agent 使用场景

综合以上机制，OpenClaw 中这个技能的典型工作流是：

# Agent 收到"总结这份周报并输出 JSON"的请求后， # 依 SKILL.md 指令拼装无头命令： cat weekly.md | gemini -m gemini-2.5-pro \ -p "Summarize into sections and action items. Return JSON." \ --output-format json

• 门控保证只有装好gemini的机器才暴露此技能；
• -p保证进程一次性退出，不挂住 Agent 的执行工具；
• stdin 注入长文档，命令行保持短小；
• --output-format json让下游解析可靠；
• 登录问题引导用户先交互式gemini一次，而非在自动化流程里反复失败。

小结与参考路径

skills/gemini/SKILL.md体量虽小，却展示了 OpenClaw 技能体系的完整闭环：YAML frontmatter 声明依赖与安装方式，markdown 正文提供 Agent 可直接执行的命令知识，加载器负责发现、门控与优先级仲裁。理解了这一闭环，你就能照着同样的模式为任意 CLI 工具编写自己的技能。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw