创建 Template

创建 Forward Template 基线。

POST /api/v1/forward/templates

Template 定义创建 Session 时使用的默认 Agent 配置和 Session 默认配置。

​

请求头

Header	是否必填	说明
Authorization	是	Bearer <PAT>
Content-Type	是	application/json
Idempotency-Key	否	有副作用请求可选的幂等键。

​

请求体参数

参数	类型	是否必填	说明
name	string	是	Template 名称，1-256 个字符，租户内唯一。
model	string	是	模型标识，例如 ultimate。
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	否	Managed Agents 配置。
vault_ids	array	否	默认 Vault ID 列表。
files	object	否	默认文件资源配置，按 file ID 组织。
environment_variables	object | string	否	默认 Session 环境变量。
metadata	object	否	自定义元数据。

​

嵌套配置对象

​

文件资源

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

​

示例请求

curl -s -X POST 'https://api.qoder.com/api/v1/forward/templates' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Support assistant",
  "description": "Handles customer support requests",
  "model": "ultimate",
  "system": "You are a helpful support assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "environment_id": "env_support",
  "vault_ids": [
    "vault_crm"
  ],
  "files": {},
  "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": "ultimate",
  "system": "You are a helpful support assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "environment_id": "env_support",
  "vault_ids": [
    "vault_crm"
  ],
  "files": {},
  "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。
environment_id	string	默认 Environment ID。
vault_ids	array	默认 Vault ID 列表。
files	object	默认文件资源配置。

​

错误

HTTP	Type	Code	触发条件
400	invalid_request_error	-	请求体或字段取值不合法。
404	not_found_error	-	引用的 Environment、Skill、Vault 或 File 不存在。
409	conflict_error	-	Template 名称已存在。
401	authentication_error	authentication_required	PAT 无效或已过期。

​

注意事项

• 创建时不要传 template_id，ID 由 Forward 生成。
• files 使用 file ID 作为 map key，配置项内不要重复写 file_id、id 或 resource_id。
• Forward 在创建 Session 时自动补充文件挂载路径。

​

相关

列出 Templates

创建 Session