mx-link（MX 链接）

Office Link — 第三方账号链接与 API 代理

通过 mx_link 工具，统一管理第三方平台的账号链接和 API 调用。Bot 不直接持有 OAuth token，所有请求通过 MorphixAI 服务端代理，自动管理凭据。

重要：优先使用已有的专用 skill。 对于已有专用 skill 的平台，必须优先使用对应 skill（如 jira-workflow、gitlab-workflow、outlook-email 等）而非 mx_link 的 proxy。专用 skill 自动处理 URL 构建、认证、数据格式转换，更可靠且更简洁。mx_link 仅用于： 1. 账号管理（查看/链接账号） 2. 调用尚未有专用 skill 的平台 API（如 Slack、Discord、Zoom、Google Sheets 等）

前置条件

1. 安装插件: openclaw plugins install openclaw-morphixai
2. 获取 API Key: 访问 morphix.app/api-keys 生成 mk_xxxxxx 密钥
3. 配置环境变量: export MORPHIXAI_API_KEY="mk_your_key_here"
4. 链接账号: 访问 morphix.app/connections 管理账号，或使用下方 mx_link: connect 操作

工具选择规则

用户请求操作某个平台
  ├── 有专用 skill？ → 使用专用 skill（见下方列表）
  ├── 账号未链接？ → mx_link: connect 引导授权
  └── 无专用 skill？ → mx_link: proxy 兜底代理调用

核心能力

1. 账号管理 — 查看已链接账号、引导用户链接新账号
2. API 代理 — 通过已链接账号安全调用第三方 API（仅用于无专用工具的平台）
3. 统一入口 — 支持 40+ 第三方平台，无需各自配置

支持的平台

完整列表可通过 mx_link 的 list_apps action 获取。

使用流程

1. 检查已链接账号

使用 mx_link 工具:
  action: list_accounts
  app_name: "github"  (可选，筛选特定平台)

2. 引导用户链接新账号

如果用户需要的平台尚未链接：

使用 mx_link 工具:
  action: connect
  app: "github"  (必须指定目标应用)

返回一个 OAuth 授权链接，发送给用户在浏览器中完成授权。链接有效期 4 小时。

重要：app 参数必须提供。 后端返回的链接格式为： `` https://pipedream.com/_static/connect.html?token=ctok_xxx&connectLink=true ` 该链接如果缺少 app 参数则无法访问。当传入 app 参数后，生成的链接会包含 &app=<app_name>，例如： ` https://pipedream.com/_static/connect.html?token=ctok_xxx&connectLink=true&app=gitlab ` 只有带 app` 参数的链接才能正常打开授权页面。

3. 通过代理调用第三方 API（仅限无专用 skill 的平台）

再次强调： 对于已有专用 skill 的平台（见下方完整列表），必须使用专用 skill。proxy 仅作为无专用 skill 时的兜底方案。

用户授权完成后，对于没有专用 skill 的平台，用 proxy action 调用第三方 API：

示例：查询 Slack 频道消息（无专用工具，使用 proxy）

使用 mx_link 工具:
  action: proxy
  account_id: "apn_xxx"   (从 list_accounts 获取)
  method: "GET"
  url: "https://slack.com/api/conversations.history"
  params: { "channel": "C01234567", "limit": 10 }

示例：创建 Google Sheets 行（无专用工具，使用 proxy）

使用 mx_link 工具:
  action: proxy
  account_id: "apn_xxx"
  method: "POST"
  url: "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}:append"
  params: { "valueInputOption": "USER_ENTERED" }
  body: {
    "values": [["2026-02-25", "完成 SDK 集成", "通过"]]
  }

已有专用 Skill（必须优先使用）

以下平台已有专用 skill，禁止使用 mx_link: proxy 替代：

专用 skill 的优势：

• 自动账号检测 — 无需手动查 account_id
• 自动 URL 构建 — 无需知道 API 端点
• 自动格式转换 — 如 Jira Markdown→ADF、Confluence Storage Format
• 语义化参数 — jql: "..." 比手写 REST URL 更直观
• 内置工作流 — 每个 skill 包含常见场景的操作步骤

mx_link 的 proxy action 仅适用于上述列表之外的应用（如 Slack、Discord、Zoom、Google Sheets 等）。

常见场景

有专用 skill → 直接使用对应 skill

# 查 Jira 待办 → 使用 jira-workflow skill
mx_jira: action: search_issues,
  jql: "assignee = currentUser() AND status != Done ORDER BY updated DESC"

# 查 GitLab MR → 使用 gitlab-workflow skill
mx_gitlab: action: list_merge_requests, state: "opened"

# 查 GitHub 仓库 → 使用 github-workflow skill
mx_github: action: list_repos, sort: "updated", per_page: 5

# 查今日日程 → 使用 outlook-calendar skill
mx_outlook_calendar: action: get_calendar_view,
  start_date_time: "2026-02-25T00:00:00Z", end_date_time: "2026-02-25T23:59:59Z"

无专用 skill → 兜底使用 mx_link proxy

# Slack 消息（无专用 skill）→ 使用 proxy
1. mx_link: list_accounts, app_name="slack"
2. mx_link: proxy, account_id="apn_xxx", method="GET",
   url="https://slack.com/api/conversations.history",
   params={"channel":"C01234567","limit":10}

# Google Sheets（无专用 skill）→ 使用 proxy
1. mx_link: list_accounts, app_name="google_sheets"
2. mx_link: proxy, account_id="apn_xxx", method="GET",
   url="https://sheets.googleapis.com/v4/spreadsheets/{id}/values/Sheet1"

账号未链接 → 引导连接

1. mx_link: list_accounts, app_name="slack"
     → 返回空列表
2. mx_link: connect, app: "slack"
     → 返回 OAuth 授权链接，发给用户
3. 用户完成授权后，重新操作

错误处理

• 401 — API Key 无效或已过期，提示用户到 MorphixAI 控制台 (https://morphix.app/api-keys) 重新创建
• 403 — API Key 缺少权限范围，需要全选 scope（user:profile:read、link）
• 账号未链接 — 使用 connect action 引导用户授权
• 第三方 API 错误 — proxy 返回第三方原始错误，根据各平台文档处理

配置

环境变量

# ~/.openclaw/.env
MORPHIXAI_API_KEY=mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

或通过 openclaw.json

{
  "morphix": {
    "apiKey": "mk_xxx"
  }
}

获取 API Key

1. 登录 MorphixAI 控制台 https://morphix.app/api-keys
2. 点击「创建 API Key」，Scope 全选
3. 复制保存 Key（只显示一次）

最佳实践

1. 专用 skill 优先 — 有专用 skill 的平台必须用对应 skill，proxy 只作为无专用 skill 时的兜底
2. 先查后连 — 总是先用 list_accounts 检查是否已链接，避免重复引导用户授权
3. 缓存 account_id — 在对话中缓存 account_id，无需每次都查询
4. 组合使用 — 一个对话中可以跨 skill 操作（先用 jira-workflow 查任务，再用 mx_link: proxy 发 Slack 通知）
5. 优雅降级 — 如果 API Key 未配置，提示用户设置环境变量