创建或更新 Identity Config

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

请求头

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

路径参数

参数	类型	是否必填	说明
identity_id	string	是	Forward Identity ID。
template_id	string	是	Forward Template ID。

请求体参数

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

Identity Config 对象

identity_config 是存储的用户级覆盖 DSL，不是 Get Effective Config 返回的编译后运行时配置。

字段	内部归类	说明
system	Agent	System Prompt 覆盖或追加规则。
model	Agent	模型覆盖。支持模型 ID string 或 Agent model object。
tools	Agent	内置工具覆盖，按工具名组织。
mcp_servers	Agent	MCP Server 覆盖，按 MCP server name 组织。
skills	Agent	Skill 覆盖，按 Skill ID 组织。
toolsets	Agent	Toolset 级覆盖，主要用于 MCP toolset 或内置工具组。
agent_metadata	Agent	合并到编译后的 Agent metadata。
vaults	Session	Vault 资源覆盖，按 Vault ID 组织。
files	Session	文件资源覆盖，按 File ID 组织；`mount_path` 由 Forward 注入，调用方无需提供。
github_repositories	Session	GitHub 仓库覆盖，按 Template 中的 binding key 或新增 binding key 组织。
environment_variables	Session	Session 环境变量覆盖，按变量名组织；支持设置、删除和继承 Template 默认值。
environment / environment_id	不支持	Identity Config 不能覆盖 Template 的执行环境；传入这些字段会返回 `400 invalid_request_error`。

Model

identity_config.model 支持两种等价形态：直接传模型 ID 字符串，或传包含模型 ID 和可选调优字段的对象。

字段	类型	是否必填	说明
id	string	是	模型标识；可通过列出模型接口查询可用值。
effort	string	否	Reasoning effort 等级。可选值：`none`、`low`、`medium`、`high`、`xhigh`、`max`；各模型实际支持的等级见列出模型返回的 `efforts`。
context_window	integer	否	期望的上下文窗口（token 数，正整数）；取值请从列出模型返回的 `available_context_windows` 中选择。

GitHub 仓库覆盖

identity_config.github_repositories 是 keyed overlay。它可以覆盖 Template 中的同名 binding，也可以增加新的 binding。

字段	类型	说明
url	string	null
authorization_token	string	null
mount_path	string	null
enabled	boolean	null

请求形态	语义
`github_repositories` 未出现	保留当前仓库覆盖层。
`github_repositories: null`	删除整个仓库覆盖层，恢复 Template 继承。
binding 未出现	保留已有覆盖；没有覆盖时继承 Template。
binding 为 `null`	删除该 binding 的当前覆盖，恢复 Template 继承。
binding 的 `enabled` 为 `false`	禁用同名继承 binding。
binding 为 object	按字段合并到同名 binding。

合并后的 Effective Config 最多包含 20 个启用的 binding。同名 binding 省略 mount_path 时继承 Template；新 binding 没有可继承路径时使用 /data/workspace/<仓库名>。每个启用项必须最终得到有效的 url、authorization_token 和 mount_path，且规范化后的 URL 和挂载路径不能重复。

环境变量覆盖

identity_config.environment_variables 是以环境变量名为 key 的覆盖对象。

{
  "identity_config": {
    "environment_variables": {
      "BASE_MODE": {
        "op": "set",
        "value": "identity"
      },
      "REMOVE_ME": {
        "op": "unset"
      },
      "USER_MODE": {
        "op": "set",
        "value": "enabled"
      }
    }
  }
}

请求形态	语义
`{ "op": "set", "value": "..." }`	新增变量，或覆盖 Template 中的同名变量。
`{ "op": "unset" }`	从 Effective Config 中移除该变量，即使 Template 已配置同名变量。
变量项未出现	保留当前 Identity Config 中已有的覆盖；没有覆盖时继承 Template。
变量项为 `null`	删除该变量的 Identity Config 覆盖，恢复继承 Template。
`environment_variables: null`	删除整个环境变量覆盖层，恢复 Template 的全部默认值。

更新语义

请求形态	语义
字段未出现	保留已有值。
字段出现且值非 `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_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "CRM profile",
  "identity_config": {
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 400000
    },
    "system": {
      "mode": "append",
      "content": "Prefer CRM data when answering."
    },
    "skills": {
      "skill_019f18f2749e": {
        "enabled": true,
        "type": "custom",
        "version": "1"
      },
      "skill_019f18f2750a": {
        "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_019f18f2761b": {
        "enabled": true
      }
    },
    "files": {
      "file_019eXXXX": {
        "enabled": true
      }
    },
    "environment_variables": {
      "CRM_REGION": {
        "op": "set",
        "value": "cn-shanghai"
      },
      "LEGACY_CRM_MODE": {
        "op": "unset"
      }
    },
    "github_repositories": {
      "source": {
        "mount_path": "/data/workspace/support-agent",
        "authorization_token": "github_pat_xxx"
      },
      "legacy": {
        "enabled": false
      }
    }
  },
  "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"
}

响应字段

字段	类型	说明
type	string	固定为 `config`。
identity_id	string	Forward Identity ID。
template_id	string	Forward Template ID。
effective_hash	string	编译后的 Effective Config hash。

错误

HTTP	Type	Code	触发条件
400	`invalid_request_error`	-	配置字段、GitHub binding 结构或字段取值不合法，传入了不支持的 Environment 覆盖，或请求体非法。
404	`not_found_error`	-	Identity、Template、Skill、Vault 或 File 不存在。
409	`conflict_error`	-	Config 状态冲突，或 Effective GitHub 仓库的规范化 URL、挂载路径重复。
401	`authentication_error`	`authentication_required`	PAT 或 SAT 无效或已过期。

备注

未传字段保持不变。
字段传 null 表示从当前 Identity Config 中删除该字段。
资源型 map 使用资源 ID 作为 key；某个资源项传 null 表示恢复继承。
Identity Config 当前不支持覆盖 environment_id。
identity_config.github_repositories.*.authorization_token 是 write-only 字段，不会出现在 Config 或 Effective Config 响应中。

创建或更新 Identity Config

请求头

路径参数

请求体参数

Identity Config 对象

Model

GitHub 仓库覆盖

环境变量覆盖

更新语义

资源 map 语义

示例请求

示例响应

响应字段

错误

备注

相关

获取 Identity Config

获取 Effective Config

​请求头

​路径参数

​请求体参数

​Identity Config 对象

​Model

​GitHub 仓库覆盖

​环境变量覆盖

​更新语义

​资源 map 语义

​示例请求

​示例响应

​响应字段

​错误

​备注

​相关

获取 Identity Config

获取 Effective Config

请求头

路径参数

请求体参数

Identity Config 对象

Model

GitHub 仓库覆盖

环境变量覆盖

更新语义

资源 map 语义

示例请求

示例响应

响应字段

错误

备注

相关