从零打造AI航班助手：OpenClaw + 飞常准MCP全攻略

从零打造AI航班助手OpenClaw 飞常准MCP全攻略摘要本文记录了我从0到1开发一个完整的OpenClaw Skill的全过程涵盖MCP协议实战、YAML front matter踩坑、API密钥安全管理等核心技术点。如果你也想开发AI插件这篇避坑指南值得收藏已发布skillVariflightAviation供测试使用。 目录项目背景为什么要做这个Skill技术选型OpenClaw MCP是什么Step 1项目架构设计Step 2SKILL.md的YAML坑重点Step 3MCP服务器生命周期管理Step 4API密钥安全最佳实践Step 5数据解析与格式化输出完整代码与发布总结与展望一、项目背景为什么要做这个Skill最近AI应用爆发但大多数AI工具都是孤岛——无法直接获取实时数据。作为经常出差的开发者我需要一个能查航班、看天气、追踪飞机的AI助手。核心需求 实时航班查询按航线/航班号 航班舒适度评估准点率、机型评分️ 机场天气预报 飞机实时位置追踪技术路线OpenClawAI技能平台 飞常准MCP航班数据源二、技术选型OpenClaw MCP是什么2.1 OpenClawOpenClaw是AI技能Skill托管平台类似AI应用商店。开发者发布Skill用户通过自然语言调用。2.2 MCPModel Context ProtocolMCP是Anthropic推出的开放协议让AI模型能安全地访问外部数据源。简单说AI的USB接口。┌─────────────┐ MCP协议 ┌─────────────┐ │ AI助手 │ ◄──────────────► │ 飞常准API │ │ (Claude等) │ stdio/SSE │ 航班数据 │ └─────────────┘ └─────────────┘为什么选择MCP✅ 标准化接口无需重复开发API适配层✅ 支持stdio/SSE多种传输模式✅ 内置安全机制权限控制、密钥隔离三、Step 1项目架构设计3.1 目录结构variflight-aviation-skill/ ├── SKILL.md# 技能定义文件元数据文档├── package.json# npm配置├── config.json# 默认配置无敏感信息├── src/ │ ├── lib/ │ │ ├── variflight-client.js# MCP客户端封装│ │ ├── mcp-server-manager.js# 服务器生命周期管理│ │ └── config-loader.js# 配置加载器│ └── commands/ │ ├── search.js# 航线搜索│ ├── info.js# 航班详情│ ├── comfort.js# 舒适度指数│ ├── weather.js# 机场天气│ ├── transfer.js# 中转方案│ └── track.js# 飞机追踪└── bin/ └── variflight# CLI入口3.2 核心设计按需启动架构关键决策MCP服务器不作为守护进程而是每次调用时启动、用完即走。// 伪代码asyncfunctionsearchFlights(dep,arr,date){constclientnewVariflightClient();try{awaitclient.connect();// 1. 启动MCP服务器constresultawaitclient.callTool(searchFlightsByDepArr,{dep,arr,date});returnresult;}finally{awaitclient.disconnect();// 3. 关闭MCP服务器关键}}为什么不用守护进程❌ MCP stdio模式需要保持stdin/stdout连接守护进程会退出exit code 0/78✅ 按需启动避免资源浪费✅ 错误隔离单次失败不影响其他调用四、Step 2SKILL.md的YAML坑重点这是最容易踩坑的地方。SKILL.md采用YAML front matter Markdown混合格式。4.1 基础结构---name:variflight-aviationdescription:飞常准航班信息查询version:1.0.0metadata:openclaw:emoji:✈️category:travelrequirements:|# ← 多行字符串开始## 系统要求-Node.js 18.0.0---## 功能概述 # ← Markdown正文开始...4.2 致命坑点requirements中的代码块错误写法会导致Markdown解析错乱requirements:|## 配置方法bash# ← 嵌套代码块export KEYxxx json# ← 又一个嵌套代码块{key:xxx}错误现象功能概述的一部分在代码框内一部分在外面命令显示错乱正确写法三种方案方案1简化requirements代码示例放正文requirements:|系统要求Node.js 18.0.0 配置设置X_VARIFLIGHT_KEY环境变量---## 配置说明bash export X_VARIFLIGHT_KEYyour_key**方案2使用4空格缩进代替反引号** yaml requirements: | 设置环境变量 export X_VARIFLIGHT_KEYyour_key方案3使用-折叠修饰符requirements:-系统要求Node.js 18.0.04.3 环境变量命名陷阱飞常准MCP不使用常见的VARIFLIGHT_API_KEY而是X_VARIFLIGHT_KEY// 错误 ❌env:{VARIFLIGHT_API_KEY:xxx}// 返回401 Unauthorized// 正确 ✅env:{X_VARIFLIGHT_KEY:xxx}// 官方要求兼容写法支持两种变量名constapiKeyprocess.env.X_VARIFLIGHT_KEY||process.env.VARIFLIGHT_API_KEY;五、Step 3MCP服务器生命周期管理5.1 核心类VariflightClientconst{Client}require(modelcontextprotocol/sdk/client/index.js);const{StdioClientTransport}require(modelcontextprotocol/sdk/client/stdio.js);classVariflightClient{asyncconnect(){// 关键使用绝对路径避免nvm路径问题consttransportnewStdioClientTransport({command:/Users/lixiao/.nvm/versions/node/v22.14.0/bin/npx,args:[-y,variflight-ai/variflight-mcp],env:{X_VARIFLIGHT_KEY:this.apiKey,PATH:/Users/lixiao/.nvm/versions/node/v22.14.0/bin:/usr/local/bin:/usr/bin:/bin}});this.clientnewClient({name:variflight-skill,version:1.0.0});awaitthis.client.connect(transport);}asynccallTool(name,args){constresultawaitthis.client.callTool({name,arguments:args});// 解析MCP返回的content数组if(result?.content?.[0]?.typetext){try{returnJSON.parse(result.content[0].text);// 尝试解析JSON}catch(e){returnresult.content[0].text;// 返回原始文本}}returnresult;}}5.2 为什么不能用launchd守护进程我最初尝试用macOS launchd管理MCP服务器launchctl list|grepvariflight -0com.variflight.mcp# ← exit code 0表示正常退出失败原因MCP stdio模式需要与客户端保持stdin/stdout连接没有客户端连接时服务器自动退出这是设计特性不是bug守护进程模式适合SSEHTTP传输不适合stdio六、Step 4API密钥安全最佳实践6.1 绝不提交密钥到Git# .gitignore config.local.json # 本地配置文件含密钥 .env .env.local *.key *.pem6.2 配置优先级从高到低// config-loader.jsfunctionloadConfig(){// 1. 环境变量最高优先级生产环境用if(process.env.X_VARIFLIGHT_KEY){return{apiKey:process.env.X_VARIFLIGHT_KEY};}// 2. 本地配置文件开发环境用if(fs.existsSync(config.local.json)){returnJSON.parse(fs.readFileSync(config.local.json));}// 3. 默认配置无密钥仅模板returnJSON.parse(fs.readFileSync(config.json));}6.3 SKILL.md中的安全声明metadata:openclaw:env:-X_VARIFLIGHT_KEY# 只声明变量名不提供值requirements:|## 配置方法 1. 环境变量export X_VARIFLIGHT_KEYyour_key 2. 本地文件创建config.local.json已加入.gitignore⚠️ 注意请勿将API Key提交到Git七、Step 5数据解析与格式化输出7.1 飞常准API返回格式{code:200,message:Success,data:[{FlightNo:HU7601,FlightCompany:海南航空股份有限公司,FlightDeptimePlanDate:2026-02-20 07:25:00,FlightState:计划,OntimeRate:93.33%,ftype:78A}]}注意字段名是首字母大写的驼峰命名7.2 智能字段提取// 处理各种可能的字段名constflightNoflight.FlightNo||flight.flightNo||flight.flightNum||未知;constairlineflight.FlightCompany||flight.airline||未知航司;constdepTime(flight.FlightDeptimePlanDate||).split( )[1]?.substring(0,5)||待定;7.3 终端输出格式化console.log(${index1}.${flightNo}|${airline});console.log(${depTime}${depAirport}${depTerminal? TdepTerminal:});console.log(${arrTime}${arrAirport}${arrTerminal? TarrTerminal:});console.log(✈️${aircraft}| 状态:${status}${ontimeRate? | 准点率: ontimeRate:});输出效果1. HU7601 | 海南航空股份有限公司 07:25 PEK T2 09:35 SHA T2 ✈️ 78A | 状态: 计划 | 准点率: 93.33% 值机柜台: F,G 距离: 1178公里八、完整代码与发布8.1 GitHub仓库结构https://github.com/your-username/variflight-aviation-skill ├── SKILL.md ├── README.md ├── package.json ├── .gitignore └── src/ ├── lib/ │ ├── variflight-client.js │ ├── mcp-server-manager.js │ └── config-loader.js └── commands/ ├── search.js ├── info.js ├── comfort.js ├── weather.js ├── transfer.js └── track.js8.2 发布到ClawHub# 安装CLInpminstall-gclawhub# 登录需要GitHub账号注册满一周clawhub login# 发布cdvariflight-aviation-skill clawhub publish.\--slugvariflight-aviation\--nameVariflight Aviation\--version1.0.0# 验证clawhubinstallvariflight-aviation8.3 用户使用安装后用户可以在OpenClaw中使用variflight-aviation search PEK SHA2026-02-20 variflight-aviation info HU76012026-02-20 variflight-aviation weather PEK九、总结与展望核心收获技术点关键决策MCP架构按需启动避免守护进程YAML格式requirements简化代码示例放正文API密钥X_VARIFLIGHT_KEY环境变量数据解析首字母大写字段名兼容错误处理try-finally确保资源释放十、安装即可用clawhub skill名variflight-aviationopenclaw安装clawhubinstallvariflight-aviation现在可以会话查询3月13日下午上海虹桥到昆明的直达航班。回复✈️2026年3月13日 上海虹桥 → 昆明长水 下午航班信息以下是12:00以后出发的直飞航班不含经停航班号航司起飞到达航站楼机型准点率飞行时长MU5802东航12:1015:45T2B73796.7%~3h35m8L9888祥鹏航空13:2516:55T2A330100%~3h30mMU5806东航15:0518:50T2B73796.7%~3h45mHO1099吉祥航空15:5519:35T2A32093.3%~2h53mMU5808东航16:2019:50T2B737100%~3h30mMU5810东航17:2021:10T2B73793.3%~3h50mMU5804东航20:0523:55T2B73796.7%~3h50mMU5812东航21:1500:151T2B737100%~3h45m⚠️ 注意9C8829(春秋 12:25出发) - 经停常德不是直飞MU5323/9(09:25出发) - 经停长沙飞行时间较长 推荐下午航班MU5806(15:05出发) - 东航准点率96.7%HO1099(15:55出发) - 吉祥航空用时较短MU5808(16:20出发) - 东航准点率100% 联系方式东航95530吉祥航空95520祥鹏航空95326上海虹桥021-22344553昆明长水0871-67092570航线距离约2042公里需要查询具体某个航班的票价或舒适度评估吗踩坑清单❌ launchd守护进程失败 → ✅ 按需启动架构❌ VARIFLIGHT_API_KEY 401错误 → ✅ X_VARIFLIGHT_KEY❌ YAML嵌套代码块解析错乱 → ✅ 简化requirements❌ npx路径找不到 → ✅ 使用绝对路径未来优化缓存机制航班数据缓存5分钟减少API调用自然语言支持明天北京飞上海而非强制YYYY-MM-DD订阅推送航班状态变更主动通知 参考资源OpenClaw官方文档Model Context Protocol规范飞常准MCP平台ClawHavoc安全事件分析了解Skill安全最佳实践作者简介全栈开发者专注AI应用与DevOps。热爱用技术解决实际问题欢迎Star我的GitHub项目一起交流GitHub: https://github.com/Lancenas/variflight-aviation-skillCSDN: https://blog.csdn.net/qq_38637122如果本文对你有帮助请点赞、收藏⭐、评论三连支持有问题欢迎在评论区讨论。#OpenClaw #MCP #AI开发 #航班查询 #飞常准 #YAML #Node.js #技能开发