> ## 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.

# 创建/更新 Identity Config

> 创建或更新某个 Identity 在指定 Template 下的用户级配置。

`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\_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   | 模型覆盖。                                                                      |
| 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 注入，调用方无需提供。                     |
| 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 基线。          |

## 示例请求

```bash theme={null}
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**

```json theme={null}
{
  "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` | -                         | 配置字段不合法、传入了不支持的 Environment 覆盖，或请求体非法。    |
| 404  | `not_found_error`       | -                         | Identity、Template、Skill、Vault 或 File 不存在。 |
| 409  | `conflict_error`        | -                         | Config 状态冲突。                              |
| 401  | `authentication_error`  | `authentication_required` | PAT 无效或已过期。                               |

## 注意事项

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

## 相关

<CardGroup cols={2}>
  <Card title="获取 Identity Config" icon="file-lines" href="/cloud-agents/api/forward/identities/get-config" />

  <Card title="获取 Effective Config" icon="layer-group" href="/cloud-agents/api/forward/identities/effective" />
</CardGroup>