跳转到主要内容
POST /api/v1/forward/templates/{template_id} 只更新请求体中出现的字段；数组字段在传入时整体替换。

​
请求头

Header是否必填说明
Authorization是Bearer <PAT>
Content-Type是application/json
Idempotency-Key否有副作用请求可选的幂等键。

​
路径参数

参数类型是否必填说明
template_idstring是Forward Template ID。

​
请求体参数

参数类型是否必填说明
namestring否新的 Template 名称。
descriptionstring否新的 Template 描述。
modelstring否新的模型标识。
systemstring否新的 System Prompt。
toolsarray否整体替换工具配置列表。
mcp_serversarray否整体替换 MCP Server 列表。
skillsarray否整体替换 Skill 绑定列表。
multiagentobject否替换 Managed Agents 配置。
environment_idstring | null否替换默认 Environment ID；null 或空字符串表示清空。
vault_idsarray | null否整体替换默认 Vault 列表；null 表示清空。
filesobject | null否整体替换默认文件资源配置；null 表示清空。
environment_variablesobject | string | null否整体替换默认环境变量；null 表示清空。
metadataobject否合并更新自定义元数据。

​
嵌套配置对象

tools、mcp_servers、skills 都是数组字段；更新请求中一旦传入，会整体替换原数组。

​
文件资源

files 是按 File ID 组织的 map。配置项内不要再写 file_id、id 或 resource_id。Forward 在创建 Session 时自动注入 mount_path。
字段类型是否必填说明
enabledboolean否省略等同于 true。Identity Config 中可用 false 禁用继承的文件。

​
tools 数组项

每个 tools[] 项通过 type 选择结构。
字段类型适用类型说明
typestring全部必填。取值为 agent_toolset_20260401、mcp_toolset 或 custom。
enabled_toolsarrayagent_toolset_20260401便捷白名单；非空数组表示只启用这些内置工具。
disallowed_toolsarrayagent_toolset_20260401便捷禁用列表；编译为 disabled tool config。
configsarrayagent_toolset_20260401、mcp_toolset单工具启用状态和权限策略。
mcp_server_namestringmcp_toolset必填，必须匹配某个 mcp_servers[].name。
namestringcustom必填，自定义工具名，不能与内置工具重名。
descriptionstringcustom必填，自定义工具描述。
input_schemaobjectcustom必填 JSON Schema，input_schema.type 必须为 object。
内置工具名包括 Bash、Read、Write、Edit、Glob、Grep、WebFetch、WebSearch、DeliverArtifacts。

​
Tool config

tools[].configs[] 使用以下结构。
字段类型是否必填说明
namestring是工具名；内置工具使用 built-in tool name，MCP toolset 使用 MCP tool name。
enabledboolean否false 表示隐藏并拒绝该工具；true 表示显式启用。
permission_policyobject否运行时权限行为。

​
Permission policy

字段类型是否必填说明
typestring是always_allow、always_ask 或 always_deny。

​
MCP servers

字段类型是否必填说明
typestring否当前只支持 http；省略时 Effective Config 中按 HTTP MCP server 处理。
namestring是Template 内唯一的 MCP server 名称，由 tools[].mcp_server_name 引用。
urlstring是Streamable HTTP MCP endpoint URL。

​
skills 数组项

字段类型是否必填说明
typestring是custom 或 qoder。
skill_idstring是Skill ID。
versionstring否Skill 版本，省略时使用最新版本。
enabledboolean否省略等同于 true；false 表示不进入编译后的 Agent 配置。

​
示例请求

curl -s -X POST 'https://api.qoder.com/api/v1/forward/templates/tmpl_support' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Support assistant v2",
  "environment_id": "env_support_v2",
  "vault_ids": [
    "vault_crm",
    "vault_billing"
  ],
  "environment_variables": {
    "BASE_MODE": "support_v2"
  }
}'

​
示例响应

HTTP 200 OK 
{
  "type": "template",
  "id": "tmpl_support",
  "name": "Support assistant v2",
  "description": "Handles customer support requests",
  "status": "active",
  "model": "ultimate",
  "system": "You are a helpful support assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "environment_id": "env_support_v2",
  "vault_ids": [
    "vault_crm",
    "vault_billing"
  ],
  "files": {},
  "environment_variables": {
    "BASE_MODE": "support_v2"
  },
  "metadata": {},
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:30:00Z"
}

​
响应字段

字段类型说明
返回值object更新后的完整 Template 对象。

​
错误

HTTPTypeCode触发条件
400invalid_request_error-请求体或字段取值不合法。
404not_found_error-Template 或引用资源不存在。
409conflict_error-Template 名称已存在或状态冲突。
401authentication_errorauthentication_requiredPAT 无效或已过期。

​
注意事项

  • 归档后的 Template 不允许更新。
  • 更新 Session 默认配置不会修改已经存在的 Session。

​
相关

获取 Template

克隆 Template