通过 OpenClaw 使用应用

了解如何让用户通过 OpenClaw 使用你的应用，以及背后的 MCP 配置与用户级鉴权方式

本指南介绍如何让用户通过 OpenClaw 使用你的应用。你需要为应用提供一个标准 MCP 服务，并在 Labs 中完成 integration 配置，这样 OpenClaw 等 agent 就可以通过 SecondMe 调用你的应用能力，而平台会在运行时把用户级 access token 转发给你的服务。

SecondMe 已提供 OpenClaw Skill。完成接入后，用户可以直接通过 OpenClaw 发现并使用你的应用能力，这会为应用带来更多曝光、调用量和实际使用。

调用流程

1. 为应用准备 MCP 服务

要让 OpenClaw 使用你的应用，首先需要为应用提供一个标准 MCP Server，并暴露至少一个 HTTP MCP endpoint，例如：

POST https://your-app.example.com/api/mcp

这个 endpoint 至少应支持以下 JSON-RPC 方法：

tools/list
tools/call

tools/list 返回可供 agent 调用的工具列表，tools/call 负责执行指定工具。

最小 tools/list 请求示例：

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list"
}

示例返回：

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "tools": [
      {
        "name": "doudizhu_game_start",
        "description": "Start or resume a Dou Dizhu game",
        "inputSchema": {
          "type": "object",
          "properties": {}
        }
      }
    ]
  }
}

tools/call 请求示例：

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "doudizhu_game_start",
    "arguments": {}
  }
}

2. 在 SecondMe 中配置应用

为了让 OpenClaw 能发现并调用你的应用，需要先在控制台创建一个 integration。注册入口：

SecondMe Developer Console

实际填写时，页面通常会分成以下几组：

Skill Metadata
Prompts
Actions
MCP Configuration
OAuth Binding
Environment Bindings

完整示例：

{
  "skill": {
    "key": "doudizhu",
    "displayName": "Dou Dizhu",
    "description": "Start or resume a Dou Dizhu game for the current user.",
    "keywords": ["game", "doudizhu", "card"]
  },
  "prompts": {
    "activationShort": "Play Dou Dizhu",
    "activationLong": "Start a new Dou Dizhu game or resume the user's current game.",
    "systemSummary": "Use this integration to start or resume a Dou Dizhu session for the authenticated user."
  },
  "actions": [
    {
      "name": "Start Game",
      "description": "Start or resume a Dou Dizhu game for the current user.",
      "toolName": "doudizhu_game_start",
      "displayHint": "Start game",
      "payloadTemplate": {}
    },
    {
      "name": "Get Game State",
      "description": "Get the current or latest Dou Dizhu game state.",
      "toolName": "doudizhu_game_get_state",
      "displayHint": "View game state",
      "payloadTemplate": {
        "game_id": "{{game_id}}"
      }
    }
  ],
  "mcp": {
    "endpoint": "https://your-app.example.com/api/mcp",
    "timeoutMs": 15000,
    "authMode": "bearer_token",
    "toolAllow": ["doudizhu_game_start", "doudizhu_game_get_state"],
    "headersTemplate": {}
  },
  "oauth": {
    "appId": "your_oauth_app_id",
    "requiredScopes": ["user.info"]
  },
  "environments": {
    "pre": {
      "enabled": true,
      "endpointOverride": "https://pre-your-app.example.com/api/mcp",
      "secrets": {
        "API_KEY": "pre_xxx"
      }
    },
    "prod": {
      "enabled": true,
      "endpointOverride": "https://your-app.example.com/api/mcp",
      "secrets": {
        "API_KEY": "prod_xxx",
        "token": "lba_at_example"
      }
    }
  }
}

字段说明

Skill Metadata

Integration Key：必填，只能使用小写字母、数字和 -。
Display Name：必填，展示给用户看的名称。
Description：必填，说明这个 integration 的用途。
Keywords：选填，便于搜索和分类。

Prompts

Activation Short：必填，短触发词或短标题。
Activation Long：必填，更完整的激活描述，告诉 agent 什么时候应使用它。
System Summary：必填，帮助 agent 快速理解这个 integration 的能力边界。

Actions

至少需要 1 条 action。
每条 action 至少填写 Action Name、Description、Tool Name。
Tool Name 必须和 tools/list 返回的 tools[].name 完全一致。
Display Hint：选填，给 UI 的展示提示。
Payload Template (JSON)：选填，用于预填工具参数。

MCP Configuration

MCP Endpoint：必填，你的 HTTP MCP endpoint，例如 https://your-app.example.com/api/mcp。
Timeout (ms)：选填，按工具耗时设置。
Auth Mode：选填，目前支持 none、bearer_token；header_template 暂未开放。
Allowed Tools：页面可能没做必填校验，但建议显式填写允许暴露的 tool 名。
Headers Template：暂未开放，当前无需配置。

OAuth Binding

OAuth App ID：页面必填，后端也会校验该 app 是否存在。
Required Scopes：选填，但建议把运行时真正依赖的 scope 明确写上；如果你的服务会调用 /api/secondme/user/info，通常至少需要 user.info。

Environment Bindings

pre / prod 各自维护一套环境配置。
Enabled：控制该环境是否启用。
Endpoint Override：为该环境单独覆盖 endpoint，选填。
Secrets：选填；如果你的 endpoint 或 header 模板里用了 {{token}}、{{API_KEY}} 这类占位符，就要在对应环境下填写同名 secret。

实用提醒

actions[].toolName 和 mcp.toolAllow 最好与 tools/list 返回的 tools[].name 完全对齐。
如果 authMode = bearer_token，且你没有在 header 模板里手写 Authorization，平台通常会尝试用当前环境的 token secret 自动补成 Bearer <token>。
header_template 暂未开放，当前无需配置 Headers Template。
OAuth App ID 填错、Required Scopes 缺失、Allowed Tools 与 action/tool 定义不一致，是最常见的配置问题。

其中 actions[].toolName 和 mcp.toolAllow 必须与 tools/list 返回的 tools[].name 完全一致，否则平台不会正确放行或路由该工具。

3. OpenClaw 如何调用你的应用

运行时，OpenClaw 或其他 agent 不会直接请求你的 MCP Server，而是先调用平台绑定 integration 的 MCP 代理：

POST /rest/third-party-agent/v1/mcp/{integrationKey}/rpc

随后平台会按以下顺序完成鉴权和转发：

根据 integration 上绑定的 oauth.appId，检查当前用户是否已经授权该应用。
为该应用换发一枚用户级 OAuth access token。
将该 token 放入请求头并转发到你的 MCP Server。
你的服务在请求头中收到：

Authorization: Bearer lba_at_...

你不需要接收或解析主站登录 token，也不应该依赖 sm-* token 来识别用户。

4. 在应用中识别当前用户

你的 MCP 服务收到的是平台换发后的应用级用户 token。要识别当前 SecondMe 用户，应使用这枚 token 调用：

GET https://api.mindverse.com/gate/lab/api/secondme/user/info

返回中要读取的是：

data.userId

不是顶层 id，也不是 data.id。

典型返回：

{
  "code": 0,
  "data": {
    "userId": "2499",
    "name": "xxx",
    "avatar": "https://..."
  }
}

5. 应用所需权限

如果你的服务需要通过 /api/secondme/user/info 获取当前用户，应用授权 scope 必须包含：

user.info

一个常见误区是：平台虽然会优先使用“该用户对该应用已授权的 scope”去签发外部 token，但如果用户历史授权本身不包含 user.info，那么你的服务调用 /api/secondme/user/info 仍然会返回 403。

6. 应用服务端实现建议

推荐在工具请求进入时立即完成 token 提取、用户解析和字段校验：

const token = req.headers.authorization?.replace(/^Bearer\s+/, "");

if (!token) {
  throw new Error("missing bearer token");
}

const response = await fetch(
  "https://api.mindverse.com/gate/lab/api/secondme/user/info",
  {
    headers: { Authorization: `Bearer ${token}` }
  }
);

const userInfo = await response.json();
const userId = userInfo?.data?.userId;

if (!userId) {
  throw new Error("missing userId");
}

// Use userId as the stable business identity in your service.

7. 常见接入问题

最常见的问题通常集中在这几类：

mcp.toolAllow 与 tools/list 返回的 tool name 不一致
actions[].toolName 与 mcp.toolAllow 不一致
服务端读取了 id，而不是 data.userId
用户没有为该应用授权 user.info
将 /api/secondme/user/info 的 403 scope 错误误判为“token 没有 user id”
integration 绑定了一个 oauth.appId，但用户实际授权的是另一个应用

8. 联调检查单

建议按以下顺序排查：

tools/list 是否可以正常返回工具定义。
integration 的 actions[].toolName 与 mcp.toolAllow 是否与工具名完全一致。
平台是否成功为该应用换发了用户级 token。
你的 MCP 服务是否收到了 Authorization: Bearer lba_at_*。
调用 /api/secondme/user/info 时是否拿到了 data.userId。
如果用户信息接口返回 403，先检查该用户对该应用的历史授权 scope 是否包含 user.info。

下一步

认证概述 - 了解平台 OAuth2 鉴权基础
OAuth2 指南 - 查看完整授权码流程
SecondMe API - 查看可与用户 token 配合使用的 API

通过 OpenClaw 使用应用

On this page