更新 Template

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

请求头

Header	是否必填	说明
Authorization	是	`Bearer <PAT 或 SAT>`
Content-Type	是	`application/json`
Idempotency-Key	否	有副作用请求可选的幂等键。
X-Qoder-Beta	使用浏览器能力时	更新后的 `tools` 中包含 Browser Use 工具集时，必须设置为 `browser-use-2026-07-14`。

路径参数

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

请求体参数

参数	类型	是否必填	说明
name	string	否	新的 Template 名称。
description	string	否	新的 Template 描述。
model	string \| object	否	新的模型标识。可传 string，或传 Agent model 对象以同时配置 `effort`、`speed` 或 `context_window`。可通过列出模型接口查询可用值。
system	string	否	新的 System Prompt。
max_tool_rounds	integer\|null	否	单次 Turn 的工具调用轮数上限，必须为正整数。省略时保留当前值；传 `null` 清除显式上限并使用平台默认值。
tools	array	否	整体替换工具配置列表。
managed_tool_config	object\|null	否	整体替换 Forward 托管能力基线；`null`、`{}` 或 `enabled_tools: []` 表示清空。
mcp_servers	array	否	整体替换 MCP Server 列表。
skills	array	否	整体替换 Skill 绑定列表。
multiagent	object\|null	否	整体替换 Multi-agent 协作配置；传 `null` 表示清空，省略则保留当前配置。
environment_id	string\|null	否	替换默认 Environment ID；`null` 或空字符串表示清空。
vaults	object\|null	否	整体替换默认 Vault 配置；按 Vault ID 组织，`null` 表示清空。
files	object\|null	否	整体替换默认文件资源配置；`null` 表示清空。
github_repositories	object\|null	否	整体替换默认 GitHub 仓库配置；按 binding key 组织，`null` 或空 object 表示清空。
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` 中选择。
`speed`	string	否	推理速度，可选值：`standard`、`high`；省略时使用 `standard`。各模型实际支持的速度见列出模型返回的 `speed` 数组。

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` 禁用继承的文件。

GitHub 仓库

github_repositories 是按 binding key 组织的 map。binding key 必须匹配 [A-Za-z][A-Za-z0-9_-]{0,63}，最多包含 20 个 binding；规范化后的仓库 URL 和挂载路径均不能重复。

字段	类型	是否必填	说明
url	string	是	绝对 HTTPS 仓库 URL；不能包含 userinfo、query、fragment、百分号编码或反斜杠，末尾 `.git` 会被规范化移除。
authorization_token	string	是	仓库访问 token，仅写入，响应不会回显；最长 8192 bytes，只允许 ASCII 字母、数字和下划线。
mount_path	string	否	Session 内的挂载路径，必须是除 `/` 外的规范化绝对路径；省略时为 `/data/workspace/<仓库名>`。省略整个 `github_repositories` 字段仍保留已有配置。

更新时 github_repositories 使用整体替换语义：

请求形态	语义
字段未出现	保留当前仓库配置。
`github_repositories: null`	清空全部 binding。
`github_repositories: {}`	清空全部 binding。
非空 object	使用该 object 整体替换当前仓库配置。

tools 数组项

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

字段	类型	适用类型	说明
type	string	全部	必填。取值为 `agent_toolset_20260401`、`browser_toolset_20260714`、`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。

Forward 托管能力

managed_tool_config.enabled_tools 完整表示 Template 启用的 Forward 托管能力。Forward 负责提供对应的工具定义，调用方不需要在 tools 中重复配置。当前支持 schedule、create_forward_schedule、list_forward_schedules、delete_forward_schedule 和 drive。 schedule 是 Schedule 能力组合的便捷写法，等价于同时启用 create_forward_schedule、list_forward_schedules 和 delete_forward_schedule：

{
  "managed_tool_config": {
    "enabled_tools": ["schedule"]
  }
}

schedule 等 Bundle/Capability 选择器只用于配置；drive 表示完整的 Drive 能力。Session 运行时会获得对应的、可独立调用的 Forward 托管工具；Template 响应会保留请求中的 schedule 或 drive，不会将其改写为执行工具名。

请求形态	语义
字段未出现	保留当前托管能力基线。
`managed_tool_config: null`	清空全部 Forward 托管能力。
`managed_tool_config: {}`	清空全部 Forward 托管能力。
`{ "enabled_tools": [] }`	清空全部 Forward 托管能力。
`enabled_tools` 为非空数组	使用该数组整体替换当前基线。

未知或重复的选择器会被拒绝。

浏览器能力（Beta）

Browser Use 当前为 Beta 能力，功能、使用限制和接口细节可能会调整。如需为通过该 Template 创建的 Session 开启浏览器能力，请在 tools 中添加以下工具集：

{
  "type": "browser_toolset_20260714"
}

请求还必须携带以下 Header，否则无法启用浏览器能力：

X-Qoder-Beta: browser-use-2026-07-14

更新接口中的 tools 是整体替换语义。如果需要保留已有工具集，请将它们与 browser_toolset_20260714 一并放入新的 tools 数组。

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 配置。

Multiagent

multiagent 将当前 Template 配置为 coordinator，声明它可以委派的 Agent 名单及可选的 Advisor。

字段	类型	是否必填	说明
type	string	是	固定为 `coordinator`。
agents	array	是	非空名单，最多 20 个普通 Agent 条目（含 `self`），另可包含 1 个 Advisor。

multiagent.agents[] 支持以下形式：

形式	示例	说明
Template 引用对象	`{"type":"agent","template_id":"tmpl_research"}`	引用当前调用方可访问的 Forward Template。
coordinator 自身	`{"type":"self"}`	将当前 coordinator 作为可委派 Agent。
Advisor 对象	`{"type":"advisor","model":"ultimate"}`	给主线程配置一个顾问模型；每份名单最多一个，详见 Advisor。

普通 Agent 和 self 对象的字段如下；Advisor 使用单独的结构，见 Advisor。

字段	类型	适用类型	是否必填	说明
type	string	全部	是	`agent` 表示引用另一个 Agent，`self` 表示 coordinator 自身。
template_id	string	`agent`	是	被引用的 Forward Template ID。
name	string	`agent`	否	子 Agent 显示名称。

使用 template_id 时，被引用 Template 必须存在且当前调用方有权访问。名单包含普通 Agent 或 self 时，tools 需要包含 agent_toolset_20260401；仅配置 Advisor 时不要求该工具集。如果在同一个更新请求中也传入 tools，该数组会整体替换当前工具配置，因此需要在新数组中保留该工具集。

请求形态	语义
字段未出现	保留当前 `multiagent` 配置。
`multiagent: null`	清空 `multiagent` 配置。
非空 object	使用该 object 整体替换当前配置。

Advisor

Advisor 为主 Agent 提供建议，适合方案评审、复杂问题分析等场景。主 Agent 决定何时咨询及是否采纳建议；你可以在系统提示词中写明咨询条件。Advisor 根据主 Agent 的当前对话上下文提供建议，不执行工具。

字段	类型	是否必填	说明
type	string	是	必须为 `"advisor"`。
model	string	是	非空的可用模型名称，见列出模型；不支持模型对象格式。

Advisor 条目只接受 type 和 model，可以单独配置，也可以与普通条目共存。每份名单最多一个 Advisor，不计入普通 Agent 的 20 项上限；无需加入 enabled_tools。字段定义与 Managed 层的 Advisor 对象一致。

{
  "multiagent": {
    "type": "coordinator",
    "agents": [{"type": "advisor", "model": "ultimate"}]
  }
}

修改 Advisor 模型时，更新 multiagent.agents[] 中 Advisor 条目的 model 字符串；Template 顶层 model 控制主 Agent，不会修改 Advisor 模型。更新 multiagent 会整体替换配置，需一并传入所有要保留的普通 Agent 和 self 条目；移除 Advisor 时从名单中删除该项，清空整份名单时传 multiagent: null。Advisor 配置变更仅对新建 Session 生效。

示例请求

curl -s -X POST 'https://api.qoder.com/api/v1/forward/templates/tmpl_support' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Support assistant v2",
  "max_tool_rounds": 40,
  "model": {
    "id": "ultimate",
    "effort": "high",
    "speed": "standard",
    "context_window": 400000
  },
  "managed_tool_config": {
    "enabled_tools": []
  },
  "multiagent": {
    "type": "coordinator",
    "agents": [
      {
        "type": "agent",
        "template_id": "tmpl_research_v2",
        "name": "Research Agent"
      },
      {
        "type": "self"
      }
    ]
  },
  "environment_id": "env_support_v2",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    },
    "vault_019f18f2762c": {
      "enabled": true
    }
  },
  "github_repositories": {
    "source": {
      "url": "https://github.com/acme/support-agent.git",
      "authorization_token": "github_pat_xxx",
      "mount_path": "/data/workspace/support-agent"
    }
  },
  "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",
  "max_tool_rounds": 40,
  "model": {
    "id": "ultimate",
    "effort": "high",
    "speed": "standard",
    "context_window": 400000
  },
  "system": "You are a helpful support assistant.",
  "tools": [
    {
      "type": "agent_toolset_20260401"
    }
  ],
  "managed_tool_config": {
    "enabled_tools": []
  },
  "mcp_servers": [],
  "skills": [],
  "multiagent": {
    "type": "coordinator",
    "agents": [
      {
        "type": "agent",
        "template_id": "tmpl_research_v2",
        "name": "Research Agent"
      },
      {
        "type": "self"
      }
    ]
  },
  "environment_id": "env_support_v2",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    },
    "vault_019f18f2762c": {
      "enabled": true
    }
  },
  "files": {},
  "github_repositories": {
    "source": {
      "url": "https://github.com/acme/support-agent",
      "mount_path": "/data/workspace/support-agent"
    }
  },
  "environment_variables": {
    "BASE_MODE": "support_v2"
  },
  "metadata": {},
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:30:00Z"
}

响应字段

字段	类型	说明
返回值	object	更新后的完整 Template 对象；请求包含 `model` 时按提交形态返回，未包含时保持原有形态。
managed_tool_config	object	更新后的 Forward 托管能力基线，以 `enabled_tools` 数组返回。
max_tool_rounds	integer	单次 Turn 的工具调用轮数上限；未设置或已清除时省略该字段，不返回 `null`。
multiagent	object\|null	更新后的 Multi-agent 配置；未设置时为 `null`。
github_repositories	object	更新后的 GitHub 仓库配置；不包含 write-only 的 `authorization_token`。

错误

HTTP	Type	Code	触发条件
400	`invalid_request_error`	-	请求体或字段取值不合法。
400	`invalid_request_error`	-	使用 `browser_toolset_20260714` 但未携带正确的 `X-Qoder-Beta` Header。
400	`invalid_request_error`	-	`multiagent` 结构不合法，名单为空、普通 Agent 超过 20 个、Advisor 超过 1 个或其字段不合法，或引用的 Forward Template 不存在或不可访问。
404	`not_found_error`	-	Template 或引用资源不存在。
409	`conflict_error`	-	Template 名称已存在、状态冲突，或 GitHub 仓库的规范化 URL、挂载路径重复。
401	`authentication_error`	`authentication_required`	PAT 或 SAT 无效或已过期。

备注

归档后的 Template 不允许更新。
存量请求中的 managed_tool_config.tools 和 schedule_creation_enabled 仍兼容处理；新接入应使用 managed_tool_config.enabled_tools。
更新 Session 默认配置不会修改已经存在的 Session。
github_repositories.*.authorization_token 是 write-only 字段，不会出现在 Template 响应中。

更新 Template

请求头

路径参数

请求体参数

嵌套配置对象

Model

Vaults

文件资源

GitHub 仓库

tools 数组项

Forward 托管能力

浏览器能力（Beta）

Tool config

Permission policy

MCP servers

skills 数组项

Multiagent

Advisor

示例请求

示例响应

响应字段

错误

备注

相关

获取 Template

克隆 Template

​请求头

​路径参数

​请求体参数

​嵌套配置对象

​Model

​Vaults

​文件资源

​GitHub 仓库

​tools 数组项

​Forward 托管能力

​浏览器能力（Beta）

​Tool config

​Permission policy

​MCP servers

​skills 数组项

​Multiagent

​Advisor

​示例请求

​示例响应

​响应字段

​错误

​备注

​相关

获取 Template

克隆 Template

请求头

路径参数

请求体参数

嵌套配置对象

Model

Vaults

文件资源

GitHub 仓库

tools 数组项

Forward 托管能力

浏览器能力（Beta）

Tool config

Permission policy

MCP servers

skills 数组项

Multiagent

Advisor

示例请求

示例响应

响应字段

错误

备注

相关