使用 OpenClaw 插件将 Higress AI Gateway 接入 AI Agent模型提供者与自动路由接入实战指南【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress本指南围绕 Higress 仓库中的 Higress AI Gateway OpenClaw 插件 展开讲解如何让 OpenClawAI Agent 运行时把 Higress AI Gateway 作为统一模型提供者model provider接入并启用higress/auto自动路由能力。读完本文你将掌握插件的文件结构、安装与交互式配置流程、源码级实现原理以及如何结合get-ai-gateway.sh部署网关并配置基于消息内容的智能模型路由。插件定位为什么需要它Higress AI Gateway 是一个 AI 原生 API 网关而 OpenClaw 是一个支持插件扩展的 AI Agent 平台从本仓库 skill 文档可确认其具备模型提供者插件、openclaw gateway网关、openclaw models模型认证等机制。二者之间需要一个翻译层让 OpenClaw 能像使用 OpenAI 原生模型一样调用经由 Higress 统一收敛的各类大模型。这个 TypeScript 编写的 provider 插件 正是这一层翻译它提供四项核心能力自动路由Auto-routing使用higress/auto作为模型名网关会根据请求消息内容智能选择底层模型动态模型发现Dynamic model discovery自动从 Higress Console 探测当前可用的模型列表智能 URL 处理Smart URL handling对网关地址做自动规范化与合法性校验灵活认证Flexible authentication同时支持本地部署无需 API Key与远程网关部署需要 API Key。插件文件清单与职责插件目录.agents/skills/higress-openclaw-integration/scripts/plugin/下共三个文件各司其职文件职责index.ts插件主实现注册 provider、定义交互式配置流程、生成 OpenClaw 配置补丁package.jsonNPM 包元数据与 OpenClaw 扩展声明openclaw.plugin.jsonOpenClaw 插件清单manifestpackage.json中的关键字段是openclaw: { extensions: [./index.ts] }它声明了插件入口文件openclaw.plugin.json则声明了插件id: higress、名称、描述与支持的providers: [higress]并允许additionalProperties承载任意配置项。插件的id将作为后续openclaw plugins enable higress、openclaw models auth login --provider higress命令中的唯一标识。安装插件自动安装推荐该插件会在使用higress-openclaw-integration技能时被自动安装到$HOME/.openclaw/extensions/higress/完整安装流程见父级技能文档 higress-openclaw-integration/SKILL.md。手动安装# 1. 复制插件文件到 OpenClaw 扩展目录 mkdir -p $HOME/.openclaw/extensions/higress cp -r ./* $HOME/.openclaw/extensions/higress/ # 2. 启用插件 openclaw plugins enable higress # 3. 配置模型提供者交互式 openclaw models auth login --provider higress需要注意openclaw models auth login与openclaw gateway restart均为交互式命令必须由用户在自己的终端中手动执行AI Agent 无法代为完成。配置完成后还需重启 OpenClaw 网关使配置生效openclaw gateway restart重启后Higress 的模型将以higress/前缀出现在 OpenClaw 中例如higress/glm-5、higress/auto。交互式配置全流程执行openclaw models auth login --provider higress后插件会依次引导用户输入 5 项信息以下默认值与提示文案均来自 index.ts 源码步骤输入项默认值说明1Gateway URLhttp://localhost:8080Higress AI Gateway 的地址输入后立即做 URL 校验2Console URLhttp://localhost:8001Higress Console 地址用于自动路由配置与模型探测3API Key空本地部署可留空留空时自动降级为higress-local4模型列表自动探测或内置默认逗号分隔包含higress/auto即启用自动路由5自动路由默认模型glm-5仅在模型列表包含higress/auto时出现用于无规则命中时的兜底配置过程中还会实时展示两个进度状态Testing gateway connection…网关连通性检测与 Fetching available models…模型探测。若网关连接失败插件会弹出 Connection Warning 提示用户检查网关是否运行、URL 是否正确但不会中断配置。配置流程的源码级拆解index.ts中register()内的auth配置项完整呈现了七步实现逻辑Gateway URLctx.prompter.text()读取输入validateUrl校验合法性Console URL同上用于后续自动路由配置连通性测试调用testGatewayConnection(gatewayUrl)向${gatewayUrl}/chat/completions发送空 body 的 POST 请求5 秒超时只要收到任意响应哪怕是 400/401/422即视为网关可达API Key留空时回退为higress-local后续据此判断是否为本地部署apiKey higress-local时 profileId 为higress:local且authHeader置为false模型探测调用fetchAvailableModels(consoleUrl)请求${consoleUrl}/v1/ai/routes解析data[].model字段探测成功则模型列表为[higress/auto, ...fetchedModels]失败则回退到内置默认列表模型列表确认用户可修改模型 ID 列表逗号或换行分隔parseModelIds会去重自动路由默认模型若列表含higress/auto额外询问无规则命中时的默认模型默认glm-5。源码级实现细节URL 规范化与校验normalizeBaseUrl()会对用户输入的网关地址做三步处理trim()去除首尾空白 → 循环去掉末尾的/→ 若不以/v1结尾则自动追加/v1。这意味着无论用户输入http://localhost:8080、http://localhost:8080/还是完整的http://localhost:8080/v1最终都会得到 OpenAI 兼容的http://localhost:8080/v1形式。validateUrl()则用new URL()做合法性兜底校验非法输入会返回Enter a valid URL错误提示。内置模型配置表插件内置了一张模型级联配置表MODEL_CONFIG为常见模型预设上下文窗口与最大输出 token模型contextWindowmaxTokensgpt-5.41,000,000128,000gpt-5.4-mini / gpt-5.4-nano400,000128,000claude-opus-4-61,000,000128,000claude-sonnet-4-61,000,00064,000claude-haiku-4-5200,00064,000qwen3.5-plus960,00064,000deepseek-chat / deepseek-reasoner256,000128,000kimi-k2.5256,000128,000glm-5200,000128,000MiniMax-M2.5200,000128,000未知模型回退200,000128,000需要说明的是这些模型名是插件内置的默认值实际可用的模型以 Higress 网关中已配置的 provider 为准用户在配置步骤中完全可以手动增删。内置默认模型清单DEFAULT_MODEL_IDS按厂商归类如下自动路由专用higress/auto常见模型kimi-k2.5、glm-5、MiniMax-M2.5、qwen3.5-plusAnthropic 系claude-opus-4-6、claude-sonnet-4-6、claude-haiku-4-5OpenAI 系gpt-5.4、gpt-5.4-mini、gpt-5.4-nanoDeepSeek 系deepseek-chat、deepseek-reasoner模型定义生成buildModelDefinition(modelId)为每个模型生成 OpenClaw 模型定义api固定为openai-completionsOpenAI 兼容协议、reasoning: true、输入模态[text, image]、成本cost全部为 0本地网关不计费。其中higress/auto会被特殊命名为 Higress Auto Router。网关连通性检测的两个事实源码注释明确写了两点其一Higress不支持/models端点因此连通性测试改为调用/chat/completions发送空 body其二只要收到任意 HTTP 响应包括 400/401/422都说明网关可达真正需要担心的只是网络不通或 DNS 失败。生成的最终配置配置完成后插件返回profiles、configPatch、defaultModel三部分profiles本地部署生成higress:local远程部署生成higress:default凭据类型为tokenconfigPatch写入 OpenClaw 配置——models.providers.higress含baseUrl、apiKey、api、authHeader、models、agents.defaults.models每个模型生成higress/modelId引用、plugins.entries.higress含gatewayUrl、consoleUrl、autoRoutingDefaultModeldefaultModel若列表含higress/auto则默认模型为higress/auto否则取列表第一个模型统一使用higress/前缀引用例如higress/glm-5。在 OpenClaw 中使用 Higress 模型配置并重启网关后模型即以下列形式在 OpenClaw 中可用higress/glm-5 higress/kimi-k2.5 higress/qwen3.5-plus higress/claude-opus-4-6 higress/gpt-5.4 higress/auto # 自动路由专用插件在完成配置后还会输出一条关键提示后续配置变更无需重启网关。得益于 Higress 的热加载机制用户可以直接通过对话让 OpenClaw动态新增 DeepSeek / OpenAI / Claude 等 provider、无重启更新已有 provider 的 API Key、以及配置自动路由规则。这也是将 Higress 作为统一模型网关的核心收益——所有 provider 与模型的管理都收敛到网关一侧。自动路由higress/auto的工作原理上游实现model-router 插件higress/auto并非 OpenClaw 侧的概念其底层能力由 Higress 的 wasm 插件 model-router 提供。从 main.go 源码可见定义了AutoModelPrefix higress/auto作为自动路由的专用模型名main.go#L24解析autoRouting配置对象包含enable是否启用、defaultModel无规则命中时的默认模型、rules按顺序匹配的正则规则数组每项含pattern与model匹配时遍历规则命中即把目标模型写入x-higress-llm-model请求头无规则命中则回退defaultModel两者皆无则保持原请求。路由规则配置命令自动路由的规则由get-ai-gateway.shCLI 工具管理详见 higress-auto-router skill# 新增规则消息命中触发词时路由到指定模型多个触发词用 | 分隔 ./get-ai-gateway.sh route add --model model-name --trigger keyword1|keyword2 # 也可用自定义正则替代触发词 ./get-ai-gateway.sh route add --model deepseek-chat --pattern (?i)^(数学题|math:) # 查看规则 ./get-ai-gateway.sh route list # 删除规则 ./get-ai-gateway.sh route remove --rule-id id规则实际存储在容器内/data/wasmplugins/model-router.internal.yamlCLI 会自动编辑该文件、校验 YAML 语法并触发热加载无需重启容器。常用触发词映射场景建议触发词推荐模型复杂推理深入思考\|deep thinkingclaude-opus-4.5, o1编码任务写代码\|code:\|coding:qwen-coder, deepseek-coder创意写作创意写作\|creative:gpt-4o, claude-sonnet翻译翻译:\|translate:gpt-4o, qwen-max数学题数学题\|math:deepseek-r1, o1-mini快速回答快速回答\|quick:qwen-turbo, gpt-4o-mini完整工作流用户在 OpenClaw 中发起请求模型参数为higress/autoHigress 的 model-router 插件将请求体中的model提取到x-higress-llm-model请求头并按序匹配autoRouting.rules中的正则命中某条规则 → 路由到该规则指定的模型全部未命中 → 使用defaultModel。验证自动路由是否生效可直接对网关发起请求# 测试指定模型 curl http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model: glm-5, messages: [{role: user, content: Hello}]} # 测试自动路由 curl http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model: higress/auto, messages: [{role: user, content: What is AI?}]}前置条件部署 Higress AI GatewayOpenClaw 插件只是客户端使用前需要先部署好 Higress AI Gateway。部署工具为get-ai-gateway.sh安装脚本支持start/stop/delete等子命令关键参数如下./get-ai-gateway.sh start --non-interactive \ --provider-key api-key \ [--auto-routing --auto-routing-default-model model]常用 provider 参数完整列表见 SKILL.mdProvider参数模型前缀智谱 / z.ai--zhipuai-keyglm-*Claude Code--claude-code-key需 OAuth token来自claude setup-token-Moonshot (Kimi)--moonshot-keymoonshot-, kimi-Minimax--minimax-keyabab-*阿里云通义千问--dashscope-keyqwen*OpenAI--openai-keygpt-, o1-, o3-*DeepSeek--deepseek-keydeepseek-*Grok--grok-keygrok-*Google Gemini / OpenRouter / Groq / Doubao 等对应--name-key各自模型z.ai / 智谱区域适配部署前可用 detect-region.sh 检测时区——命中Asia/Shanghai、Asia/Hong_Kong或含China/Beijing的时区输出china否则输出international。中国区默认使用域名open.bigmodel.cn国际区需追加--zhipuai-domain api.z.ai并默认启用--zhipuai-code-plan-mode面向编码任务优化走/api/coding/paas/v4/chat/completions端点。部署完成后的关键端点端点URLChat Completionshttp://localhost:8080/v1/chat/completionsConsolehttp://localhost:8001访问日志./higress-install/logs/access.log部署后的管理命令还包括./get-ai-gateway.sh config add --provider provider --key api-key热更新 API Key、route add/list/remove管理路由规则见上文、stop/delete停止或删除网关。常见问题与排查要点完整的排障手册见 TROUBLESHOOTING.md核心要点速查问题快速定位容器启动失败docker logs higress-ai-gateway查看日志netstat -tlnp \| grep 8080检查端口占用API server 报 too many open files调大fs.inotify.max_user_instances默认 128 偏小建议sysctl -w fs.inotify.max_user_instances8192并持久化到/etc/sysctl.conf插件未被识别检查~/.openclaw/extensions/higress目录与package.json中openclaw.extensions字段然后openclaw gateway restart自动路由不生效./get-ai-gateway.sh route list确认规则存在确认部署时带上了--auto-routingdocker logs higress-ai-gateway \| grep -i routing查网关日志镜像下载慢脚本按时区自动选择最近镜像仓库可手动设置IMAGE_REPO环境变量覆盖如杭州、东南亚、北美各区域镜像无法连接网关docker port higress-ai-gateway检查端口映射docker exec higress-ai-gateway curl localhost:8080/v1/models验证容器内连通性必要时放行防火墙端口小结与延伸阅读通过本文你已掌握 Higress AI Gateway OpenClaw 插件的完整接入路径部署网关 → 安装插件 → 交互式配置 → 使用higress/前缀模型 → 配置higress/auto自动路由。插件源码中的 URL 规范化、空 body 连通性探测、Console 模型发现等设计细节与上游model-router插件的正则路由机制共同构成了这套统一模型入口 内容感知路由的完整闭环。可进一步阅读父级技能完整部署指南higress-openclaw-integration/SKILL.md自动路由配置技能higress-auto-router/SKILL.md排障手册TROUBLESHOOTING.md上游路由插件实现model-router/main.go 与 model-router 配置说明插件与相关文档均以 Apache-2.0 协议开源。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考