创建 Template

POST /api/v1/forward/templates Template 定义创建 Session 时使用的默认 Agent 配置和 Session 默认配置。

请求头

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

请求体参数

参数	类型	是否必填	说明
name	string	是	Template 名称，1-256 个字符，租户内唯一。
model	string \| object	是	模型标识。可传 string（如 `"ultimate"`），或传 Agent model 对象以同时配置 `effort`、`speed` 或 `context_window`。可通过列出模型接口查询可用值。
environment_id	string	是	创建 Session 时默认使用的 Environment ID。
description	string	否	Template 描述，最多 2048 个字符。
system	string	否	System Prompt，最多 100,000 个字符。
max_tool_rounds	integer\|null	否	单次 Turn 的工具调用轮数上限，必须为正整数。省略或传 `null` 时使用平台默认值；Forward 不额外设置默认值。
tools	array	否	工具配置列表，最多 128 项。
managed_tool_config	object\|null	否	Forward 托管能力基线；按 `enabled_tools` 完整声明启用的能力选择器。
mcp_servers	array	否	MCP Server 配置列表，最多 20 项。
skills	array	否	Skill 绑定列表，最多 20 项。
multiagent	object\|null	否	Multi-agent 协作配置。`type` 必须为 `coordinator`；省略或传 `null` 表示不启用。
vaults	object	否	默认 Vault 配置，按 Vault ID 组织。
files	object	否	默认文件资源配置，按 file ID 组织。
github_repositories	object	否	默认 GitHub 仓库配置，按调用方指定的 binding key 组织，最多 20 项。
environment_variables	object\|string	否	默认 Session 环境变量。
metadata	object	否	自定义元数据。

嵌套配置对象

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。配置项内无需重复填写 vault_id、id 或 resource_id。

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

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

文件资源

files 是按 File ID 组织的 map。在会话时会将文件挂载到环境的 /data/workspace/<文件名> 路径下。

字段	类型	是否必填	说明
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/<仓库名>`。

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 是 Template 顶层字段，用于选择由 Forward 提供并运行的托管能力。Forward 负责提供对应的工具定义；调用方只需指定 Capability 或 Bundle 选择器，不需要在 tools 中重复配置这些工具。

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

字段	类型	是否必填	说明
enabled_tools	array	否	完整的启用选择器列表；空数组表示不启用任何 Forward 托管能力。

当前支持 schedule、create_forward_schedule、list_forward_schedules、delete_forward_schedule 和 drive。其中 schedule 是 Schedule 能力组合的便捷写法，等价于同时启用 create_forward_schedule、list_forward_schedules 和 delete_forward_schedule；drive 表示完整的 Drive 能力。Bundle/Capability 选择器只用于配置，Session 运行时会获得对应的、可独立调用的 Forward 托管工具；Template 响应会保留请求中的 schedule 或 drive，不会将其改写为执行工具名。未知或重复的选择器会被拒绝。

请求形态	语义
字段未出现	不创建托管能力基线，默认不启用任何 Forward 托管能力。
`null`、`{}` 或 `{ "enabled_tools": [] }`	创建显式为空的托管能力基线。
`enabled_tools` 为非空数组	以该数组作为完整基线。

浏览器能力（Beta）

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

{
  "type": "browser_toolset_20260714"
}

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

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

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 必须存在且当前调用方有权访问。

{
  "multiagent": {
    "type": "coordinator",
    "agents": [
      {"type": "agent", "template_id": "tmpl_research", "name": "Research Agent"},
      {"type": "self"}
    ]
  }
}

名单包含普通 Agent 或 self 时，tools 需要包含 agent_toolset_20260401；仅配置 Advisor 时不要求该工具集。创建 Template 时 Forward 会自动补齐该工具集。

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' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Support assistant",
  "description": "Handles customer support requests",
  "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",
        "name": "Research Agent"
      },
      {
        "type": "self"
      }
    ]
  },
  "environment_id": "env_xxx",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    }
  },
  "files": {},
  "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"
  },
  "metadata": {}
}'

示例响应

HTTP 200 OK

{
  "type": "template",
  "id": "tmpl_support",
  "name": "Support assistant",
  "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",
        "name": "Research Agent"
      },
      {
        "type": "self"
      }
    ]
  },
  "environment_id": "env_xxx",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    }
  },
  "files": {},
  "github_repositories": {
    "source": {
      "url": "https://github.com/acme/support-agent",
      "mount_path": "/data/workspace/support-agent"
    }
  },
  "environment_variables": {
    "BASE_MODE": "support"
  },
  "metadata": {},
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:00:00Z"
}

响应字段

字段	类型	说明
type	string	固定为 `template`。
id	string	Template ID。
status	string	`active` 或 `archived`。
`model`	string \| object	与请求提交的形态一致；对象形态保留 `id`、`effort`、`speed` 和 `context_window`。
max_tool_rounds	integer	单次 Turn 的工具调用轮数上限；未设置或已清除时省略该字段，不返回 `null`。
managed_tool_config	object	Template 的 Forward 托管能力基线，配置存在时以 `enabled_tools` 数组返回。
multiagent	object\|null	Multi-agent 协作配置；未设置时为 `null`。
environment_id	string	默认 Environment ID。
vaults	object	默认 Vault 配置，按 Vault ID 组织。
files	object	默认文件资源配置。
github_repositories	object	默认 GitHub 仓库配置；包含规范化后的 `url` 和最终 `mount_path`，不包含 `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`	-	引用的 Environment、Skill、Vault 或 File 不存在。
409	`conflict_error`	-	Template 名称已存在，或 GitHub 仓库的规范化 URL、挂载路径重复。
401	`authentication_error`	`authentication_required`	PAT 或 SAT 无效或已过期。

备注

创建时不要传 template_id，ID 由 Forward 生成。
files 使用 file ID 作为 map key，配置项内不要重复写 file_id、id 或 resource_id。
Forward 在创建 Session 时自动补充文件挂载路径。
不传 managed_tool_config 时默认不启用 Forward 托管能力。
存量请求中的 managed_tool_config.tools 和 schedule_creation_enabled 仍兼容处理；新接入应使用 managed_tool_config.enabled_tools。
github_repositories.*.authorization_token 是 write-only 字段，不会出现在 Template 响应中。

创建 Template

请求头

请求体参数

嵌套配置对象

Model

Vaults

文件资源

GitHub 仓库

tools 数组项

Forward 托管能力

浏览器能力（Beta）

Tool config

Permission policy

MCP servers

skills 数组项

Multiagent

Advisor

示例请求

示例响应

响应字段

错误

备注

相关

列出 Templates

创建 Session

​请求头

​请求体参数

​嵌套配置对象

​Model

​Vaults

​文件资源

​GitHub 仓库

​tools 数组项

​Forward 托管能力

​浏览器能力（Beta）

​Tool config

​Permission policy

​MCP servers

​skills 数组项

​Multiagent

​Advisor

​示例请求

​示例响应

​响应字段

​错误

​备注

​相关

列出 Templates

创建 Session

请求头

请求体参数

嵌套配置对象

Model

Vaults

文件资源

GitHub 仓库

tools 数组项

Forward 托管能力

浏览器能力（Beta）

Tool config

Permission policy

MCP servers

skills 数组项

Multiagent

Advisor

示例请求

示例响应

响应字段

错误

备注

相关