Wox AI 设置完全指南：Provider 配置、字段解析与底层实现原理

桌面应用AI 应用插件系统【免费下载链接】WoxA cross-platform launcher that simply works项目地址https://gitcode.com/gh_mirrors/wo/Wox点击查看免费下载Wox 的 AI 能力AI 对话、AI 命令、AI 辅助 Emoji 搜索、听写润色、AI 生成主题全部是可选的核心前提是正确配置一个可用的 AI Provider。本文以官方指南 AI 设置 为骨架结合wox.core/ai与wox.core/setting的源码实现讲透 Provider 的添加步骤、每个字段的真实含义与存储结构以及 API 与 CLI 两类 Provider 各自的底层工作机制让你既能快速上手配置也能在遇到问题时按图索骥排查。Wox AI 设置界面为什么需要配置 ProviderAI 功能在 Wox 中是按需启用的。只有当你想使用以下任一能力时才需要进入设置 - AI配置 ProviderAI 对话与模型进行多轮聊天对应系统插件 chatAI 命令通过模板或自然语言触发执行命令见 AI 命令AI 辅助 Emoji 搜索用自然语言描述查找表情符号听写润色对语音识别结果进行 AI 优化见 听写AI 生成主题根据描述生成或调整界面主题见 主题生成如果以上功能你都不需要可以完全跳过本节不影响 Wox 的其余功能。添加 Provider 的五个步骤打开设置 - AI。点击添加。选择APIprovider或已安装的 CLIprovider。填写名称、凭据或 CLI 信息、模型以及需要时的自定义 host。保存后在具体功能如 AI 对话、AI 命令中选择这个 provider。Provider 列表会分成API和已安装的 CLI两组API provider使用密钥API key和可选的自定义 host由 Wox 直接发起 HTTP 请求调用模型服务。已安装的 CLI provider复用本机已经安装的命令行工具如桌面编程助手Wox 负责以子进程方式驱动它并透传你已有的登录态。列表本身支持搜索便于在 provider 数量较多时快速定位Wox 能识别的 CLI 会显示对应品牌图标详见下文“品牌图标”小节。字段含义详解官方指南给出了五个核心字段下表在原文基础上补充了其在 AIProvider 结构体 中的对应存储字段与补充说明字段作用对应存储字段补充说明Provider 名称在 Wox 设置里识别这个 provider 的名称Name从预置列表中选择例如openai、deepseek、claude-cliAPI keyWox 发给 API provider 的凭据ApiKey仅 API provider 使用CLI provider 复用本机命令自身登录态Host兼容服务、代理或本地服务的可选 API 地址Host留空时使用 provider 的默认地址GetDefaultHostModel聊天、命令或生成类功能使用的模型请求时传入CLI provider 通过探测命令返回其可用模型列表CLI已安装 CLI provider 使用的本地命令Executable可选留空时按 PATH 及常见安装目录自动发现除了官方文档列出的五项源码中还暴露了两个值得了解的进阶字段AliasAlias同一 provider 可以添加多条配置Alias用于区分这些同名配置。例如你同时配置了国内与海外两个 OpenAI 兼容端点可以用 Alias 标注各自用途。Reasoning Effort推理强度ReasoningEffort仅对已安装 CLI provider 生效用于控制模型思考深度。可取值包括空值沿用模型默认以及none、minimal、low、medium、high、xhigh、max七档在 AI 设置表单 中以下拉框形式呈现若填入非法值ChatStream 会直接返回错误。存储与持久化所有 AI provider 配置以 JSON 数组形式保存在设置键AIProviders中见 wox_setting.go每个元素即一个AIProvider对象。在 UI 层newAISettingsForm 将其渲染为一张可内联编辑的表格列包括Status连通状态、Name、Alias、Host、ApiKey、Executable、ReasoningEffort。其中Host、ApiKey只在选中 API provider 时可见Executable、ReasoningEffort只在选中 CLI provider 时可见——表单通过VisibleWhen动态切换列避免不同 provider 类型的字段互相干扰。API Provider密钥 Host 的请求通道API provider 是 Wox 直接以 HTTP 方式访问模型服务的一类。从源码看绝大多数 API provider 都建立在 OpenAI 兼容协议之上OpenAIBaseProvider 是所有 OpenAI 兼容 provider 的基类getClient构造客户端时把AIProvider.Host作为BaseURL、ApiKey作为认证凭据发送见 getClient。当前仓库中注册的 API provider 包括见各init()注册处Provider注册名说明OpenAIopenai官方 OpenAI 接口DeepSeekdeepseek兼容 OpenAI 协议流式返回reasoning_contentGooglegoogleGoogle 模型服务GroqgroqGroq 高速推理服务MiniMaxminimaxMiniMax 模型服务Ollamaollama/ollama cloud本地部署模型ollama常用于本地服务OpenRouteropenrouter聚合多家模型的路由服务SiliconFlowsiliconflow硅基流动平台注册机制本身是插件式的每个 provider 在包初始化时把自己的工厂函数写入providerFactories映射运行时通过 NewProvider 按名称查找工厂并实例化。这也解释了为什么“Provider 名称”必须从预置列表中选择——它直接对应providerFactories中的注册键。值得注意的实现细节所有 OpenAI 兼容 provider 共享一套流式解析逻辑包括推理内容分离流式返回时统一识别reasoning与reasoning_content两个字段把思考过程与最终答案分开呈现见 reasoningExtraFieldNames内容标签路由部分模型用think.../think标签包裹思考内容解析器会将其剥离并归入推理区不混入用户可见答案见 streamContentTagsTool Call 参数归一化对模型返回的工具调用参数做类型修正、必填参数补齐、下划线命名对齐等处理见 normalizeArguments。这意味着只要目标服务兼容 OpenAI 的/v1/chat/completions协议即使它不在上面的预置列表里理论上也可以通过选择某个兼容 provider 并填写自定义 Host 来接入例如各类代理服务、本地服务或公司内部网关。已安装 CLI Provider驱动本机命令CLI provider 是 Wox 的一个特色它不把 API key 交给 Wox而是直接驱动你本机已经安装并登录好的命令行工具。当前注册的 CLI provider 有四种Provider注册名底层命令Claude Codeclaude-cliclaudeCodexcodex-clicodexGrokgrok-cligrokOpenCodeopencode-cliopencode可执行文件发现机制CLI provider 配置里填的Executable是可选的。留空时executable() 会按以下顺序自动定位命令在系统PATH中查找在常见安装目录中逐一探测~/.local/bin、~/.opencode/bin、~/.grok/bin、~/.claude/local、/opt/homebrew/bin、/usr/local/bin、Windows 下的%APPDATA%\npmWindows 上会自动补.exe后缀若配置了Executable则必须是绝对路径否则报错。对于.cmd/.bat/.ps1这类 shell 垫片shimWox 不会直接执行——它会通过 Node 解析对应的 npm 入口脚本例如 Claude Code 的anthropic-ai/claude-code/cli.js避免引入不可控的 shell 环境。这一点在 newCommand 中通过shell.BuildCommandContext构建进程树并把取消信号绑定到整棵进程树确保中断时不留孤儿进程。会话与登录态CLI provider 的运行模式是“临时工作区 单次会话”每次请求创建独立的临时工作目录wox-ai-*请求结束后清理见 runTurn直接继承本机命令的登录态凭证由命令自身管理Wox 不读取、不存储 CLI 的凭据模型列表通过调用命令自身的接口探测例如 Claude Code 会执行claude auth status --json检查登录状态成功后才返回sonnet、opus、haiku三个模型名见 provider_cli_claudecode.go请求期间会拉起一个内部 tool bridgeMCP HTTP 服务把 Wox 的内置工具文件读写、Shell、Web 搜索等以mcp__wox__*工具的形式暴露给 CLI从而实现“在 Wox 里用 AI 操作电脑”。品牌图标Wox 能识别已安装的 CLI 并显示对应品牌图标。映射逻辑在 installedCLIIconcodex-cli使用 OpenAI 图标、claude-cli使用 Claude Code 图标、grok-cli使用 Grok 图标、opencode-cli使用 OpenCode 图标未识别的命令回退到通用终端图标。这也是设置列表中“API 与已安装 CLI 分组 图标区分”体验的底层来源排序逻辑上 API provider 在前、CLI 在后组内按字母序排列见 sortAIProviderOptions。保存后如何验证 Provider 可用每个 Provider 实现都要满足 Provider 接口其中两个方法与“验证可用性”直接相关Models(ctx)返回该 provider 可用的模型列表。API provider 通过GET /models拉取CLI provider 通过探测本机命令获取。Ping(ctx)连通性探测。API provider 的实现是调用一次模型列表接口CLI provider 则直接复用Models探测逻辑。设置界面中的Status列就是基于这套机制实时显示连通状态的——如果某个 provider 标红通常意味着凭据、Host 或模型名有问题。安全注意事项把 API key 当作密码处理AIProviders配置中保存的ApiKey是明文凭据不要与他人共享配置文件也不要截图外发。付费 provider 会对每次请求计费包括 AI 命令执行和主题生成这类“看起来像工具调用”的场景也会消耗 token 产生费用。只使用可信的自定义 hostWox 会把 prompt 内容发送到你填写的Host地址恶意或不可信的地址意味着你的输入会被第三方截获。注意敏感数据边界不要把敏感剪贴板内容、选中文本或私有文件发送给在线模型除非你确认这符合自己的工作流与 provider 的数据政策。特别是涉及企业代码、个人隐私信息的场景建议优先选择本地部署方案如 Ollama或已明确数据政策的自托管服务。排查清单如果某个 AI 功能没有返回结果按以下顺序检查Provider 是否被选中确认 provider 已启用并在具体功能AI 对话、AI 命令等的模型选择中选中了它而不是只添加未使用。凭据是否有效API provider 检查 API key 是否有效CLI provider 确认对应命令已安装、在PATH中或Executable指向绝对路径、且已完成登录例如claude需要先claude auth login。模型名是否被接受模型名必须与 provider 支持的范围一致。CLI provider 可在设置中刷新模型列表API provider 可用Ping状态列辅助判断。自定义 host 是否可达如果你填了Host用浏览器或 curl 确认该地址可访问、协议正确HTTPS/HTTP、路径完整部分兼容服务需要/v1前缀。网络是否可用API provider 依赖出网能力企业网络、代理环境下需要确保 Wox 的流量可正常到达目标服务。结语Wox 的 AI 设置在设计上刻意保持克制不强制绑定任何一家模型厂商而是通过“API 已安装 CLI”双通道的 Provider 抽象让用户自由选择在线服务、聚合路由、本地部署或桌面编程助手。理解AIProvider的字段含义与providerFactories的注册机制后你不仅能顺利配置还能在需要时接入任何 OpenAI 兼容服务或排查出绝大多数“AI 无响应”的问题。进一步了解 AI 命令的编写与主题生成可继续阅读 AI 命令 与 主题生成。赞分享桌面应用AI 应用插件系统【免费下载链接】WoxA cross-platform launcher that simply works项目地址https://gitcode.com/gh_mirrors/wo/Wox点击查看免费下载相关推荐ET框架帧同步完整指南用3个关键机制消除多人对战的瞬移与不同步ET框架帧同步完整指南用3个关键机制消除多人对战的瞬移与不同步 做Unity3D多人对战最怕的就是角色瞬移、技能不同步。ET框架Unity3D客户端 游戏开发后端微服务云原生Freetar未来路线图移动UX优化与PWA支持即将到来的5大新功能Freetar未来路线图移动UX优化与PWA支持即将到来的5大新功能 Freetar作为终极吉他ultimate guitar.com的替代前端为吉他包管理器CLIwezterm 字体大小重置完全指南ResetFontSize 键位配置与底层实现解析wezterm 字体大小重置完全指南ResetFontSize 键位配置与底层实现解析 本文基于 wezterm 官方文档 ResetFontSize htt桌面应用开发工具跨平台上一篇大麦网抢票脚本终极指南从API逆向到实战部署的完整解决方案下一篇embedded-can 控制器局域网完全指南从帧结构到错误处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考