更新 Template - Qoder CN 系列

根据 ID 更新 Forward Template。

请求头

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

路径参数

参数	类型	是否必填	说明
`template_id`	string	是	Forward Template ID。

请求体参数

参数	类型	是否必填	说明
`name`	string	否	新的 Template 名称。
`description`	string	否	新的 Template 描述。
`model`	string \| object	否	新的模型标识。可传 string，或传 Agent model 对象以同时配置 `effort` 或 `context_window`。可通过列出模型接口查询可用值。
`system`	string	否	新的 System Prompt。
`tools`	array	否	整体替换工具配置列表。
`mcp_servers`	array	否	整体替换 MCP Server 列表。
`skills`	array	否	整体替换 Skill 绑定列表。
`multiagent`	object	否	替换 Managed Agents 配置。
`environment_id`	string\|null	否	替换默认 Environment ID；`null` 或空字符串表示清空。
`vaults`	object\|null	否	整体替换默认 Vault 配置；按 Vault ID 组织，`null` 表示清空。
`files`	object\|null	否	整体替换默认文件资源配置；`null` 表示清空。
`environment_variables`	object\|string\|null	否	整体替换默认环境变量；`null` 表示清空。
`metadata`	object	否	合并更新自定义元数据。

嵌套配置对象

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

Model

model 支持两种等价形态：直接传模型 ID 字符串，或传包含模型 ID 和可选调优字段的对象。

字段	类型	是否必填	说明
`id`	string	是	模型标识；可通过列出模型接口查询可用值。
`effort`	string	否	Reasoning effort 等级。可选值：`none`、`low`、`medium`、`high`、`xhigh`、`max`；各模型实际支持的等级见列出模型返回的 `efforts`。
`context_window`	integer	否	期望的上下文窗口（token 数，正整数）；取值请从列出模型返回的 `available_context_windows` 中选择。

Vaults

vaults 是按 Vault ID 组织的 map。每个配置项支持可选的 enabled boolean；省略等同于 true。更新时传入 vaults 会整体替换原配置，传 null 会清空。

{
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    },
    "vault_019f18f2762c": {
      "enabled": true
    }
  }
}

响应统一返回对象形态的 vaults。

文件资源

files 是按 File ID 组织的 map。配置项内不要再写 file_id、id 或 resource_id。Forward 在创建 Session 时自动注入 mount_path。

字段	类型	是否必填	说明
`enabled`	boolean	否	省略等同于 `true`。Identity Config 中可用 `false` 禁用继承的文件。

tools 数组项

每个 tools[] 项通过 type 选择结构。

字段	类型	适用类型	说明
`type`	string	全部	必填。取值为 `agent_toolset_20260401`、`mcp_toolset` 或 `custom`。
`enabled_tools`	array	`agent_toolset_20260401`	便捷白名单；非空数组表示只启用这些内置工具。
`disallowed_tools`	array	`agent_toolset_20260401`	便捷禁用列表；编译为 disabled tool config。
`configs`	array	`agent_toolset_20260401`、`mcp_toolset`	单工具启用状态和权限策略。
`mcp_server_name`	string	`mcp_toolset`	必填，必须匹配某个 `mcp_servers[].name`。
`name`	string	`custom`	必填，自定义工具名，不能与内置工具重名。
`description`	string	`custom`	必填，自定义工具描述。
`input_schema`	object	`custom`	必填 JSON Schema，`input_schema.type` 必须为 `object`。

内置工具名包括 Bash、Read、Write、Edit、Glob、Grep、WebFetch、WebSearch、DeliverArtifacts。

Tool config

tools[].configs[] 使用以下结构。

字段	类型	是否必填	说明
`name`	string	是	工具名；内置工具使用 built-in tool name，MCP toolset 使用 MCP tool name。
`enabled`	boolean	否	`false` 表示隐藏并拒绝该工具；`true` 表示显式启用。
`permission_policy`	object	否	运行时权限行为。

Permission policy

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

MCP servers

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

skills 数组项

字段	类型	是否必填	说明
`type`	string	是	`custom` 或 `qoder`。
`skill_id`	string	是	Skill ID。
`version`	string	否	Skill 版本，省略时使用最新版本。
`enabled`	boolean	否	省略等同于 `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",
  "model": {
    "id": "ultimate",
    "effort": "high",
    "context_window": 400000
  },
  "environment_id": "env_support_v2",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    },
    "vault_019f18f2762c": {
      "enabled": true
    }
  },
  "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": {
    "id": "ultimate",
    "effort": "high",
    "context_window": 400000
  },
  "system": "You are a helpful support assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "environment_id": "env_support_v2",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    },
    "vault_019f18f2762c": {
      "enabled": true
    }
  },
  "files": {},
  "environment_variables": {
    "BASE_MODE": "support_v2"
  },
  "metadata": {},
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:30:00Z"
}

响应字段

字段	类型	说明
返回值	object	更新后的完整 Template 对象；请求包含 `model` 时按提交形态返回，未包含时保持原有形态。

错误

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

备注

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

Qoder CN 系列：更新 Template

请求头