创建 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` 或 `context_window`。可通过列出模型接口查询可用值。
environment_id	string	是	创建 Session 时默认使用的 Environment ID。
description	string	否	Template 描述，最多 2048 个字符。
system	string	否	System Prompt，最多 100,000 个字符。
tools	array	否	工具配置列表，最多 128 项。
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	否
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` 中选择。

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。

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

字段	类型	是否必填	说明
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": {
    "type": "coordinator",
    "agents": [
      {"type": "agent", "template_id": "tmpl_research", "name": "Research Agent"},
      {"type": "self"}
    ]
  }
}

使用 multiagent 时，tools 需要包含 agent_toolset_20260401。创建 Template 时 Forward 会自动补齐该工具集。

示例请求

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",
  "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",
        "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",
  "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",
        "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` 和 `context_window`。
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` 结构不合法，`agents` 数量不在 1-20 之间，或引用的 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 时自动补充文件挂载路径。
github_repositories.*.authorization_token 是 write-only 字段，不会出现在 Template 响应中。

创建 Template

请求头

请求体参数

嵌套配置对象

Model

Vaults

文件资源

GitHub 仓库

tools 数组项

浏览器能力（Beta）

Tool config

Permission policy

MCP servers

skills 数组项

Multiagent

示例请求

示例响应

响应字段

错误

备注

相关

列出 Templates

创建 Session

​请求头

​请求体参数

​嵌套配置对象

​Model

​Vaults

​文件资源

​GitHub 仓库

​tools 数组项

​浏览器能力（Beta）

​Tool config

​Permission policy

​MCP servers

​skills 数组项

​Multiagent

​示例请求

​示例响应

​响应字段

​错误

​备注

​相关

列出 Templates

创建 Session

请求头

请求体参数

嵌套配置对象

Model

Vaults

文件资源

GitHub 仓库

tools 数组项

浏览器能力（Beta）

Tool config

Permission policy

MCP servers

skills 数组项

Multiagent

示例请求

示例响应

响应字段

错误

备注

相关