用 Shield CLI 本地开发调试:从零到上线你的第一个 Skill

当 AI Agent 需要调用外部能力时Skill 就是它的技能包。本文以一个文旅素材搜索 Skill 为例带你走完本地开发 → 调试 → 发布 → 安装使用的完整流程。核心工具只有一个 ——Shield CLI。背景什么是 SkillSkill 是符合 Agent Skills 规范的能力描述包。一个典型的 Skill 包含my-skill/ ├── .well-known/agent-skills/index.json # 发现文件描述、权限、环境变量 ├── SKILL.md # 技能指令Agent 读取并执行 ├── config.json # 运行时配置API 地址等 └── references/ # 补充文档Agent 通过读取SKILL.md了解如何调用你的 API而index.json告诉平台这个 Skill 需要什么权限、支持哪些环境变量。我们今天要开发的 Skill 很简单通过一个 POST API 搜索素材将结果以表格形式展示给用户。API 是现成的我们要做的是把它包装成 Agent 能理解的 Skill。一、安装 Shield CLIShield CLI 是 YiShield 提供的命令行工具用于本地开发、调试和部署应用。macOS推荐使用 Homebrewbrew tap fengyily/tap brewinstallshield-cliWindows使用 PowerShell 一键安装irm https://raw.githubusercontent.com/fengyily/shield-cli/main/install.ps1|iex手动安装前往 Shield CLI 官方文档 根据对应平台选择安装方式验证安装f1F1s-MacBook-Pro ~ % shield--versionshield version0.3.11f1F1s-MacBook-Pro ~ % shield start _____ __ _ __ __ ________ ____ / ___// /_ (_)__ / /___/ / / ____/ / / _/ \__ \/ __ \/ // _ \/ // __ / / / / / / / ___/ / / / / // __/ // /_/ / / /___/ /____/ / /____/_/ /_/_/ \___/_/ \__,_/ \____/_____/___/ Shield CLI - Secure Tunnel Connector ├─ Version: 0.3.11 ├─ Go: go1.25.8 └─ Platform: darwin/arm64 ────────────────────────────────────────────────── ✓ Service is already running Web UI: http://localhost:8181 Commands: shield stop Stop the service shield uninstall Remove the service f1F1s-MacBook-Pro ~ %二、本地启动 API 服务Shield CLI 最强大的能力之一是将你的本地服务暴露为可调试的 API 端点。启动本地服务假设你的后端 API 已经在本地开发完毕比如一个 Python FastAPI 或 Go 服务先把它跑起来# 示例启动文旅素材搜索 APIcurlhttp://localhost:8080/api/v1/resources/search\--data-raw{query:雁荡山,use_llm:true,page:1,page_size:1}服务启动后通过http://127.0.0.1:8080即可在本地访问。本地测试 API用curl快速验证接口是否正常rootfenyi-MS-7E44:~# curl -X POST http://172.16.3.60:8080/api/v1/resources/search -H Content-Type: application/json -d {query: 雁荡山, page_size: 1, use_llm: false}|jq你应该能看到类似这样的响应{code:0,message:success,data:{total:42,items:[...],page:1,page_size:5}}三、WebUI 配置获取外网访问地址本地 API 跑通了但 Agent 平台如 OpenClaw在云端它无法直接访问你的127.0.0.1。这时需要通过 Shield 的隧道功能将本地服务映射到外网。启动隧道通过http://127.0.0.1:8181访问 Shield 的 Web 界面添加一个 HTTP 协议端口 8080 IP 为 127.0.0.1 的应用点击连接等待几秒Shield 会为你分配一个外网可达的地址格式类似https://d2128144f966ce17-yishield.cn01.apps.yishield.com[图片待补充]Shield 隧道启动成功显示分配的外网地址更新 Skill 配置拿到外网地址后将其填入 Skill 的config.json{api_origin:https://d2128144f966ce17-yishield.cn01.apps.yishield.com,api_version_path:/api/v1,preview_play_path:/api/v1/play,trusted_media_origins:[https://d2128144f966ce17-yishield.cn01.apps.yishield.com]}这样 Agent 在远端调用时请求会通过 Shield 隧道转发到你的本地服务。改一行代码 → 刷新 → 立即生效无需重新部署。四、将 Skill 目录上传到 ClawHub 并发布本地调试完毕、功能确认无误后就可以把 Skill 发布到 ClawHub —— Agent Skill 的集中分发平台。打开 https://clawhub.ai/登录账号进入「我的 Skills」页面点击「上传 Skill」选择文件夹填写 Skill 名称、描述、分类等元信息点击「发布」发布后平台会扫描你的 Skill 当状态变为 Benign 就可以被其他用户在 ClawHub 市场中搜索和安装了。五、在 OpenClaw 中安装和调试 Skill5.1 安装 Skill打开 OpenClaw 客户端进入「Skill 市场」或「技能管理」搜索你刚发布的 Skill 名称如culturetour-skill点击「安装」我这里用的是 ArkClaw5.2 配置环境变量可选如果你需要让 Skill 指向不同的 API 地址比如在开发阶段指向 Shield 隧道地址可以在 OpenClaw 中设置环境变量变量名说明WENLV_API_ORIGIN覆盖 config.json 中的 api_origin仅站点根不含 /api/v1TRADE_API_BASE交易 API 基址预留5.3 对话调试安装完成后直接在 OpenClaw 对话框中用自然语言触发 Skill用户帮我搜索黄山相关的文旅素材Agent 会自动调用 Skill 中定义的 API返回结构化的搜索结果表格你可以继续测试完整流程用户选 1、3 用户预览第 1 条的视频 用户确认购买5.4 实时调试技巧这里是 Shield CLI 真正发光的地方 ——本地服务还在跑着隧道还连着。你在 OpenClaw 里触发的每一次 API 调用都会实时打到你的本地服务看日志本地终端实时输出请求日志方便排查参数和响应改代码修改 API 逻辑后重启服务OpenClaw 里下一次对话就能看到效果改 Skill调整SKILL.md中的指令描述重新打包上传测试 Agent 行为变化[本地终端] POST /api/v1/resources/search 200 {query:黄山,page_size:5} 32ms POST /api/v1/resources/search 200 {query:西湖 日落,page_size:3} 28ms[图片待补充]Shield 隧道实时转发请求到本地终端可见完整日志总结为什么选择 Shield CLI传统方式Shield CLI 方式改代码 → 推送 → CI/CD → 部署 → 测试改代码 → 本地重启 → 立即测试搭建测试环境配置域名、证书一条shield http 8080命令搞定调试靠日志平台延迟高本地终端实时看请求/响应API 和 Skill 分开调试端到端打通Agent 直接调用本地服务Shield CLI 的核心价值在于缩短反馈循环零部署调试—— 本地服务通过隧道直接暴露给 Agent 平台省去了部署到测试环境的等待时间所见即所得—— 修改 API 逻辑后秒级生效修改 Skill 描述后重新上传即可验证 Agent 行为全链路可观测—— 请求从 Agent → Shield 隧道 → 本地服务每一跳都有日志问题定位快开发生产一致—— 本地用的和线上跑的是同一套代码、同一个 API不存在本地能跑线上挂的问题低门槛—— 不需要公网服务器、不需要配置 Nginx、不需要申请域名证书一个 CLI 工具全搞定对于 Skill 开发者来说Shield CLI 把原本需要多个工具、多次部署才能完成的工作流压缩成了本地开发 一条命令。当你的 Skill 在 OpenClaw 里跑通了把config.json里的地址换成生产环境就是正式上线。开始动手吧Shield CLI 开源地址https://github.com/fengyily/shield-cli如果你觉得有用就点个星星吧