> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # 创建 Template > 创建 Forward Template 基线。 `POST /api/v1/forward/templates` Template 定义创建 Session 时使用的默认 Agent 配置和 Session 默认配置。 ## 请求头 | Header | 是否必填 | 说明 | | --------------- | ---- | ------------------ | | Authorization | 是 | `Bearer ` | | 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 配置。 | ## 示例请求 ```bash theme={null} 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** ```json theme={null} { "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 时自动补充文件挂载路径。 ## 相关