跳转到主要内容
POST /api/v1/forward/identities/{identity_id}/templates/{template_id}/config 如果配置不存在则创建，已存在则更新 active 配置。Identity Config 是覆盖 Template 基线的用户级配置层。

​
请求头

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

​
路径参数

参数类型是否必填说明
identity_idstring是Forward Identity ID。
template_idstring是Forward Template ID。

​
请求体参数

参数类型是否必填说明
namestring否Config 展示名。
identity_configobject是用户级覆盖配置。
metadataobject否业务元数据；传入时整体替换已有 metadata。

​
Identity Config 对象

identity_config 是存储的用户级覆盖 DSL，不是 Get Effective Config 返回的编译后运行时配置。
字段内部归类说明
systemAgentSystem Prompt 覆盖或追加规则。
modelAgent模型覆盖。
toolsAgent内置工具覆盖，按工具名组织。
mcp_serversAgentMCP Server 覆盖，按 MCP server name 组织。
skillsAgentSkill 覆盖，按 Skill ID 组织。
toolsetsAgentToolset 级覆盖，主要用于 MCP toolset 或内置工具组。
agent_metadataAgent合并到编译后的 Agent metadata。
vaultsSessionVault 资源覆盖，按 Vault ID 组织。
filesSession文件资源覆盖，按 File ID 组织；mount_path 由 Forward 注入，调用方无需提供。
environment / environment_id不支持Identity Config 不能覆盖 Template 的执行环境；传入这些字段会返回 400 invalid_request_error。

​
更新语义

请求形态语义
字段未出现保留已有值。
字段出现且值非 null更新该字段。
字段出现且值为 null从当前 Identity Config 中删除该字段。
metadata 未传保留已有 metadata。
metadata 为对象整体替换已有 metadata。
metadata 为 null清空 metadata。

​
资源 map 语义

skills、vaults、files 使用资源 ID 作为 map key。配置项内不要再写 skill_id、vault_id、file_id、id 或 resource_id；这些运行时字段只会出现在 Forward 编译后的 Effective Config 中。
map 项值语义
{ "enabled": true }显式启用或覆盖该资源。
{ "enabled": false }显式禁用该资源，即使 Template 基线中存在也会移除或屏蔽。
资源项不存在继承 Template 基线。
资源项值为 null删除当前覆盖，恢复继承 Template 基线。

​
示例请求

curl -s -X POST 'https://api.qoder.com/api/v1/forward/identities/idn_019eabc123/templates/tmpl_support/config' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "CRM profile",
  "identity_config": {
    "system": {
      "mode": "append",
      "content": "Prefer CRM data when answering."
    },
    "skills": {
      "skill_customer_reply": {
        "enabled": true,
        "type": "custom",
        "version": "1"
      },
      "skill_marketing_copy": {
        "enabled": false
      }
    },
    "mcp_servers": {
      "mcp_crm": {
        "enabled": true,
        "type": "http",
        "url": "https://crm.example.com/mcp"
      }
    },
    "tools": {
      "Read": {
        "enabled": true
      },
      "Grep": {
        "enabled": true
      },
      "WebSearch": {
        "enabled": true
      }
    },
    "vaults": {
      "vault_crm": {
        "enabled": true
      }
    },
    "files": {
      "file_019eXXXX": {
        "enabled": true
      }
    }
  },
  "metadata": {}
}'

​
示例响应

HTTP 200 OK 
{
  "type": "config",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_support",
  "name": "CRM profile",
  "status": "active",
  "effective_hash": "sha256:...",
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:00:00Z"
}

​
响应字段

字段类型说明
typestring固定为 config。
identity_idstringForward Identity ID。
template_idstringForward Template ID。
effective_hashstring编译后的 Effective Config hash。

​
错误

HTTPTypeCode触发条件
400invalid_request_error-配置字段不合法、传入了不支持的 Environment 覆盖，或请求体非法。
404not_found_error-Identity、Template、Skill、Vault 或 File 不存在。
409conflict_error-Config 状态冲突。
401authentication_errorauthentication_requiredPAT 无效或已过期。

​
注意事项

  • 未传字段保持不变。
  • 字段传 null 表示从当前 Identity Config 中删除该字段。
  • 资源型 map 使用资源 ID 作为 key；某个资源项传 null 表示恢复继承。
  • Identity Config 当前不支持覆盖 environment_id。

​
相关

获取 Identity Config

获取 Effective Config