配置 Agent MCP 与 Skill

完成在 TypeX 桌面端启用 MCP 后，还需完成以下两步，才能让 AI 助手正常使用 TypeX：

配置 Agent MCP — 将 AI 工具接入 TypeX MCP 端点
配置 Skill — 教会 AI 如何正确使用 TypeX 工具

两步缺一不可。MCP 提供工具调用能力，Skill 文件提供操作流程、确认规则和错误处理。

端点地址： http://127.0.0.1:52222/mcp/

配置 Agent MCP

TypeX MCP 使用 Streamable HTTP 传输协议。只需将 Agent 指向本地端点，无需 command、args 或 env 字段。

配置前请确认：

TypeX 桌面端已打开且 MCP 已启用
你的 Agent 支持 HTTP / Streamable HTTP MCP 传输

以下示例按 Agent 类型分组。通用型 Agent 适合日常消息收发和自动化；面向开发的 Agent 单独列出，供在编程 IDE 中使用。

通用型 Agent

Claude Code

Claude Code 是面向终端的通用 AI 助手，适合日常消息、日程、调研和自动化任务。

配置文件位置：

作用范围	路径
全局（所有项目）	`~/.claude.json` → 顶层 `mcpServers`
项目（当前仓库）	项目根目录 `.mcp.json`

操作步骤：

创建或打开对应作用范围的配置文件
添加 typex 条目，必须包含 "type": "http"（Claude Code 要求）
保存文件
在终端运行 claude mcp list，确认 typex 出现在列表中
若未出现，运行 claude /doctor 检查配置格式错误

{
  "mcpServers": {
    "typex": {
      "type": "http",
      "url": "http://127.0.0.1:52222/mcp/"
    }
  }
}

替代方式 — CLI 一行命令：

claude mcp add typex --type http --url http://127.0.0.1:52222/mcp/

OpenClaw

OpenClaw 是运行在本地的个人 AI Agent，可通过 MCP 连接消息渠道、自动化任务和外部工具。

配置文件位置：

作用范围	路径
全局	`~/.openclaw/openclaw.json` → `mcp.servers`

操作步骤：

打开 ~/.openclaw/openclaw.json（若不存在则创建）
在 mcp.servers 下添加 typex 条目，设置 transport: "streamable-http"
保存文件
运行 openclaw mcp list，确认 typex 出现
开启新会话（聊天中输入 /new）或运行 openclaw mcp reload 使配置生效

{
  "mcp": {
    "servers": {
      "typex": {
        "url": "http://127.0.0.1:52222/mcp/",
        "transport": "streamable-http"
      }
    }
  }
}

替代方式 — CLI 一行命令：

openclaw mcp set typex '{"url":"http://127.0.0.1:52222/mcp/","transport":"streamable-http"}'

Hermes

Hermes 是通用 AI Agent，支持持久记忆、定时任务和多渠道消息。

配置文件位置：

作用范围	路径
全局	`~/.hermes/config.yaml` → `mcp_servers`

操作步骤：

打开 ~/.hermes/config.yaml（不确定时可运行 hermes config edit）
在 mcp_servers 下添加 typex 条目
保存文件
在 Hermes 聊天中运行 /reload-mcp 使配置生效
让 Agent 列出 MCP 工具，确认 TypeX 工具可用

mcp_servers:
  typex:
    url: 'http://127.0.0.1:52222/mcp/'

替代方式 — CLI 一行命令：

hermes mcp add typex --url http://127.0.0.1:52222/mcp/

面向开发的 Agent

以下 Agent 内置于编程 IDE，适合在开发环境中操作 TypeX。

Codex

Codex 是 OpenAI 的编程 Agent，集成在 IDE 工作流中。

操作步骤：

打开 Codex 设置，进入 MCP 服务器配置区域
添加新的 HTTP MCP 服务器，URL 填 http://127.0.0.1:52222/mcp/
保存配置，若提示则重启 Codex

Codex MCP 设置

若你的 Codex 版本支持 JSON 配置文件，可使用：

{
  "mcpServers": {
    "typex": {
      "url": "http://127.0.0.1:52222/mcp/"
    }
  }
}

VS Code（GitHub Copilot Agent）

VS Code 配合 GitHub Copilot Agent 是面向开发的助手，内置 MCP 支持。

配置文件位置：

作用范围	路径
工作区	`.vscode/mcp.json`
用户配置	运行命令 MCP: Open User Configuration

操作步骤：

运行 MCP: Open Workspace Folder MCP Configuration（或用户级配置命令）
在 servers 下添加 typex 条目（VS Code 使用 servers，不是 mcpServers）
保存文件
打开 Chat 面板，确认 TypeX MCP 工具出现在 MCP 服务器列表中

{
  "servers": {
    "typex": {
      "type": "http",
      "url": "http://127.0.0.1:52222/mcp/"
    }
  }
}

其他支持 MCP 的 Agent

Cursor、Trae、Cline 等 IDE 扩展也支持 MCP，JSON 格式略有差异：

Agent	配置路径	HTTP 字段
Cursor	`~/.cursor/mcp.json` 或 `.cursor/mcp.json`	`url`
Trae	`.trae/mcp.json`	`url`
Cline	Cline 面板 → Configure MCP Servers	`url` + `"type": "streamableHttp"`

通用模板（适用于 Cursor、Trae 等）：

{
  "mcpServers": {
    "typex": {
      "url": "http://127.0.0.1:52222/mcp/"
    }
  }
}

部分 Agent 需要额外字段 — 例如 Claude Code 需要 "type": "http"，VS Code 使用 servers 而非 mcpServers。请查阅对应 Agent 的 MCP 文档并调整字段名。

配置 Skill

Skill 文件教会 AI 如何使用 TypeX MCP 工具——先搜索再发送、确认规则、歧义处理、错误恢复。没有 Skill 时，AI 虽有工具权限，但可能跳过重要的安全检查。

下载 Skill 文件

📥 下载 SKILL 文件 (Markdown)

文件包含 YAML 前置元数据（name: typex-use）和详细使用说明。导入时请保留前置元数据部分。

导入 Skill

通用步骤（所有 Agent）：

下载 Skill 文件（上方链接）
放入 Agent 的 Skill / 规则 / 指令目录（见下方各 Agent 路径）
若 Agent 要求特定文件名，重命名为 SKILL.md
重启或重新加载 Agent

通用型 Agent

Claude Code

打开 ~/.claude/CLAUDE.md（全局）或项目根目录的 CLAUDE.md
在 ## TypeX MCP 标题下，追加下载的 Skill 文件完整内容
保存文件 — Claude Code 启动时会读取 CLAUDE.md

OpenClaw

mkdir -p ~/.openclaw/skills/typex-use
cp ~/Downloads/typex-mcp-skill.md ~/.openclaw/skills/typex-use/SKILL.md

可选：在 ~/.openclaw/openclaw.json 中启用：

{
  "skills": {
    "entries": {
      "typex-use": {
        "enabled": true
      }
    }
  }
}

开启新会话（/new），运行 openclaw skills list 验证

Hermes

mkdir -p ~/.hermes/skills/typex-use
cp ~/Downloads/typex-mcp-skill.md ~/.hermes/skills/typex-use/SKILL.md

或者将 Skill 内容追加到 ~/.hermes/SOUL.md 的 ## TypeX MCP 章节下
开启新的 Hermes 会话使配置生效

面向开发的 Agent

Codex

在 Codex 设置中将 Skill 文件导入为自定义指令或项目级 Agent 配置，将完整 Markdown 内容粘贴到指令字段中。

VS Code

创建或编辑项目根目录的 .github/copilot-instructions.md（工作区级别）
粘贴下载的 Skill 文件完整内容
保存并开启新的 Copilot Agent 会话

其他 Agent

Agent	Skill 导入路径
Cursor	`~/.cursor/skills/typex-use/SKILL.md`
Trae	项目根目录 `.trae/project_rules.md`
Cline / Roo Code	扩展的 Custom Instructions 设置

验证配置

检查 MCP 连接：

让 AI 列出可用的 MCP 工具，应能看到 TypeX 的消息搜索、发送消息、群管理等工具。

检查 Skill 集成：

尝试如下指令：

"搜索我 TypeX 里和产品相关的群"

预期行为：

AI 先搜索再操作（不会猜测群名）
多个匹配项 → 请你选择
TypeX 未运行 → 报告明确错误并提示在设置中启用 MCP

若 MCP 工具可见但行为不正确，通常是 Skill 未配置 — 请完成上方的 Skill 配置。

配置 Agent MCP​

通用型 Agent​

Claude Code​

OpenClaw​

Hermes​

面向开发的 Agent​

Codex​

VS Code（GitHub Copilot Agent）​

其他支持 MCP 的 Agent​

配置 Skill​

下载 Skill 文件​

导入 Skill​

通用型 Agent​

Claude Code​

OpenClaw​

Hermes​

面向开发的 Agent​

Codex​

VS Code​

其他 Agent​

验证配置​

配置 Agent MCP

通用型 Agent

Claude Code

OpenClaw

Hermes

面向开发的 Agent

Codex

VS Code（GitHub Copilot Agent）

其他支持 MCP 的 Agent

配置 Skill

下载 Skill 文件

导入 Skill

通用型 Agent

Claude Code

OpenClaw

Hermes

面向开发的 Agent

Codex

VS Code

其他 Agent

验证配置