更新 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` 或 `context_window`。可通过列出模型接口查询可用值。
system	string	否	新的 System Prompt。
tools	array	否	整体替换工具配置列表。
mcp_servers	array	否	整体替换 MCP Server 列表。
skills	array	否	整体替换 Skill 绑定列表。
multiagent	object\|null	否	整体替换 Multi-agent 协作配置；传 `null` 表示清空，省略则保留当前配置。
environment_id	string	null	否
vaults	object	null	否
files	object	null	否
github_repositories	object	null	否
environment_variables	object	string	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` 禁用继承的文件。

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。

浏览器能力（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 花名册。

字段	类型	是否必填	说明
type	string	是	固定为 `coordinator`。
agents	array	是	可委派的 Agent 列表，必须包含 1-20 项。

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

形式	示例	说明
Template 引用对象	`{"type":"agent","template_id":"tmpl_research"}`	引用当前调用方可访问的 Forward Template。
coordinator 自身	`{"type":"self"}`	将当前 coordinator 作为可委派 Agent。

对象形式的字段如下：

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

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

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

示例请求

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",
  "model": {
    "id": "ultimate",
    "effort": "high",
    "context_window": 400000
  },
  "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",
  "model": {
    "id": "ultimate",
    "effort": "high",
    "context_window": 400000
  },
  "system": "You are a helpful support assistant.",
  "tools": [
    {
      "type": "agent_toolset_20260401"
    }
  ],
  "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` 时按提交形态返回，未包含时保持原有形态。
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` 结构不合法，`agents` 数量不在 1-20 之间，或引用的 Forward Template 不存在或不可访问。
404	`not_found_error`	-	Template 或引用资源不存在。
409	`conflict_error`	-	Template 名称已存在、状态冲突，或 GitHub 仓库的规范化 URL、挂载路径重复。
401	`authentication_error`	`authentication_required`	PAT 或 SAT 无效或已过期。

备注

归档后的 Template 不允许更新。
更新 Session 默认配置不会修改已经存在的 Session。
github_repositories.*.authorization_token 是 write-only 字段，不会出现在 Template 响应中。

更新 Template

请求头

路径参数

请求体参数

嵌套配置对象

Model

Vaults

文件资源

GitHub 仓库

tools 数组项

浏览器能力（Beta）

Tool config

Permission policy

MCP servers

skills 数组项

Multiagent

示例请求

示例响应

响应字段

错误

备注

相关

获取 Template

克隆 Template

​请求头

​路径参数

​请求体参数

​嵌套配置对象

​Model

​Vaults

​文件资源

​GitHub 仓库

​tools 数组项

​浏览器能力（Beta）

​Tool config

​Permission policy

​MCP servers

​skills 数组项

​Multiagent

​示例请求

​示例响应

​响应字段

​错误

​备注

​相关

获取 Template

克隆 Template

请求头

路径参数

请求体参数

嵌套配置对象

Model

Vaults

文件资源

GitHub 仓库

tools 数组项

浏览器能力（Beta）

Tool config

Permission policy

MCP servers

skills 数组项

Multiagent

示例请求

示例响应

响应字段

错误

备注

相关