> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # 更新 Template > 根据 ID 更新 Forward Template。 `POST /api/v1/forward/templates/{template_id}` 只更新请求体中出现的字段；数组字段在传入时整体替换。 ## 请求头 | Header | 是否必填 | 说明 | | --------------- | ---- | ------------------ | | Authorization | 是 | `Bearer ` | | Content-Type | 是 | `application/json` | | Idempotency-Key | 否 | 有副作用请求可选的幂等键。 | ## 路径参数 | 参数 | 类型 | 是否必填 | 说明 | | ------------ | ------ | ---- | -------------------- | | template\_id | string | 是 | Forward Template ID。 | ## 请求体参数 | 参数 | 类型 | 是否必填 | 说明 | | ---------------------- | ------------------------ | ---- | ------------------------------------- | | name | string | 否 | 新的 Template 名称。 | | description | string | 否 | 新的 Template 描述。 | | model | string | 否 | 新的模型标识。 | | 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` 或空字符串表示清空。 | | vault\_ids | array \| null | 否 | 整体替换默认 Vault 列表；`null` 表示清空。 | | files | object \| null | 否 | 整体替换默认文件资源配置；`null` 表示清空。 | | environment\_variables | object \| string \| null | 否 | 整体替换默认环境变量；`null` 表示清空。 | | metadata | object | 否 | 合并更新自定义元数据。 | ## 嵌套配置对象 `tools`、`mcp_servers`、`skills` 都是数组字段；更新请求中一旦传入，会整体替换原数组。 ### 文件资源 `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 配置。 | ## 示例请求 ```bash theme={null} 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** ```json theme={null} { "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 对象。 | ## 错误 | 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。 ## 相关