创建或更新 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	object	Agent	System：System Prompt 覆盖或追加规则。
model	string \| object	Agent	Model：模型 ID 或包含调优字段的对象。
tools	object \| array	Agent	Tools：按工具名覆盖，或用运行时工具数组整体替换。
managed_tool_config	object	Forward 托管能力	按 Capability 或 Bundle 选择器组织的稀疏开关，用于覆盖 Template 的 Forward 托管能力基线。
mcp_servers	object	Agent	MCP servers：按 MCP server name 覆盖。
skills	object	Agent	Skills：按 Skill ID 覆盖。
toolsets	object	Agent	Toolsets：内置工具集或 MCP toolset 覆盖。
agent_metadata	object	Agent	合并到编译后的 Agent metadata。
vaults	object	Session	Vaults 与 Files：按 Vault ID 覆盖。
files	object	Session	Vaults 与 Files：按 File ID 覆盖；挂载路径由 Forward 注入。
github_repositories	object	Session	GitHub 仓库覆盖：按 binding key 覆盖。
environment_variables	object	Session	Session 环境变量覆盖，按变量名组织；支持设置、删除和继承 Template 默认值。
environment / environment_id	不支持	不支持	Identity Config 不能覆盖 Template 的执行环境；传入这些字段会返回 `400 invalid_request_error`。

上述可覆盖字段均可传 null 以删除当前覆盖、恢复继承。更新已有 Config 时，对象按字段递归合并，数组整体替换；详见更新语义。

System

identity_config.system 使用以下对象结构，编译后的 agent.system 为字符串。

字段	类型	是否必填	说明
mode	string	否	可选值：`replace`、`append`。覆盖层中没有 `mode` 时默认 `replace`。
content	string	否	提示词内容，编译时去除首尾空白；覆盖层中未设置时按空字符串处理。

mode	编译行为
`replace`	用 `content` 替换 Template 的 System Prompt；空字符串可清空提示词。
`append`	将 `content` 追加到 Template 的 System Prompt 后；拼接前去除两段文本首尾空白，两者均非空时用一个换行符连接。`content` 为空时保留非空的 Template 提示词。

例如，Template 的 system 为 You are a support assistant.：

{
  "identity_config": {
    "system": {
      "mode": "append",
      "content": "Prefer CRM data when answering."
    }
  }
}

编译后的 agent.system 为 You are a support assistant.\nPrefer CRM data when answering.。改为 replace 后，结果仅为 Prefer CRM data when answering.。更新时只传 content 会保留已存的 mode，不会把已有 append 重置为 replace。要切换模式，请显式传入 mode；传 system: null 则删除整个 System 覆盖，恢复 Template 提示词。非法模式（如 prepend）返回 400 invalid_request_error。

Model

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

字段	类型	是否必填	说明
`id`	string	条件必填	模型标识；首次设置模型对象时必填。更新已有对象时可省略，继承已存模型覆盖中的 `id`。
effort	string	否	Reasoning effort 等级。可选值：`none`、`low`、`medium`、`high`、`xhigh`、`max`；各模型实际支持的等级见列出模型返回的 `efforts`。
context_window	integer	否	期望的上下文窗口（token 数，正整数）；取值请从列出模型返回的 `available_context_windows` 中选择。
`speed`	string	否	推理速度，可选值：`standard`、`high`；最终模型未设置该字段时使用 `standard`。各模型实际支持的速度见列出模型返回的 `speed` 数组。

Tools

identity_config.tools 支持两种形态：

对象：以工具名为 key，对 Template 中的工具配置进行覆盖。内置工具项结构如下，工具名见 Agent 结构 — 内置工具名。
数组：整体替换 Template 的 tools；数组项见 Agent tool。需要保留的工具必须一并传入，[] 表示空工具列表；之后仍会叠加 toolsets 覆盖。

对象项字段	类型	是否必填	说明
enabled	boolean	否	省略时按 `true` 编译；`false` 隐藏并拒绝该工具。
permission_policy	object	否	工具权限策略，结构见 Permission policy；`type` 为 `always_allow`、`always_ask` 或 `always_deny`。

对象形态也可按名称启用或禁用 Template 中已有的 custom 工具，但这些项只支持 enabled。新增或修改自定义工具定义时使用数组形态。

{
  "identity_config": {
    "tools": {
      "Bash": {
        "enabled": true,
        "permission_policy": { "type": "always_ask" }
      },
      "WebSearch": { "enabled": false }
    }
  }
}

Toolsets

identity_config.toolsets 是以工具集标识为 key 的对象。内置工具集可使用 agent_toolset_20260401 作为 key；MCP toolset 建议以 server name 作为 key，并显式填写 type 和 mcp_server_name。

配置项字段	类型	是否必填	说明
type	string	否	`agent_toolset_20260401` 或 `mcp_toolset`；建议显式填写。
enabled	boolean	否	省略时按 `true` 处理；`false` 从有效工具列表中移除整个工具集。
mcp_server_name	string	MCP 时建议填写	对应 MCP server 名称；`type` 为 `mcp_toolset` 且省略此字段时使用 map key。
tools	object	否	以工具名为 key 的覆盖对象；每项支持上文的 `enabled`、`permission_policy`。MCP 工具使用 server 暴露的原始工具名，不带 `mcp__` 前缀。
configs	array	否	运行时 Tool config 数组；传入时整体替换该工具集继承的 `configs`。通常使用 `tools` 做逐工具覆盖即可。

toolsets.*.tools 编译为 agent.tools[].configs，按工具名合并；未覆盖的工具配置保留。若同时传入 configs 和 tools，先采用 configs 数组，再叠加 tools。同一内置工具同时出现在顶层 tools 对象与 toolsets 时，最后应用顶层 tools 对象的覆盖。

{
  "identity_config": {
    "toolsets": {
      "mcp_crm": {
        "type": "mcp_toolset",
        "mcp_server_name": "mcp_crm",
        "tools": {
          "search_customers": { "enabled": true },
          "delete_customer": {
            "enabled": true,
            "permission_policy": { "type": "always_ask" }
          }
        }
      }
    }
  }
}

该示例要求 Template 或 Identity Config 中存在名为 mcp_crm 的 MCP server。

MCP servers

identity_config.mcp_servers 以 MCP server name 为 key。编译为 agent.mcp_servers[] 时，由 map key 填入 name。

配置项字段	类型	是否必填	说明
enabled	boolean	否	省略时按 `true` 处理；`false` 移除继承的 server。
type	string	否	Forward 使用 `http`；新增项省略时默认为 `http`，覆盖已有项时继承其类型。
url	string	新增时必填	Streamable HTTP MCP endpoint URL；覆盖已有 server 时可继承 Template 中的 URL。

MCP 鉴权通过 Vault 配置，再通过 vaults 绑定。

Skills

identity_config.skills 以 Skill ID 为 key，编译为 agent.skills[] 时自动填入 skill_id。

配置项字段	类型	是否必填	说明
enabled	boolean	否	省略时按 `true` 处理；`false` 禁用继承的 Skill。
type	string	否	`custom` 或 `qoder`；新增项省略时默认为 `custom`，覆盖已有项时继承其类型。
version	string	否	非空版本字符串；覆盖已有项时继承其版本，最终未指定版本时使用最新版本。

Vaults 与 Files

identity_config.vaults 和 identity_config.files 分别以 Vault ID、File ID 为 key。

配置项字段	类型	是否必填	说明
enabled	boolean	否	省略时按 `true` 处理；`false` 禁用 Template 中继承的资源。

例如，"vaults": { "vault_019f18f2761b": { "enabled": true } } 启用该 Vault。编译后，Vault ID 进入 session.vault_ids，文件进入 session.resources；文件挂载路径由 Forward 注入，调用方无需提供 mount_path。

Forward 托管能力覆盖

Template 通过顶层 managed_tool_config.enabled_tools 提供完整的 Capability/Bundle 选择器基线；Identity Config 通过 identity_config.managed_tool_config 只保存需要改变的稀疏开关。Forward 负责提供最终生效能力对应的工具，调用方不需要在 tools 中配置对应实现。未出现的选择器继承 Template，因此 Template 后续新增能力时不需要回刷 Identity Config。

{
  "identity_config": {
    "managed_tool_config": {
      "schedule": {
        "enabled": false
      },
      "drive": {
        "enabled": true
      }
    }
  }
}

请求形态	语义
某选择器为 `{ "enabled": true }`	对该 Identity 显式启用对应托管能力。
某选择器为 `{ "enabled": false }`	对该 Identity 显式禁用对应托管能力。
某选择器未出现	保留已存的该项覆盖；没有覆盖时继承 Template。
某选择器为 `null`	删除该项覆盖，恢复继承 Template。
`managed_tool_config: {}`	不修改已存的单项覆盖。
`managed_tool_config: null`	清空全部 Forward 托管能力覆盖，恢复继承 Template。

支持的选择器如下：

选择器	语义
`schedule`	Schedule 能力组合，同时控制创建、查询和删除 Schedule。
`create_forward_schedule`	只控制创建 Schedule。
`list_forward_schedules`	只控制查询 Schedule。
`delete_forward_schedule`	只控制删除 Schedule。
`drive`	控制完整的 Drive 能力。

每项必须是只含 boolean 类型 enabled 的对象。Identity 稀疏覆盖不接受 Template 使用的 enabled_tools 数组；未知选择器、额外字段、缺少 enabled 或类型错误均返回 HTTP 400。drive 的执行工具名（例如 list_drive_entries）不能直接作为选择器。当同一 Identity Config 同时出现 schedule 和细粒度 Schedule 选择器时，schedule 的值优先。例如，schedule.enabled=false 会禁用全部三个 Schedule 能力，即使同层还设置了 list_forward_schedules.enabled=true。未设置 schedule 时，可以用细粒度选择器单独覆盖从 Template 继承的 Schedule 能力。将 schedule 设置为 null 只删除该组合覆盖，不会删除已经保存的细粒度覆盖。

GitHub 仓库覆盖

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

字段	类型	说明
url	string\|null	覆盖继承仓库的 HTTPS URL；校验和规范化规则与 Template 相同。
authorization_token	string\|null	覆盖仓库访问 token；仅写入，读取接口不会回显。
mount_path	string\|null	覆盖 Session 挂载路径；非空值必须是除 `/` 外的规范化绝对路径。`null` 删除该字段覆盖；Effective Config 中没有可继承路径时，默认 `/data/workspace/<仓库名>`。
enabled	boolean\|null	`false` 禁用同名 binding；`true` 显式启用；`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
      }
    },
    "managed_tool_config": {
      "schedule": {
        "enabled": false
      },
      "drive": {
        "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": {}
}'

示例响应

首次创建 Config 时返回 HTTP 201 Created；更新已有 Config 时返回 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 中删除该字段。
managed_tool_config 是按选择器合并的稀疏覆盖，不是完整数组替换。
资源型 map 使用资源 ID 作为 key；某个资源项传 null 表示恢复继承。
Identity Config 当前不支持覆盖 environment_id。
identity_config.github_repositories.*.authorization_token 是 write-only 字段，不会出现在 Config 或 Effective Config 响应中。

创建或更新 Identity Config

请求头

路径参数

请求体参数

Identity Config 对象

System

Model

Tools

Toolsets

MCP servers

Skills

Vaults 与 Files

Forward 托管能力覆盖

GitHub 仓库覆盖

环境变量覆盖

更新语义

资源 map 语义

示例请求

示例响应

响应字段

错误

备注

相关

获取 Identity Config

获取 Effective Config

​请求头

​路径参数

​请求体参数

​Identity Config 对象

​System

​Model

​Tools

​Toolsets

​MCP servers

​Skills

​Vaults 与 Files

​Forward 托管能力覆盖

​GitHub 仓库覆盖

​环境变量覆盖

​更新语义

​资源 map 语义

​示例请求

​示例响应

​响应字段

​错误

​备注

​相关

获取 Identity Config

获取 Effective Config

请求头

路径参数

请求体参数

Identity Config 对象

System

Model

Tools

Toolsets

MCP servers

Skills

Vaults 与 Files

Forward 托管能力覆盖

GitHub 仓库覆盖

环境变量覆盖

更新语义

资源 map 语义

示例请求

示例响应

响应字段

错误

备注

相关