在 openJiuwen 智能体平台中，插件是连接外部能力与智能体工作流的核心桥梁。平台支持本地自定义服务端插件、外部 API 调用插件（云侧插件）及代码插件三种类型。本文将以高德地图 Web 服务 API 为例，完整演示如何通过云侧插件方式接入 IP 城市定位与路径规划两个插件工具，并将其集成到智能工作流中，最终联动大模型完成“城市定位 → 旅游推荐”的自动化任务。

不同于单纯的操作步骤罗列，本文将在每个阶段穿插设计考量、常见问题及解决方案，帮助读者不仅“知其然”，更“知其所以然”，从而能够将这套流程快速复用到其他 API （支付，团购，优惠券）的接入场景中。读者可以基于这套流程，快速接入更多第三方 API，持续扩展 openJiuwen 工作流与智能体的能力边界。

一、为什么选择地图 API 作为插件示例？

在我们日常的智能体应用中，地理位置感知与路径规划是高频需求，例如：

• 根据用户 IP 自动推荐当地服务；
• 在文旅、出行、物流场景中规划最优路线；
• 结合大模型生成基于城市相关的个性化旅游推荐建议。

开发者通过阅读本文可以掌握以下技能：

• 云侧插件的创建与配置流程；
• 工具（API）的输入/输出参数配置方法；
• 插件测试与发布全流程；
• 工作流中插件的串联与大模型联动技巧。

二、准备条件与启动确认

2.1 环境准备

1、完成 openJiuwen 智能体平台部署

请参考官方部署文档：

openJiuwen agent studio 安装部署 部署成功后，您将获得一个本地可访问的 openJiuwen 服务。

2、服务启动确认

浏览器访问 http://localhost:3002/，若能正常打开工作台，并可进入「智能体管理」和「插件管理」页面，则视为启动成功。

3、获取高德地图 Web API Key

访问高德开放平台，注册账号并创建应用，获取 Key。 注意：Web 服务 API 的 Key 需要绑定安全域名或 IP，本地测试时可先不限制（调试完成后务必设置域名白名单）。

三、插件开发流程：从零到发布

3.1 核心概念：云侧插件与工具

在 openJiuwen 中：

• 插件是一组同域名的工具集合。例如高德地图插件可包含 IP 定位、步行路径规划、驾车路径规划等工具。
• 工具对应一个具体的 API 接口，需要明确其输入参数、输出结构以及请求方式。

设计思考：将同源 API 聚合为插件，便于权限管理和工作流编排。在创建插件时，服务URL 应填写 API 的基础地址（如 https://restapi.amap.com/v3），后续工具只需配置相对路径。

3.2、创建云端插件

1、进入「插件管理」→ 点击「安装插件」→ 选择「云端插件 – 基于已有服务创建」

2、填写插件基础信息，如下图所示：

插件配置项	说明	必填
插件名称	插件显示名称，建议包含服务商标识	是
插件描述	简短功能描述	是
插件详情	插件的详细描述，支持markdown格式，帮助用户了解插件的详细配置方式	否
服务URL	插件对应的服务基础URL，插件将通过该URL调用服务接口	是

注意：服务URL末尾不要带 /，工具配置时需填写完整的相对路径（如 /ip）。

4、点击「创建」，插件列表将出现新条目。此时插件为未配置工具状态。

3.3、添加并配置工具

插件创建完成后，进入「编辑插件」→ 切换到「工具设置」→ 点击「添加工具」，分别配置两个工具。

工具 1：IP 城市定位

1、开始编辑

这里我们上一步点击编辑插件，进入到插件的详情页面

2、添加工具

在配置选项这里切换到工具设置，然后再点击 【添加工具】，会弹出一个【创建工具】弹窗，这里我们进行高德地图插件下不同工具的配置：

3、进入工具详情页面

点击创建之后，我们进入城市定位工具的详情页面，如下图所示

4、输入参数配置

在这个页面，我们可以进一步的完善当前接口API的输入参数和输出参数，以及请求头配置。

高德 IP 定位 API 需要两个参数：

• key：用户密钥（必填）
• ip：要查询的 IP 地址，如不传则自动获取请求来源 IP

我们在工具详情页的「输入参数」Tab 中依次添加：

设计思考：这里将 key 作为显式参数，是为了在工作流中通过变量动态传入，避免将密钥硬编码在插件中。实际生产环境建议将 key 设为固定值并隐藏。这里也建议 openJiuwen增加一个密钥管理功能。

5、插件测试

切换到「测试」Tab，输入测试用的 Key 和 IP（例如 202.103.0.20），点击「开始测试」。

执行测试，可以看到测试结果——执行成功，成功返回：当前城市的IP信息—武汉

6、服务示例

https://restapi.amap.com/v3/ip?ip=114.247.50.2&output=xml&key=<用户的key>

参数	值	备注	必选
ip	202.103.45.20	需要搜索的 IP 地址（仅支持国内） 若用户不填写 IP，则取客户 HTTP 之中的请求来进行定位	否

返回结果示例:

​
{ "timestamp": "2026-02-11T15:45:42.101Z", "execution_success": true, "error_code": 0, "error_message": "success", "output": { "status": "1", "info": "OK", "infocode": "10000", "province": "湖北省", "city": "武汉市", "adcode": "420100", "rectangle": "114.0169501,30.36460893;114.6261227,30.77017755" }, "raw_response": { "data": { "type": "plugin", "payload": { "error_code": 0, "error_message": "success", "output": { "status": "1", "info": "OK", "infocode": "10000", "province": "湖北省", "city": "武汉市", "adcode": "420100", "rectangle": "114.0169501,30.36460893;114.6261227,30.77017755" } } }, "code": 200, "message": "Executed successfully" } }

​

测试成功后，工具状态变为启用。若修改参数或代码，工具将自动变为禁用，需重新测试通过才能生效。

7、常见问题与排查

• 400 错误：通常为参数缺失或格式错误，检查 key 是否有效，ip 格式是否正确。
• 401/10001：Key 无效或权限不足，确认 Key 类型为“Web 服务”，且 IP 白名单已放行。
• 超时：高德 API 响应通常在 200ms 以内，若持续超时请检查网络或服务URL是否可达。

到这一步我们的第一个城市定位插件工具就完成了

工具 2：步行路径规划

参照城市定位工具的配置流程，添加路径导航规划工具。

1、参考相同的方法快速完成【路径导航规划】插件工具的配置

2、输入参数配置

3、服务示例

​
https://restapi.amap.com/v3/direction/walking?origin=116.434307,39.90909&destination=116.434446,39.90816&key=<用户的key>

​

参数	值	备注	必选
origin	116.481028,39.989643	lon,lat（经度,纬度）,如117.500244, 40.417801 经纬度小数点不超过6位	是
destination	116.434446,39.90816	lon,lat（经度,纬度）,如117.500244, 40.417801 经纬度小数点不超过6位	是

返回结果示例：

​
{ "timestamp": "2026-02-11T16:07:43.508Z", "execution_success": true, "error_code": 0, "error_message": "success", "output": { "status": "1", "info": "ok", "infocode": "10000", "count": "1", "route": { "origin": "116.481028,39.989643", "destination": "116.434446,39.90816", "paths": [ { "distance": "11253", "duration": "9002", "steps": [ { "instruction": "向西南步行43米左转", "orientation": "西南", "road": [], "distance": "43", "duration": "34", "polyline": "116.481194,39.989544;116.480942,39.989288;116.480942,39.989288;116.48089,39.989227", "action": "左转", "assistant_action": [], "walk_type": "0" }, { "instruction": "步行287米右转", "orientation": [], "road": [], "distance": "287", "duration": "230", "polyline": "116.480885,39.989223;116.480933,39.989201;116.480933,39.989201;116.48115,39.989058;116.48115,39.989058;116.481432,39.98888;116.481432,39.98888;116.481489,39.988841;116.481489,39.988841;116.483238,39.987674;116.483238,39.987674;116.483325,39.987613;116.483329,39.987595;116.483329,39.987595;116.483372,39.98747", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "步行278米左转", "orientation": [], "road": [], "distance": "278", "duration": "222", "polyline": "116.483372,39.987465;116.48332,39.987409;116.48332,39.987409;116.4826,39.986775;116.4826,39.986775;116.482556,39.986732;116.482556,39.986732;116.481918,39.986137;116.481918,39.986137;116.481458,39.985716;116.481359,39.985499", "action": "左转", "assistant_action": [], "walk_type": "0" }, { "instruction": "步行126米向右前方行走", "orientation": [], "road": [], "distance": "126", "duration": "101", "polyline": "116.481354,39.985495;116.481497,39.985412;116.481497,39.985412;116.48214,39.984996;116.48214,39.984996;116.482487,39.984766;116.482491,39.984748", "action": "向右前方行走", "assistant_action": [], "walk_type": "0" }, { "instruction": "向南步行19米右转", "orientation": "南", "road": [], "distance": "19", "duration": "15", "polyline": "116.482491,39.984744;116.482552,39.984579", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "步行2688米左转", "orientation": [], "road": [], "distance": "2688", "duration": "2150", "polyline": "116.482552,39.984575;116.482413,39.984444;116.482413,39.984444;116.482183,39.984193;116.482183,39.984193;116.481536,39.983572;116.481536,39.983572;116.481411,39.98352;116.481411,39.98352;116.481259,39.983411;116.47947,39.981806;116.47947,39.981806;116.478828,39.981237;116.478806,39.981115;116.478806,39.981115;116.478277,39.980681;116.478277,39.980681;116.477934,39.980365;116.477934,39.980365;116.477886,39.98033;116.477886,39.98033;116.477661,39.980243;116.477231,39.979844;116.477053,39.979661;116.476984,39.979588;116.476984,39.979588;116.47671,39.979327;116.47671,39.979327;116.476628,39.979249;116.476467,39.979093;116.476467,39.979093;116.475812,39.978498;116.475812,39.978498;116.474709,39.977543;116.474709,39.977543;116.474184,39.977066;116.474184,39.977066;116.473681,39.976589;116.473681,39.976589;116.473047,39.976024;116.473047,39.976024;116.472808,39.975816;116.4726,39.975612;116.4726,39.975612;116.472318,39.975321;116.471871,39.974939;116.471871,39.974939;116.471372,39.974466;116.471372,39.974466;116.471111,39.974249;116.470616,39.973967;116.469987,39.973694;116.469774,39.973628;116.46921,39.973511;116.46921,39.973511;116.468694,39.973455;116.468477,39.973407;116.468394,39.973372;116.46783,39.972917;116.46783,39.972917;116.467036,39.972218;116.467036,39.972218;116.466701,39.971892;116.46661,39.97174;116.466576,39.971649;116.466567,39.971562;116.466567,39.971259;116.466567,39.971259;116.466554,39.971059;116.466554,39.971059;116.466523,39.970842;116.466463,39.970634;116.466363,39.970365;116.466272,39.970182;116.466094,39.9699;116.466094,39.9699;116.465968,39.969727;116.465573,39.969319;116.465573,39.969319;116.465282,39.96885;116.465282,39.96885;116.46523,39.968793;116.46523,39.968793;116.465122,39.968759;116.464818,39.96849;116.464818,39.96849;116.464779,39.968455;116.464779,39.968455;116.464557,39.968264;116.463707,39.967522;116.46283,39.966697;116.462717,39.966576;116.462717,39.966576;116.462717,39.966567;116.462617,39.966463", "action": "左转", "assistant_action": [], "walk_type": "2" }, { "instruction": "沿太阳宫北街向东南步行15米右转", "orientation": "东南", "road": "太阳宫北街", "distance": "15", "duration": "12", "polyline": "116.462613,39.966463;116.462652,39.966424;116.462652,39.966424;116.462695,39.966332", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿京密路向西南步行341米向左前方行走", "orientation": "西南", "road": "京密路", "distance": "341", "duration": "273", "polyline": "116.462695,39.966328;116.460799,39.964601;116.460799,39.964601;116.460117,39.963984", "action": "向左前方行走", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿京密路向西南步行1927米左转", "orientation": "西南", "road": "京密路", "distance": "1927", "duration": "1542", "polyline": "116.460113,39.963976;116.460204,39.963915;116.460204,39.963915;116.460117,39.963828;116.460117,39.963828;116.458069,39.961966;116.458069,39.961966;116.457426,39.961402;116.457426,39.961402;116.457257,39.961259;116.457257,39.961259;116.456732,39.960829;116.456732,39.960829;116.456207,39.960464;116.456207,39.960464;116.455569,39.960109;116.455569,39.960109;116.455078,39.959874;116.454805,39.959744;116.454644,39.959644;116.454379,39.959436;116.454379,39.959436;116.454327,39.959245;116.453676,39.958611;116.453676,39.958611;116.45352,39.958472;116.45352,39.958472;116.453186,39.958173;116.453186,39.958173;116.452995,39.957995;116.452995,39.957995;116.452313,39.957405;116.452313,39.957405;116.452166,39.957279;116.451463,39.956645;116.451463,39.956645;116.45125,39.956463;116.45125,39.956463;116.451111,39.956345;116.451111,39.956345;116.451068,39.956311;116.451068,39.956311;116.450707,39.955985;116.450707,39.955985;116.450369,39.95569;116.450369,39.95569;116.450165,39.955512;116.450165,39.955512;116.449896,39.955269;116.449896,39.955269;116.449757,39.955152;116.449757,39.955152;116.449336,39.954805;116.449336,39.954805;116.448559,39.954084;116.448559,39.954084;116.448485,39.954032;116.448485,39.954032;116.447817,39.953511;116.447817,39.953511;116.447135,39.953012;116.447135,39.953012;116.446771,39.952743;116.446771,39.952743;116.446558,39.952582;116.446558,39.952582;116.445994,39.952166;116.445994,39.952166;116.44556,39.951814;116.44556,39.951814;116.445161,39.951536;116.444839,39.951458;116.444839,39.951458;116.444744,39.95138", "action": "左转", "assistant_action": [], "walk_type": "0" }, { "instruction": "向东南步行155米右转", "orientation": "东南", "road": [], "distance": "155", "duration": "124", "polyline": "116.44474,39.951376;116.444787,39.951259;116.444926,39.95112;116.445247,39.95092;116.445247,39.95092;116.445343,39.950855;116.445343,39.950855;116.445833,39.95053;116.446059,39.950438", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿东直门外斜街向西南步行1266米右转", "orientation": "西南", "road": "东直门外斜街", "distance": "1266", "duration": "1013", "polyline": "116.446059,39.950434;116.445812,39.950308;116.445538,39.950078;116.445538,39.950078;116.445039,39.949596;116.445039,39.949596;116.444527,39.949119;116.444527,39.949119;116.444206,39.948854;116.444206,39.948854;116.443225,39.947977;116.443225,39.947977;116.442947,39.947765;116.442947,39.947765;116.442882,39.947708;116.442882,39.947708;116.442413,39.947287;116.442413,39.947287;116.44197,39.946875;116.44197,39.946875;116.441319,39.946298;116.441319,39.946298;116.441315,39.946289;116.440651,39.94569;116.440651,39.94569;116.440469,39.94553;116.440469,39.94553;116.440347,39.945425;116.440347,39.945425;116.440161,39.945256;116.440161,39.945256;116.43987,39.944987;116.43987,39.944987;116.439605,39.944727;116.439605,39.944727;116.438819,39.943989;116.438772,39.943932;116.438767,39.943793;116.438767,39.943793;116.438685,39.943663;116.438581,39.943398;116.438581,39.943398;116.438546,39.943082;116.438546,39.943082;116.438546,39.942899;116.438546,39.942899;116.438563,39.942487;116.438563,39.942487;116.438598,39.941554;116.438598,39.941554;116.438611,39.941194;116.438611,39.941194;116.438611,39.941068", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿东直门外大街向西步行337米左转", "orientation": "西", "road": "东直门外大街", "distance": "337", "duration": "270", "polyline": "116.438611,39.941063;116.437526,39.941046;116.437526,39.941046;116.437131,39.941037;116.437131,39.941037;116.436363,39.941037;116.436363,39.941037;116.436146,39.94099;116.435694,39.940981;116.435694,39.940981;116.435291,39.940981;116.435291,39.940981;116.435043,39.940981;116.435043,39.940981;116.43497,39.940981;116.43497,39.940981;116.434635,39.940968", "action": "左转", "assistant_action": [], "walk_type": "0" }, { "instruction": "步行582米向左前方行走", "orientation": [], "road": [], "distance": "582", "duration": "466", "polyline": "116.434631,39.940964;116.43457,39.940894;116.43457,39.940894;116.434523,39.940833;116.43447,39.940755;116.43447,39.940755;116.434431,39.940694;116.434431,39.940694;116.434462,39.940282;116.434462,39.940282;116.434488,39.939839;116.434488,39.939839;116.434488,39.939748;116.434488,39.939748;116.434492,39.939601;116.434492,39.939601;116.434488,39.939523;116.434431,39.93941;116.434431,39.93941;116.434375,39.939284;116.43418,39.938967;116.434162,39.938885;116.434171,39.938802;116.434171,39.938802;116.43424,39.937661;116.43424,39.937661;116.434262,39.937461;116.434262,39.937461;116.434271,39.937157;116.434271,39.937157;116.43428,39.936914;116.43428,39.936914;116.43431,39.93602;116.43431,39.93602;116.434284,39.935764", "action": "向左前方行走", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿东直门南大街向南步行182米右转", "orientation": "南", "road": "东直门南大街", "distance": "182", "duration": "146", "polyline": "116.43428,39.935764;116.434401,39.935382;116.434405,39.935304;116.434423,39.935156;116.434423,39.935156;116.434462,39.934132", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿东四十条桥步行172米右转", "orientation": [], "road": "东四十条桥", "distance": "172", "duration": "138", "polyline": "116.434462,39.934128;116.434388,39.934145;116.434327,39.934154;116.434327,39.934154;116.434084,39.934154;116.433911,39.934145;116.433811,39.934119;116.433811,39.934119;116.433707,39.93408;116.433707,39.93408;116.433624,39.934041;116.433624,39.934041;116.43352,39.933954;116.433472,39.933906;116.43339,39.933759;116.43339,39.933759;116.433377,39.933711;116.433377,39.933659;116.433377,39.933602;116.433377,39.933602;116.433424,39.933524;116.433472,39.933472;116.433472,39.933472;116.43365,39.933338;116.433724,39.933299", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "向南步行745米向左前方行走", "orientation": "南", "road": [], "distance": "745", "duration": "596", "polyline": "116.433724,39.933294;116.433759,39.932938;116.433759,39.932938;116.433785,39.932231;116.433785,39.932231;116.433811,39.931962;116.433811,39.931962;116.433863,39.931749;116.433885,39.931489;116.433885,39.931489;116.433885,39.931428;116.433885,39.931428;116.433893,39.931102;116.433893,39.931102;116.433898,39.930794;116.433898,39.930794;116.433958,39.929553;116.433958,39.929553;116.433958,39.929497;116.433958,39.929497;116.43401,39.928147;116.43401,39.928147;116.434015,39.928064;116.434015,39.928064;116.434028,39.927795;116.434028,39.927795;116.434036,39.927539;116.434036,39.927539;116.434106,39.926597;116.434106,39.926597;116.434201,39.926597", "action": "向左前方行走", "assistant_action": [], "walk_type": "0" }, { "instruction": "向南步行1958米向左前方行走", "orientation": "南", "road": [], "distance": "1958", "duration": "1566", "polyline": "116.434201,39.926593;116.434223,39.926402;116.434245,39.925977;116.43428,39.925065;116.43428,39.925065;116.434284,39.925022;116.434284,39.925022;116.43431,39.924319;116.434327,39.923911;116.434327,39.923911;116.434327,39.92388;116.434327,39.92388;116.434362,39.922582;116.434362,39.922582;116.434371,39.922348;116.434371,39.922348;116.434284,39.922144;116.434284,39.921992;116.434284,39.921992;116.434301,39.921584;116.434301,39.921584;116.434349,39.920061;116.434349,39.920061;116.434362,39.919588;116.434362,39.919588;116.434436,39.917982;116.434436,39.917982;116.43451,39.916497;116.43451,39.916497;116.434531,39.916059;116.434531,39.916059;116.434553,39.915768;116.434553,39.915768;116.434557,39.915655;116.434557,39.915655;116.434562,39.91556;116.434562,39.91556;116.434575,39.915369;116.434575,39.915369;116.434583,39.915082;116.434583,39.915082;116.434588,39.914957;116.434588,39.914957;116.434605,39.914536;116.434605,39.914536;116.434618,39.914332;116.434618,39.914332;116.434635,39.913971;116.434635,39.913971;116.434666,39.91355;116.434666,39.91355;116.43467,39.913494;116.43467,39.913494;116.434679,39.913333;116.434692,39.913173;116.434692,39.913173;116.434705,39.912839;116.434705,39.912839;116.43474,39.912244;116.43474,39.912244;116.434761,39.911784;116.434761,39.911784;116.434787,39.911202;116.434787,39.911202;116.434835,39.910161;116.434878,39.910013;116.434878,39.910013;116.434939,39.9098;116.434939,39.9098;116.434965,39.909045;116.434965,39.909045;116.434931,39.908932;116.434887,39.908863", "action": "向左前方行走", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿建国门北大街向南步行63米右转", "orientation": "南", "road": "建国门北大街", "distance": "63", "duration": "50", "polyline": "116.434883,39.908859;116.434818,39.908655;116.434831,39.908424;116.434878,39.908307", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿建国门内大街辅路向西步行44米左转", "orientation": "西", "road": "建国门内大街辅路", "distance": "44", "duration": "35", "polyline": "116.434878,39.908303;116.434727,39.908372;116.434661,39.908385;116.434388,39.908385", "action": "左转", "assistant_action": [], "walk_type": "0" }, { "instruction": "向南步行25米到达目的地", "orientation": "南", "road": [], "distance": "25", "duration": "20", "polyline": "116.434384,39.908385;116.434384,39.908164", "action": [], "assistant_action": "到达目的地", "walk_type": "0" } ] } ] } }, "raw_response": { "data": { "type": "plugin", "payload": { "error_code": 0, "error_message": "success", "output": { "status": "1", "info": "ok", "infocode": "10000", "count": "1", "route": { "origin": "116.481028,39.989643", "destination": "116.434446,39.90816", "paths": [ { "distance": "11253", "duration": "9002", "steps": [ { "instruction": "向西南步行43米左转", "orientation": "西南", "road": [], "distance": "43", "duration": "34", "polyline": "116.481194,39.989544;116.480942,39.989288;116.480942,39.989288;116.48089,39.989227", "action": "左转", "assistant_action": [], "walk_type": "0" }, { "instruction": "步行287米右转", "orientation": [], "road": [], "distance": "287", "duration": "230", "polyline": "116.480885,39.989223;116.480933,39.989201;116.480933,39.989201;116.48115,39.989058;116.48115,39.989058;116.481432,39.98888;116.481432,39.98888;116.481489,39.988841;116.481489,39.988841;116.483238,39.987674;116.483238,39.987674;116.483325,39.987613;116.483329,39.987595;116.483329,39.987595;116.483372,39.98747", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "步行278米左转", "orientation": [], "road": [], "distance": "278", "duration": "222", "polyline": "116.483372,39.987465;116.48332,39.987409;116.48332,39.987409;116.4826,39.986775;116.4826,39.986775;116.482556,39.986732;116.482556,39.986732;116.481918,39.986137;116.481918,39.986137;116.481458,39.985716;116.481359,39.985499", "action": "左转", "assistant_action": [], "walk_type": "0" }, { "instruction": "步行126米向右前方行走", "orientation": [], "road": [], "distance": "126", "duration": "101", "polyline": "116.481354,39.985495;116.481497,39.985412;116.481497,39.985412;116.48214,39.984996;116.48214,39.984996;116.482487,39.984766;116.482491,39.984748", "action": "向右前方行走", "assistant_action": [], "walk_type": "0" }, { "instruction": "向南步行19米右转", "orientation": "南", "road": [], "distance": "19", "duration": "15", "polyline": "116.482491,39.984744;116.482552,39.984579", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "步行2688米左转", "orientation": [], "road": [], "distance": "2688", "duration": "2150", "polyline": "116.482552,39.984575;116.482413,39.984444;116.482413,39.984444;116.482183,39.984193;116.482183,39.984193;116.481536,39.983572;116.481536,39.983572;116.481411,39.98352;116.481411,39.98352;116.481259,39.983411;116.47947,39.981806;116.47947,39.981806;116.478828,39.981237;116.478806,39.981115;116.478806,39.981115;116.478277,39.980681;116.478277,39.980681;116.477934,39.980365;116.477934,39.980365;116.477886,39.98033;116.477886,39.98033;116.477661,39.980243;116.477231,39.979844;116.477053,39.979661;116.476984,39.979588;116.476984,39.979588;116.47671,39.979327;116.47671,39.979327;116.476628,39.979249;116.476467,39.979093;116.476467,39.979093;116.475812,39.978498;116.475812,39.978498;116.474709,39.977543;116.474709,39.977543;116.474184,39.977066;116.474184,39.977066;116.473681,39.976589;116.473681,39.976589;116.473047,39.976024;116.473047,39.976024;116.472808,39.975816;116.4726,39.975612;116.4726,39.975612;116.472318,39.975321;116.471871,39.974939;116.471871,39.974939;116.471372,39.974466;116.471372,39.974466;116.471111,39.974249;116.470616,39.973967;116.469987,39.973694;116.469774,39.973628;116.46921,39.973511;116.46921,39.973511;116.468694,39.973455;116.468477,39.973407;116.468394,39.973372;116.46783,39.972917;116.46783,39.972917;116.467036,39.972218;116.467036,39.972218;116.466701,39.971892;116.46661,39.97174;116.466576,39.971649;116.466567,39.971562;116.466567,39.971259;116.466567,39.971259;116.466554,39.971059;116.466554,39.971059;116.466523,39.970842;116.466463,39.970634;116.466363,39.970365;116.466272,39.970182;116.466094,39.9699;116.466094,39.9699;116.465968,39.969727;116.465573,39.969319;116.465573,39.969319;116.465282,39.96885;116.465282,39.96885;116.46523,39.968793;116.46523,39.968793;116.465122,39.968759;116.464818,39.96849;116.464818,39.96849;116.464779,39.968455;116.464779,39.968455;116.464557,39.968264;116.463707,39.967522;116.46283,39.966697;116.462717,39.966576;116.462717,39.966576;116.462717,39.966567;116.462617,39.966463", "action": "左转", "assistant_action": [], "walk_type": "2" }, { "instruction": "沿太阳宫北街向东南步行15米右转", "orientation": "东南", "road": "太阳宫北街", "distance": "15", "duration": "12", "polyline": "116.462613,39.966463;116.462652,39.966424;116.462652,39.966424;116.462695,39.966332", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿京密路向西南步行341米向左前方行走", "orientation": "西南", "road": "京密路", "distance": "341", "duration": "273", "polyline": "116.462695,39.966328;116.460799,39.964601;116.460799,39.964601;116.460117,39.963984", "action": "向左前方行走", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿京密路向西南步行1927米左转", "orientation": "西南", "road": "京密路", "distance": "1927", "duration": "1542", "polyline": "116.460113,39.963976;116.460204,39.963915;116.460204,39.963915;116.460117,39.963828;116.460117,39.963828;116.458069,39.961966;116.458069,39.961966;116.457426,39.961402;116.457426,39.961402;116.457257,39.961259;116.457257,39.961259;116.456732,39.960829;116.456732,39.960829;116.456207,39.960464;116.456207,39.960464;116.455569,39.960109;116.455569,39.960109;116.455078,39.959874;116.454805,39.959744;116.454644,39.959644;116.454379,39.959436;116.454379,39.959436;116.454327,39.959245;116.453676,39.958611;116.453676,39.958611;116.45352,39.958472;116.45352,39.958472;116.453186,39.958173;116.453186,39.958173;116.452995,39.957995;116.452995,39.957995;116.452313,39.957405;116.452313,39.957405;116.452166,39.957279;116.451463,39.956645;116.451463,39.956645;116.45125,39.956463;116.45125,39.956463;116.451111,39.956345;116.451111,39.956345;116.451068,39.956311;116.451068,39.956311;116.450707,39.955985;116.450707,39.955985;116.450369,39.95569;116.450369,39.95569;116.450165,39.955512;116.450165,39.955512;116.449896,39.955269;116.449896,39.955269;116.449757,39.955152;116.449757,39.955152;116.449336,39.954805;116.449336,39.954805;116.448559,39.954084;116.448559,39.954084;116.448485,39.954032;116.448485,39.954032;116.447817,39.953511;116.447817,39.953511;116.447135,39.953012;116.447135,39.953012;116.446771,39.952743;116.446771,39.952743;116.446558,39.952582;116.446558,39.952582;116.445994,39.952166;116.445994,39.952166;116.44556,39.951814;116.44556,39.951814;116.445161,39.951536;116.444839,39.951458;116.444839,39.951458;116.444744,39.95138", "action": "左转", "assistant_action": [], "walk_type": "0" }, { "instruction": "向东南步行155米右转", "orientation": "东南", "road": [], "distance": "155", "duration": "124", "polyline": "116.44474,39.951376;116.444787,39.951259;116.444926,39.95112;116.445247,39.95092;116.445247,39.95092;116.445343,39.950855;116.445343,39.950855;116.445833,39.95053;116.446059,39.950438", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿东直门外斜街向西南步行1266米右转", "orientation": "西南", "road": "东直门外斜街", "distance": "1266", "duration": "1013", "polyline": "116.446059,39.950434;116.445812,39.950308;116.445538,39.950078;116.445538,39.950078;116.445039,39.949596;116.445039,39.949596;116.444527,39.949119;116.444527,39.949119;116.444206,39.948854;116.444206,39.948854;116.443225,39.947977;116.443225,39.947977;116.442947,39.947765;116.442947,39.947765;116.442882,39.947708;116.442882,39.947708;116.442413,39.947287;116.442413,39.947287;116.44197,39.946875;116.44197,39.946875;116.441319,39.946298;116.441319,39.946298;116.441315,39.946289;116.440651,39.94569;116.440651,39.94569;116.440469,39.94553;116.440469,39.94553;116.440347,39.945425;116.440347,39.945425;116.440161,39.945256;116.440161,39.945256;116.43987,39.944987;116.43987,39.944987;116.439605,39.944727;116.439605,39.944727;116.438819,39.943989;116.438772,39.943932;116.438767,39.943793;116.438767,39.943793;116.438685,39.943663;116.438581,39.943398;116.438581,39.943398;116.438546,39.943082;116.438546,39.943082;116.438546,39.942899;116.438546,39.942899;116.438563,39.942487;116.438563,39.942487;116.438598,39.941554;116.438598,39.941554;116.438611,39.941194;116.438611,39.941194;116.438611,39.941068", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿东直门外大街向西步行337米左转", "orientation": "西", "road": "东直门外大街", "distance": "337", "duration": "270", "polyline": "116.438611,39.941063;116.437526,39.941046;116.437526,39.941046;116.437131,39.941037;116.437131,39.941037;116.436363,39.941037;116.436363,39.941037;116.436146,39.94099;116.435694,39.940981;116.435694,39.940981;116.435291,39.940981;116.435291,39.940981;116.435043,39.940981;116.435043,39.940981;116.43497,39.940981;116.43497,39.940981;116.434635,39.940968", "action": "左转", "assistant_action": [], "walk_type": "0" }, { "instruction": "步行582米向左前方行走", "orientation": [], "road": [], "distance": "582", "duration": "466", "polyline": "116.434631,39.940964;116.43457,39.940894;116.43457,39.940894;116.434523,39.940833;116.43447,39.940755;116.43447,39.940755;116.434431,39.940694;116.434431,39.940694;116.434462,39.940282;116.434462,39.940282;116.434488,39.939839;116.434488,39.939839;116.434488,39.939748;116.434488,39.939748;116.434492,39.939601;116.434492,39.939601;116.434488,39.939523;116.434431,39.93941;116.434431,39.93941;116.434375,39.939284;116.43418,39.938967;116.434162,39.938885;116.434171,39.938802;116.434171,39.938802;116.43424,39.937661;116.43424,39.937661;116.434262,39.937461;116.434262,39.937461;116.434271,39.937157;116.434271,39.937157;116.43428,39.936914;116.43428,39.936914;116.43431,39.93602;116.43431,39.93602;116.434284,39.935764", "action": "向左前方行走", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿东直门南大街向南步行182米右转", "orientation": "南", "road": "东直门南大街", "distance": "182", "duration": "146", "polyline": "116.43428,39.935764;116.434401,39.935382;116.434405,39.935304;116.434423,39.935156;116.434423,39.935156;116.434462,39.934132", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿东四十条桥步行172米右转", "orientation": [], "road": "东四十条桥", "distance": "172", "duration": "138", "polyline": "116.434462,39.934128;116.434388,39.934145;116.434327,39.934154;116.434327,39.934154;116.434084,39.934154;116.433911,39.934145;116.433811,39.934119;116.433811,39.934119;116.433707,39.93408;116.433707,39.93408;116.433624,39.934041;116.433624,39.934041;116.43352,39.933954;116.433472,39.933906;116.43339,39.933759;116.43339,39.933759;116.433377,39.933711;116.433377,39.933659;116.433377,39.933602;116.433377,39.933602;116.433424,39.933524;116.433472,39.933472;116.433472,39.933472;116.43365,39.933338;116.433724,39.933299", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "向南步行745米向左前方行走", "orientation": "南", "road": [], "distance": "745", "duration": "596", "polyline": "116.433724,39.933294;116.433759,39.932938;116.433759,39.932938;116.433785,39.932231;116.433785,39.932231;116.433811,39.931962;116.433811,39.931962;116.433863,39.931749;116.433885,39.931489;116.433885,39.931489;116.433885,39.931428;116.433885,39.931428;116.433893,39.931102;116.433893,39.931102;116.433898,39.930794;116.433898,39.930794;116.433958,39.929553;116.433958,39.929553;116.433958,39.929497;116.433958,39.929497;116.43401,39.928147;116.43401,39.928147;116.434015,39.928064;116.434015,39.928064;116.434028,39.927795;116.434028,39.927795;116.434036,39.927539;116.434036,39.927539;116.434106,39.926597;116.434106,39.926597;116.434201,39.926597", "action": "向左前方行走", "assistant_action": [], "walk_type": "0" }, { "instruction": "向南步行1958米向左前方行走", "orientation": "南", "road": [], "distance": "1958", "duration": "1566", "polyline": "116.434201,39.926593;116.434223,39.926402;116.434245,39.925977;116.43428,39.925065;116.43428,39.925065;116.434284,39.925022;116.434284,39.925022;116.43431,39.924319;116.434327,39.923911;116.434327,39.923911;116.434327,39.92388;116.434327,39.92388;116.434362,39.922582;116.434362,39.922582;116.434371,39.922348;116.434371,39.922348;116.434284,39.922144;116.434284,39.921992;116.434284,39.921992;116.434301,39.921584;116.434301,39.921584;116.434349,39.920061;116.434349,39.920061;116.434362,39.919588;116.434362,39.919588;116.434436,39.917982;116.434436,39.917982;116.43451,39.916497;116.43451,39.916497;116.434531,39.916059;116.434531,39.916059;116.434553,39.915768;116.434553,39.915768;116.434557,39.915655;116.434557,39.915655;116.434562,39.91556;116.434562,39.91556;116.434575,39.915369;116.434575,39.915369;116.434583,39.915082;116.434583,39.915082;116.434588,39.914957;116.434588,39.914957;116.434605,39.914536;116.434605,39.914536;116.434618,39.914332;116.434618,39.914332;116.434635,39.913971;116.434635,39.913971;116.434666,39.91355;116.434666,39.91355;116.43467,39.913494;116.43467,39.913494;116.434679,39.913333;116.434692,39.913173;116.434692,39.913173;116.434705,39.912839;116.434705,39.912839;116.43474,39.912244;116.43474,39.912244;116.434761,39.911784;116.434761,39.911784;116.434787,39.911202;116.434787,39.911202;116.434835,39.910161;116.434878,39.910013;116.434878,39.910013;116.434939,39.9098;116.434939,39.9098;116.434965,39.909045;116.434965,39.909045;116.434931,39.908932;116.434887,39.908863", "action": "向左前方行走", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿建国门北大街向南步行63米右转", "orientation": "南", "road": "建国门北大街", "distance": "63", "duration": "50", "polyline": "116.434883,39.908859;116.434818,39.908655;116.434831,39.908424;116.434878,39.908307", "action": "右转", "assistant_action": [], "walk_type": "0" }, { "instruction": "沿建国门内大街辅路向西步行44米左转", "orientation": "西", "road": "建国门内大街辅路", "distance": "44", "duration": "35", "polyline": "116.434878,39.908303;116.434727,39.908372;116.434661,39.908385;116.434388,39.908385", "action": "左转", "assistant_action": [], "walk_type": "0" }, { "instruction": "向南步行25米到达目的地", "orientation": "南", "road": [], "distance": "25", "duration": "20", "polyline": "116.434384,39.908385;116.434384,39.908164", "action": [], "assistant_action": "到达目的地", "walk_type": "0" } ] } ] } } } }, "code": 200, "message": "Executed successfully" } }

​

4、设计思考：

为什么选择步行路径规划而非驾车？——步行规划接口对坐标精度要求较低，且返回数据量适中，适合展示。实际项目中可根据业务需求扩展驾车、骑行等工具。

到这一步我们高德地图API插件及其城市定位和路径导航规划工具就配置完成了

3.4 点击发布插件

工具配置并测试通过后，点击「发布插件」。

填写版本号、更新日志等信息，发布成功后，插件状态变为已发布，可在插件列表中看到最新版本

此时，高德地图插件已具备两个可用工具，可供智能体和工作流调用。

四、插件验证：集成到工作流

一个插件开发好了，如何验证我们的插件，以及插件在哪个场景下使用是比较合适的呢？

博主这里测试了直接在智能体中集成了插件这种方式，发现是比较难触发插件的调用，然后给出来的结果也不是相关联的。例如：“请根据当前定位的城市，帮我生成一个2日行程的旅游攻略推荐”，大模型在思考了一会后，没有给出相关的答案，其实并不太清楚我们自然语言中的需求，然后判断是否需要去调用插件的城市定位功能。

那么是不是在在工作流当中，我们的插件发挥的功能会更大，因为数据更加结构化，流程更加严谨，效率更高。

为验证插件可用，我创建一个城市定位 + 旅游推荐工作流，示例流程如下：

开始节点 → 城市定位插件节点 → 大模型节点 → 结束节点

1、前置准备

我们先切到模型管理里面，快速的添加一个大模型服务

配置完成后，测试一下 是否调用成功，成功响应回答即可。

注意：大模型节点需要能够解析插件输出的 JSON 数据。高德 API 返回字段较多，建议在提示词中明确指导模型提取关键信息。

2、 创建工作流

新建工作流：这里我们新建一个citylocation工作流 ，主要功能：获取城市定位信息，并给到城市旅游景点推荐。

开始节点：添加两个变量 key 和 ip，作为工作流的输入。

城市定位插件节点：选择高德地图插件的「IP城市定位」工具，将开始节点的 key 映射到工具参数 key，ip 映射到 ip。

大模型节点：

• 输入：引用上一节点的输出（即插件返回的完整 JSON）。
• 提示词设计：”提取当前结果中的城市信息，并给出当前城市的旅游推荐指南“

当然了，上面提示词的对大模型来说解析效率较低，这里我们可以进一步的优化提示词：

请从以下 JSON 中提取城市信息（province 和 city），并给出该城市最值得游览的 3 个旅游景点及简短推荐理由。 {{城市定位插件节点.output}}

结束节点：输出大模型节点的生成内容。

3、试运行验证

点击「试运行」，工作流会依次执行：获取 IP 定位 → 解析城市（插件） → 生成旅游推荐，最终正常输出结果，代表插件集成成功。

工作流执行成功，表明插件已正确集成，且大模型能理解插件输出并生成有用信息。

五、深度思考与建议

5.1 插件开发的核心模式

云侧插件的本质是将外部 REST API 映射为 openJiuwen 内部的可编排工具。这一模式具有以下优势：

• 标准化：无论底层 API 如何复杂，插件层统一了输入输出格式，简化工作流开发。
• 复用性：同一个插件工具可被多个工作流、多个智能体共享。
• 可观测性：插件测试、日志、监控均在平台内闭环，便于调试。

5.2 参数安全与最佳实践

• 密钥管理：避免将 key 硬编码在插件中。应作为工作流变量传入，或使用平台的密钥服务（若支持）。高德 API 的 key 属于敏感信息，建议在插件描述中提醒用户。
• 参数校验：对于必填参数，插件层应在前端（工具配置时）和后端（运行时）进行校验。目前 openJiuwen 仅在前端标记必填，实际调用时仍需依赖 API 自身的校验。

5.3 工作流编排的更多可能性

本次仅演示了单插件节点与大模型的简单串联。实际场景中，你可以：

• 链式调用：先通过 IP 定位获取城市，再用该城市调用其他 API（如团购、优惠券、支付、天气、新闻）。
• 分支判断：根据插件返回的状态码决定是否继续执行。
• 循环处理：批量处理多个 IP 地址的定位。

六、常见问题与解决方案

问题现象	可能原因	解决方案
插件测试返回 status: 0	Key 无效 / 配额超限 / IP 白名单未配置	检查 Key 是否正确；登录高德控制台查看配额；添加当前外网 IP 到白名单
工作流中插件节点执行失败	参数映射错误	确认开始节点变量名与插件参数名完全一致；检查变量是否为空
大模型节点输出不包含城市信息	提示词未明确要求提取	优化提示词，明确要求“提取 JSON 中的 province 和 city”
插件发布后仍显示“禁用”	修改后未重新测试	修改任何配置后需重新测试通过，工具状态才会变为“启用”

七、总结

本文通过高德地图 API 接入的完整案例，展示了 openJiuwen 平台云侧插件的开发全流程：创建插件 → 配置工具 → 测试验证 → 发布 → 工作流集成。我们不仅完成了操作步骤，深入讨论了插件设计思路、安全实践以及常见问题的应对方法。

通过这次实战，你应该能够：

1. 独立将任意标准 REST API 封装为 openJiuwen 插件；
2. 在工作流中灵活编排插件与大模型，构建智能应用；
3. 具备排查插件调用失败的基本能力。

插件机制是 openJiuwen 生态扩展的基石。无论是接入第三方服务，还是将企业内部系统能力开放给智能体，这套流程都能快速落地。开发者们可以基于这套流程，快速接入更多第三方 API，持续扩展 openJiuwen 工作流与智能体的能力边界。