一、前言

Halo 是一款现代化的开源建站工具，很多站长都会用它来写博客、搭知识库。日常写文时，我们往往需要手动登录后台、复制粘贴、调整格式，流程繁琐。如果能让 AI 直接读写 Halo 的内容，写作效率会提升一大截。

WorkBuddy 是腾讯出品的全场景 AI 工作台，支持通过连接器（MCP）接入第三方服务。MCP（Model Context Protocol，模型上下文协议）是一套让 AI 与外部系统交互的开放标准。只要 Halo 提供了 MCP Server，WorkBuddy 就能直接调用它来管理文章、分类、标签等内容。

本文将以 Halo 官方 MCP Server 插件为例，手把手带你在 WorkBuddy 中配置 Halo 连接器，实现「用一句话让 AI 帮你写文章并发布到 Halo」。配置完成后，你甚至可以让 AI 直接创建、修改、发布文章，全程无需打开后台。

二、准备工作

在正式开始配置之前，需要先确认以下两件事：

2.1 确认 Halo 版本

Halo MCP Server 依赖 Halo 2.x 及以上版本，且站点需要通过 HTTPS 对外访问。如果你的站点还是 HTTP，建议先配置 SSL 证书（可通过 Nginx、Caddy 或 1Panel 一键申请）。

打开 Halo 后台，在「系统」→「关于」中即可查看当前版本号。

2.2 安装 MCP Server 插件

Halo 的 MCP 能力由官方插件 MCP Server 提供，安装步骤如下：

  1. 登录 Halo 后台，进入「插件」→「应用市场」。

  2. 在搜索框中输入「MCP Server」，找到名为 MCP Server（应用 ID 形如 app-ybv96zol）的插件。

  3. 点击「安装」，等待安装完成后点击「启用」。

插件启用后，Halo 会自动注册一个 MCP 服务端点，格式如下：

https://你的域名/mcp

例如你的站点是 https://blog.example.com，那么 MCP 端点就是 https://blog.example.com/mcp。

注意：MCP 服务管理入口仅对 Halo 超级管理员开放，请使用超级管理员账号登录后台进行配置。

三、生成 Halo 访问密钥

Halo 的 MCP 服务采用 Bearer Token 鉴权，我们需要先创建一个访问密钥。

3.1 创建密钥

  1. 在 Halo 后台进入 MCP Server 插件的管理页面。

  2. 找到「MCP 密钥」区域，点击「新建」。

  3. 为密钥填写一个易识别的名称，例如 WorkBuddy。

  4. 在工具授权中，勾选你希望 AI 能够操作的工具（如文章管理、分类管理、标签管理等）。建议遵循最小权限原则，只勾选实际需要的工具。

  5. 点击保存，系统会生成一串以 hmcp_ 开头的密钥。

重要：访问密钥只会在创建或轮换后显示一次，请立即复制并妥善保存。关闭页面后将无法再次查看，只能重新生成。

3.2 密钥安全提醒

  • 为每个客户端（如 WorkBuddy、Claude Code）创建独立的最小权限密钥，便于单独吊销。

  • 不要把密钥提交到 Git 仓库、写入日志或发送到公开渠道。

  • 如果密钥疑似泄露，请立即在插件中「轮换」或删除并重新创建。

  • IP 白名单只是附加防护，不能替代 HTTPS 和最小权限授权。

四、在 WorkBuddy 中配置连接器

拿到密钥后，就可以在 WorkBuddy 中把 Halo 注册为一个自定义 MCP 连接器了。WorkBuddy 的 MCP 配置文件位于用户目录下：

~/.workbuddy/mcp.json

在 Windows 上，该路径通常是 C:\Users\你的用户名\.workbuddy\mcp.json；macOS / Linux 则为 ~/.workbuddy/mcp.json。如果文件不存在，可以手动新建。

4.1 方式一：直接编辑 mcp.json（推荐）

Halo 官方 MCP Server 采用 Streamable HTTP 传输方式，配置时只需填入端点 URL 和鉴权请求头。打开 ~/.workbuddy/mcp.json，写入以下内容：

{
  "mcpServers": {
    "halo": {
      "type": "http",
      "url": "https://你的域名/mcp",
      "headers": {
        "Authorization": "Bearer hmcp_你的密钥"
      }
    }
  }
}

把其中的 https://你的域名/mcp 替换为你的 Halo MCP 端点，hmcp_你的密钥 替换为第 3 步生成的密钥。

如果你已经配置过其他 MCP 服务，只需把 "halo" 这一段合并进已有的 mcpServers 对象中，不要覆盖其他配置。

4.2 方式二：通过界面粘贴配置

如果你不习惯手动编辑文件，也可以通过 WorkBuddy 界面完成：

  1. 打开 WorkBuddy，点击左侧「专家·技能·连接器」→ 找到「连接器 / Connectors」相关入口。

  2. 进入「自定义连接器（Custom Connectors）」区域。

  3. 点击「添加MCP」。

  4. 粘贴上面那段 JSON 配置（即 Cursor 的配置方式），将 TOKEN 变量替换为「MCP 密钥内容」，然后点击「保存」。

4.3 启用并信任连接器

无论使用哪种方式，配置写入后都需要手动启用：

  1. 回到 WorkBuddy 左侧边栏，点击「连接器」（插头/拼图图标）。

  2. 在页面右上角找到「自定义连接器」入口——通过 mcp.json 手动添加的服务只会出现在这里，不会混在预设连接器列表中。

  3. 在自定义连接器列表中找到 halo，点击右侧的「信任 / Trust」按钮。

  4. 信任后，状态会变为「已连接 / 已启用」，表示 Halo 的工具已成功映射到 WorkBuddy。

提示：如果信任后列表里看不到 halo，重启一次 WorkBuddy 让它重新加载配置，再回到自定义连接器中查看即可。

五、验证连接是否成功

启用连接器后，建议先做一次简单验证，确认 WorkBuddy 真的能访问你的 Halo 站点。在 WorkBuddy 对话区输入类似下面的指令：

帮我列出 Halo 站点最新发布的 5 篇文章标题

如果配置正确，WorkBuddy 会调用 Halo 的 halo_list_posts 工具，并返回文章列表。你也可以试着问：

列出 Halo 中所有的文章分类和标签

能正常返回数据，就说明连接已经打通了。

六、能用 Halo 连接器做什么

配置完成后，WorkBuddy 就能像操作本地文件一样管理你的 Halo 站点。常用能力包括：

能力分类

可用操作

文章管理

列出 / 创建 / 更新 / 发布 / 取消发布文章，获取与修改文章正文

分类管理

列出 / 创建 / 更新 / 删除分类，按分类筛选文章

标签管理

列出 / 创建 / 更新 / 删除标签，按标签筛选文章

评论管理

查看评论列表、发表评论与回复

附件管理

列出附件、通过 URL 上传附件、删除附件

独立页面

列出 / 创建 / 更新 / 发布单页面及其正文

搜索与统计

全站全文搜索、获取站点统计数据

菜单与信息

列出菜单 / 菜单项、列出插件与用户信息

举个实际例子：你可以直接对 WorkBuddy 说「帮我写一篇介绍 Docker 的入门文章，发布到 Halo 的『技术』分类下，并打上『Docker』标签」，它就会自动完成撰写、建草稿、设置分类标签的整套流程。如果希望更稳妥，可以先让它只创建草稿，你在后台确认无误后再手动发布。

七、常见问题排查

7.1 连接失败或报 401（401 Unauthorized）

  • 检查密钥是否填写完整，注意 Bearer 与密钥之间有一个空格。

  • 确认密钥没有被误删或轮换——密钥轮换后旧密钥立即失效。

  • 确认创建密钥时勾选了对应的工具授权，未授权的工具调用会被拒绝。

7.2 报 404 或找不到端点

  • 确认 MCP Server 插件已启用，端点路径为 https://你的域名/mcp。

  • 检查 URL 是否多写或少写了 /mcp 后缀。

  • 如果 Halo 位于反向代理之后，确认代理已正确转发 /mcp 路径，并允许长连接（Streamable HTTP）。

7.3 自定义连接器列表里没有 halo

  • 重启一次 WorkBuddy，让配置重新加载。

  • 检查 mcp.json 是否为合法 JSON（括号、逗号、引号是否闭合）。可以用在线 JSON 校验工具检查一遍。

  • 确认配置文件路径正确：用户级为 ~/.workbuddy/mcp.json，注意不是 .mcp.json（后面没有多余的点）。

7.4 操作被拒绝或权限不足

  • 回到 Halo MCP Server 插件中，检查该密钥绑定的工具列表，补充勾选所需工具。

  • 确认执行操作时使用的 Halo 账号具有对应的内容管理权限。

八、安全与最佳实践

  • 最小权限：仅授权 AI 实际需要的工具。如果只是让它写草稿，就不要给它删除文章、删除分类的权限。

  • 密钥隔离：为 WorkBuddy 单独创建密钥，与 Claude Code、Codex 等其他客户端分开，便于单独吊销。

  • 强制 HTTPS：MCP 端点务必走 HTTPS，避免密钥在传输中被窃听。

  • 只信任可信代理：Halo 处于反向代理之后时，只信任可信代理写入的 Forwarded 与 X-Forwarded-* 请求头，并阻止客户端绕过代理直接访问 Halo。

  • 先草稿后发布：初次使用时，建议让 AI 只创建草稿，人工确认后再发布，避免误操作直接上线。

  • 定期审计：定期查看密钥列表与授权工具，及时清理不再使用的密钥。

九、总结

通过 Halo 官方的 MCP Server 插件配合 WorkBuddy 的自定义连接器，我们就能把 Halo 站点无缝接入 AI 工作流。整个流程可以归纳为四步：

  1. 在 Halo 中安装并启用 MCP Server 插件，拿到 MCP 端点。

  2. 在插件中创建最小权限的访问密钥（仅显示一次，务必保存）。

  3. 在 ~/.workbuddy/mcp.json 中写入 Halo 的 HTTP 连接器配置。

  4. 在 WorkBuddy「自定义连接器」中点击信任并启用。

配置完成后，写文章、建分类、查数据这些原本要在后台点来点去的操作，都可以用一句自然语言交给 WorkBuddy 完成。让 AI 成为你的 Halo 管理助手，把时间留给真正重要的创作本身。