建立 Template - Qoder CN 系列

建立 Forward Template 基準。

要求標頭

Header	是否必填	說明
Authorization	是	`Bearer <PAT>`
Content-Type	是	`application/json`
Idempotency-Key	否	有副作用請求可選的等冪鍵。

請求體參數

參數	類型	是否必填	說明
`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	否	Managed Agents 配置。
`vaults`	object	否	預設 Vault 配置，按 Vault ID 組織。
`files`	object	否	預設檔案資源配置，按 file ID 組織。
`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` 中選擇。

Vaults

vaults 是按 Vault ID 組織的 map。每個配置項支援可選的 enabled boolean；省略等同於 true。配置項內無需重複填寫 vault_id、id 或 resource_id。

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

響應統一返回對象形態的 vaults。

檔案資源

files 是按 File ID 組織的 map。在會話時會將file掛載在環境的/data/workspace/<檔案名稱>路徑下。

欄位	類型	是否必填	說明
`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": {
    "id": "ultimate",
    "effort": "high",
    "context_window": 400000
  },
  "system": "You are a helpful support assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "environment_id": "env_xxx",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    }
  },
  "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": {
    "id": "ultimate",
    "effort": "high",
    "context_window": 400000
  },
  "system": "You are a helpful support assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "environment_id": "env_xxx",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    }
  },
  "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。
`model`	string \| object	與請求提交的形態一致；對象形態保留 `id`、`effort` 和 `context_window`。
`vaults`	object	預設 Vault 配置，按 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 時自動補充檔案掛載路徑。

Qoder CN 系列：建立 Template