查询工具列表

列出当前工作区和当前身份可读取的系统工具。列表默认不返回大型输入、输出 Schema；需要时显式请求完整视图。

GET https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/tools

调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

• $AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。

• $WORKSPACE_ID：要查询的工作区 ID，通过 X-Workspace-ID Header 传递。

路径参数

参数	类型	是否必填	说明
workspace_id	string	是	当前工作区 ID。

查询参数

参数	类型	是否必填	说明
query	string	否	按工具属性筛选。
status	string	否	按工具属性筛选。
kind	string	否	按工具属性筛选。
category	string	否	按工具属性筛选。
phase	string	否	按工具属性筛选。
side_effect_class	string	否	按工具属性筛选。
runtime	string	否	按运行时可见性、绑定类型或目录筛选。
binding_type	string	否	按运行时可见性、绑定类型或目录筛选。
catalog	string	否	按运行时可见性、绑定类型或目录筛选。
tags	string	否	按标签筛选；可重复提供。
include_schema	boolean	否	为 true 时，列表项包含 input_schema 和 output_schema。
view	string	否	full 或 detail 时，列表项包含 Schema。
limit	integer	否	返回数量和起始偏移。未提供时默认 50 条、偏移 0；limit 最大 200。
offset	integer	否	返回数量和起始偏移。未提供时默认 50 条、偏移 0；limit 最大 200。

请求示例

curl "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/tools?kind=http_api&limit=20&offset=0" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

成功响应

成功时返回 200。

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "tool_01",
        "workspace_id": "ws_01",
        "name": "查询工具",
        "display_name": "查询工具",
        "status": "active",
        "kind": "http_api",
        "side_effect_class": "read",
        "version": 1,
        "bindable": true,
        "supported_runtimes": []
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

响应字段如下。

本文中，字段路径中的 [] 表示数组中的每一项。例如，items[].name 表示 items 数组中每一项的 name 字段。

字段	类型	说明
code	integer	成功时为 0。
data.items	array	匹配筛选条件的工具。
data.items[].id	string	工具、所属工作区和原始名称。
data.items[].workspace_id	string	工具、所属工作区和原始名称。
data.items[].name	string	工具、所属工作区和原始名称。
data.items[].description	string	工具说明；未设置时不返回。
data.items[].display_name	string	按当前语言投影的名称和说明。
data.items[].display_description	string	按当前语言投影的名称和说明。
data.items[].status	string	工具状态、类别和副作用分类。
data.items[].kind	string	工具状态、类别和副作用分类。
data.items[].side_effect_class	string	工具状态、类别和副作用分类。
data.items[].category	string	工具分类；未设置时不返回。
data.items[].source_ref	object	工具来源引用；未设置时不返回。
data.items[].sync	object	同步状态；未设置时不返回。
data.items[].version	integer	工具版本。
data.items[].bindable	boolean	当前绑定能力及支持的运行环境。
data.items[].bindability_reason	string	当前绑定能力及支持的运行环境。
data.items[].supported_runtimes	string（字符串数组）	当前绑定能力及支持的运行环境。
data.items[].input_schema	object	仅 include_schema=true 或 view=full/detail 时返回。
data.items[].output_schema	object	仅 include_schema=true 或 view=full/detail 时返回。
data.items[].created_by	string	创建者标识；未设置时不返回。
data.items[].updated_by	string	最近更新者标识；未设置时不返回。
data.items[].created_at	string	创建时间，采用 RFC 3339 格式。
data.items[].updated_at	string	最近更新时间，采用 RFC 3339 格式。
data.total	integer	匹配总数、当前页大小和偏移量。
data.limit	integer	匹配总数、当前页大小和偏移量。
data.offset	integer	匹配总数、当前页大小和偏移量。

错误响应

{
  "code": 2,
  "message": "<错误信息>"
}

常见 HTTP 错误

HTTP 状态码	错误代码	常见原因	建议操作
400	2（INVALID_ARGUMENT）	筛选或分页参数无效。	检查查询参数。
401	6（UNAUTHENTICATED）	缺少有效身份凭据。	检查 API Key。
403	5（PERMISSION_DENIED）	当前身份没有读取工具目录的权限。	检查工作区授权。
503	15（UNAVAILABLE）	工具资源服务或授权依赖暂不可用。	稍后重试。

后续操作

保存目标项的标识，再查询工具详情。

最后更新于 2026 年 8 月 22 日