更新工具

部分更新当前工作区中的平台工具。工具在当前工作区不存在时不会创建新工具。

PATCH https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/tools/{tool_id}

调用前准备

先查询工具详情确认要更新的工具。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和工具 ID。

路径参数

参数	类型	是否必填	说明
workspace_id	string	是	当前工作区 ID。
tool_id	string	是	要更新的工具 ID。

查询参数

参数	类型	是否必填	说明
tool_workspace_id	string	否	工具所属工作区；仅可为当前工作区或 system。指定 system 时系统工具为只读，更新会被拒绝。

请求体

调用示例

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/tools/$TOOL_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "更新后的说明",
    "status": "active"
  }'

参数说明

请求体中的字段均为可选；未提供的字段保持原值。

参数	类型	是否必填	说明
name	string	否	工具名称、描述、状态、类别和展示信息。状态可为 draft、active、disabled 或 archived。
description	string	否	工具名称、描述、状态、类别和展示信息。状态可为 draft、active、disabled 或 archived。
status	string	否	工具名称、描述、状态、类别和展示信息。状态可为 draft、active、disabled 或 archived。
kind	string	否	工具名称、描述、状态、类别和展示信息。状态可为 draft、active、disabled 或 archived。
category	string	否	工具名称、描述、状态、类别和展示信息。状态可为 draft、active、disabled 或 archived。
icon_ref	string	否	工具名称、描述、状态、类别和展示信息。状态可为 draft、active、disabled 或 archived。
phase	string	否	工具名称、描述、状态、类别和展示信息。状态可为 draft、active、disabled 或 archived。
tags	array of string	否	工具标签；提供该字段会替换原有标签。仅更新 tags 时不会递增资源版本。
source_ref	object	否	来源；可包含 type、id、uri、version 和 config。
input_schema	object	否	输入和输出 JSON Schema。
output_schema	object	否	输入和输出 JSON Schema。
side_effect_class	string	否	副作用分类：read、write 或 external_effect。
credential_ref	string	否	凭据、审批和脱敏策略引用。
approval_policy_ref	string	否	凭据、审批和脱敏策略引用。
redaction_policy_ref	string	否	凭据、审批和脱敏策略引用。
sync	object	否	同步状态，可包含 status、last_sync_at 和 last_sync_error。
market_metadata	object	否	市场元数据、标签、注释和扩展元数据。
labels	object	否	市场元数据、标签、注释和扩展元数据。
annotations	object	否	市场元数据、标签、注释和扩展元数据。
metadata	object	否	市场元数据、标签、注释和扩展元数据。

MCP 工具不能通过此接口修改 kind、source_ref 或 credential_ref；也不能将普通工具更新为 MCP 工具。

成功响应

响应示例

{
  "code": 0,
  "data": {
    "id": "tool_01",
    "workspace_id": "ws_01",
    "name": "查询工具",
    "description": "更新后的说明",
    "status": "active",
    "kind": "http_api",
    "side_effect_class": "read",
    "version": 2,
    "bindable": true,
    "supported_runtimes": [],
    "created_at": "2026-01-02T15:04:05Z",
    "updated_at": "2026-01-02T15:04:05Z"
  }
}

字段说明

成功时返回 200 和更新后的工具。除仅更新 tags 外，资源版本会递增。

响应字段如下。

通用字段

字段	类型	说明
code	integer	成功时为 0。

基本信息

字段	类型	说明
id	string	工具 ID 和所属工作区。
workspace_id	string	工具 ID 和所属工作区。
name	string	更新后的基本定义。
description	string	更新后的基本定义。
status	string	更新后的基本定义。
kind	string	更新后的基本定义。
side_effect_class	string	副作用分类和当前资源版本。
version	integer	副作用分类和当前资源版本。
bindable	boolean	当前绑定能力、不可绑定原因和支持的运行环境。
bindability_reason	string	当前绑定能力、不可绑定原因和支持的运行环境。
supported_runtimes	array of string	当前绑定能力、不可绑定原因和支持的运行环境。
updated_at	string	最近更新时间，使用 RFC 3339 格式。

错误响应

响应示例

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

字段说明

常见 HTTP 错误

通用字段

字段	类型	说明
400	2（INVALID_ARGUMENT）	**常见原因：**路径、请求字段或 MCP 工具更新范围无效。**建议操作：**检查工具 ID、字段值和工具类别限制。
401	6（UNAUTHENTICATED）	**常见原因：**缺少有效身份凭据。**建议操作：**检查 API Key。
403	5（PERMISSION_DENIED）	**常见原因：**当前身份没有更新工具的权限。**建议操作：**检查工作区授权。
403	7（FORBIDDEN）	**常见原因：**指定的系统工具为只读。**建议操作：**不要修改系统工具；在当前工作区创建或更新自己的工具。
404	3（NOT_FOUND）	**常见原因：**指定工作区中不存在该工具。**建议操作：**检查工具 ID 和 tool_workspace_id。
503	15（UNAVAILABLE）	**常见原因：**工具资源服务或授权依赖暂不可用。**建议操作：**稍后重试。

后续操作

用同一资源标识查询工具详情确认更新结果。

最后更新于 2026 年 9 月 28 日