企业官网建设流程全解析

• 桌面应用
• AI 应用
• 插件系统

Wox 的 AI 能力（AI 对话、AI 命令、AI 辅助 Emoji 搜索、听写润色、AI 生成主题）全部是可选的，核心前提是正确配置一个可用的 AI Provider。本文以官方指南 AI 设置 为骨架，结合wox.core/ai与wox.core/setting的源码实现，讲透 Provider 的添加步骤、每个字段的真实含义与存储结构，以及 API 与 CLI 两类 Provider 各自的底层工作机制，让你既能快速上手配置，也能在遇到问题时按图索骥排查。

Wox AI 设置界面

为什么需要配置 Provider

AI 功能在 Wox 中是按需启用的。只有当你想使用以下任一能力时，才需要进入设置 -> AI配置 Provider：

• AI 对话：与模型进行多轮聊天（对应系统插件 chat）
• AI 命令：通过模板或自然语言触发执行命令（见 AI 命令）
• AI 辅助 Emoji 搜索：用自然语言描述查找表情符号
• 听写润色：对语音识别结果进行 AI 优化（见 听写）
• AI 生成主题：根据描述生成或调整界面主题（见 主题生成）

如果以上功能你都不需要，可以完全跳过本节，不影响 Wox 的其余功能。

添加 Provider 的五个步骤

1. 打开设置 -> AI。
2. 点击添加。
3. 选择APIprovider，或已安装的 CLIprovider。
4. 填写名称、凭据或 CLI 信息、模型，以及需要时的自定义 host。
5. 保存后，在具体功能（如 AI 对话、AI 命令）中选择这个 provider。

Provider 列表会分成API和已安装的 CLI两组：

• API provider：使用密钥（API key）和可选的自定义 host，由 Wox 直接发起 HTTP 请求调用模型服务。
• 已安装的 CLI provider：复用本机已经安装的命令行工具（如桌面编程助手），Wox 负责以子进程方式驱动它，并透传你已有的登录态。

列表本身支持搜索，便于在 provider 数量较多时快速定位；Wox 能识别的 CLI 会显示对应品牌图标（详见下文“品牌图标”小节）。

字段含义详解

官方指南给出了五个核心字段，下表在原文基础上补充了其在 AIProvider 结构体 中的对应存储字段与补充说明：

除了官方文档列出的五项，源码中还暴露了两个值得了解的进阶字段：

• Alias（Alias）：同一 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 在包初始化时把自己的工厂函数写入providerFactories映射，运行时通过 NewProvider 按名称查找工厂并实例化。这也解释了为什么“Provider 名称”必须从预置列表中选择——它直接对应providerFactories中的注册键。

值得注意的实现细节：所有 OpenAI 兼容 provider 共享一套流式解析逻辑，包括：

• 推理内容分离：流式返回时统一识别reasoning与reasoning_content两个字段，把思考过程与最终答案分开呈现（见 reasoningExtraFieldNames）；
• 内容标签路由：部分模型用<think>...</think>标签包裹思考内容，解析器会将其剥离并归入推理区，不混入用户可见答案（见 streamContentTags）；
• Tool Call 参数归一化：对模型返回的工具调用参数做类型修正、必填参数补齐、下划线命名对齐等处理（见 normalizeArguments）。

这意味着：只要目标服务兼容 OpenAI 的/v1/chat/completions协议，即使它不在上面的预置列表里，理论上也可以通过选择某个兼容 provider 并填写自定义 Host 来接入（例如各类代理服务、本地服务或公司内部网关）。

已安装 CLI Provider：驱动本机命令

CLI provider 是 Wox 的一个特色：它不把 API key 交给 Wox，而是直接驱动你本机已经安装并登录好的命令行工具。当前注册的 CLI provider 有四种：

可执行文件发现机制

CLI provider 配置里填的Executable是可选的。留空时，executable() 会按以下顺序自动定位命令：

1. 在系统PATH中查找；
2. 在常见安装目录中逐一探测：~/.local/bin、~/.opencode/bin、~/.grok/bin、~/.claude/local、/opt/homebrew/bin、/usr/local/bin、Windows 下的%APPDATA%\npm（Windows 上会自动补.exe后缀）；
3. 若配置了Executable，则必须是绝对路径，否则报错。

对于.cmd/.bat/.ps1这类 shell 垫片（shim），Wox 不会直接执行——它会通过 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 bridge（MCP HTTP 服务），把 Wox 的内置工具（文件读写、Shell、Web 搜索等）以mcp__wox__*工具的形式暴露给 CLI，从而实现“在 Wox 里用 AI 操作电脑”。

品牌图标

Wox 能识别已安装的 CLI 并显示对应品牌图标。映射逻辑在 installedCLIIcon：codex-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 产生费用。
• 只使用可信的自定义 host：Wox 会把 prompt 内容发送到你填写的Host地址，恶意或不可信的地址意味着你的输入会被第三方截获。
• 注意敏感数据边界：不要把敏感剪贴板内容、选中文本或私有文件发送给在线模型，除非你确认这符合自己的工作流与 provider 的数据政策。特别是涉及企业代码、个人隐私信息的场景，建议优先选择本地部署方案（如 Ollama）或已明确数据政策的自托管服务。

排查清单

如果某个 AI 功能没有返回结果，按以下顺序检查：

1. Provider 是否被选中：确认 provider 已启用，并在具体功能（AI 对话、AI 命令等）的模型选择中选中了它，而不是只添加未使用。
2. 凭据是否有效：API provider 检查 API key 是否有效；CLI provider 确认对应命令已安装、在PATH中（或Executable指向绝对路径）、且已完成登录（例如claude需要先claude auth login）。
3. 模型名是否被接受：模型名必须与 provider 支持的范围一致。CLI provider 可在设置中刷新模型列表；API provider 可用Ping状态列辅助判断。
4. 自定义 host 是否可达：如果你填了Host，用浏览器或 curl 确认该地址可访问、协议正确（HTTPS/HTTP）、路径完整（部分兼容服务需要/v1前缀）。
5. 网络是否可用：API provider 依赖出网能力；企业网络、代理环境下需要确保 Wox 的流量可正常到达目标服务。

结语

Wox 的 AI 设置在设计上刻意保持克制：不强制绑定任何一家模型厂商，而是通过“API + 已安装 CLI”双通道的 Provider 抽象，让用户自由选择在线服务、聚合路由、本地部署或桌面编程助手。理解AIProvider的字段含义与providerFactories的注册机制后，你不仅能顺利配置，还能在需要时接入任何 OpenAI 兼容服务，或排查出绝大多数“AI 无响应”的问题。进一步了解 AI 命令的编写与主题生成，可继续阅读 AI 命令 与 主题生成。

• 桌面应用
• AI 应用
• 插件系统