Copy

POST /api/v1/forward/identities/{identity_id}/templates/{template_id}/config config が存在しない場合は作成し、存在する場合は既存のアクティブな config を更新します。Identity Config は Template のベースラインに対するユーザーレベルのオーバーライドです。

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT または SAT>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	安全でないリクエストに対する任意のべき等性キー。

Path parameters

Parameter	Type	Required	Description
`identity_id`	string	Yes	Forward Identity ID。
`template_id`	string	Yes	Forward Template ID。

Body parameters

Parameter	Type	Required	Description
`name`	string	No	Config の表示名。
`identity_config`	object	Yes	ユーザーレベルのオーバーライド構成。
`metadata`	object	No	カスタムメタデータ。指定した場合は既存のメタデータを置き換えます。

Identity config object

identity_config は保存されるユーザーレベルのオーバーライド DSL です。これは Get Effective Config が返すコンパイル済みのランタイム構成ではありません。

Field	Type	Internal target	Description
`system`	object	Agent	システムプロンプトのオーバーライドまたは追加ルール。
`model`	string \| object	Agent	モデルのオーバーライド。モデル ID の文字列または Agent model オブジェクトを指定できます。
`tools`	object \| array	Agent	名前によるオーバーライド（オブジェクト）、またはランタイムツール配列の置換。Tools を参照。
`managed_tool_config`	object	Forward 管理対象機能	Capability または Bundle セレクターをキーとする差分スイッチ。Template の Forward 管理対象機能のベースラインを上書きします。
`mcp_servers`	object	Agent	MCP サーバー名をキーとする MCP サーバーのオーバーライド。
`skills`	object	Agent	Skill ID をキーとする Skill のオーバーライド。
`toolsets`	object	Agent	主に MCP ツールセットや組み込みツールグループを対象とする、ツールセットレベルのオーバーライド。
`agent_metadata`	object	Agent	コンパイルされた agent メタデータにマージされるメタデータ。
`vaults`	object	Session	Vault ID をキーとする Vault リソースのオーバーライド。
`files`	object	Session	File ID をキーとする File リソースのオーバーライド。Forward が `mount_path` を注入するため、呼び出し元はここで指定しません。
`github_repositories`	object	Session	Template の既存の binding key または新しい binding key をキーとする GitHub リポジトリのオーバーライド。
`environment_variables`	object	Session	変数名をキーとする Session 環境変数のオーバーライド。Template のデフォルト値の設定、削除、継承をサポートします。
`environment` / `environment_id`	Unsupported	Unsupported	Identity Config は Template の environment をオーバーライドできません。これらのフィールドを含むリクエストは `400 invalid_request_error` で失敗します。

サポートされる各オーバーライドフィールドに null を指定すると、現在のオーバーライドを削除して継承に戻せます。既存 Config の更新では、オブジェクトはフィールド単位で再帰的にマージされ、配列は全体が置換されます。更新セマンティクスを参照してください。

System

identity_config.system はオブジェクトで、コンパイル後の agent.system は文字列です。

フィールド	型	必須	説明
mode	string	いいえ	`replace` または `append`。オーバーライドに `mode` がない場合は `replace`。
content	string	いいえ	プロンプト本文。コンパイル時に前後の空白を除去します。オーバーライドにない場合は空文字列として扱います。

replace は Template のプロンプトを content で置換し、空文字列なら消去します。append は両方の前後の空白を除去し、両方が空でない場合に改行 1 つで連結します。追加する内容が空なら、空でない Template のプロンプトを保持します。 Template が You are a support assistant. の場合、Prefer CRM data when answering. を追加すると 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 を返します。

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

Model

identity_config.model には、モデル ID の文字列、またはモデル ID と任意の調整フィールドを含むオブジェクトを指定できます。

Field	Type	Required	Description
`id`	string	条件付き	モデル ID。モデルオブジェクトを初めて設定する場合は必須です。既存のオブジェクトを更新する場合は省略でき、保存済みのモデルオーバーライドから `id` を継承します。
`effort`	string	No	Reasoning effort。`none`、`low`、`medium`、`high`、`xhigh`、`max` を指定できます。モデルが対応する値は `efforts` を確認してください。
`context_window`	integer	No	希望するコンテキストウィンドウのトークン数。正の整数で、モデルの `available_context_windows` から選択します。
`speed`	string	No	推論速度。`standard` または `high` を指定します。最終的なモデルでこのフィールドが未設定の場合は `standard` を使用します。対応する値はモデル一覧が返す `speed` 配列を参照してください。

Tools

identity_config.tools はオブジェクトと配列の 2 形式をサポートします。

オブジェクト: ツール名をキーとして 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 はツールセット識別子をキーとするオブジェクトです。組み込みツールセットのキーには agent_toolset_20260401 を使用できます。MCP toolset は server name をキーにし、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	いいえ	ツール名をキーとする `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 をキーとします。agent.mcp_servers[] へのコンパイル時に map key が name になります。

フィールド	型	必須	説明
enabled	boolean	いいえ	省略時は `true`。`false` は継承した server を除去します。
type	string	いいえ	Forward は `http` を使用します。新規項目の既定値は `http`、既存項目の上書きでは元の型を継承します。
url	string	新規項目では必須	Streamable HTTP MCP endpoint URL。既存項目では Template の URL を継承できます。

MCP 認証は Vault で設定し、vaults で関連付けます。

Skills

identity_config.skills は Skill ID をキーとします。agent.skills[] へのコンパイル時に skill_id が自動設定されます。

フィールド	型	必須	説明
enabled	boolean	いいえ	省略時は `true`。`false` は継承した Skill を無効化します。
type	string	いいえ	`custom` または `qoder`。新規項目の既定値は `custom`、既存項目では元の型を継承します。
version	string	いいえ	空でないバージョン文字列。既存項目では元のバージョンを継承し、最終的に未指定なら最新バージョンを使用します。

Vaults and Files

identity_config.vaults と identity_config.files は、それぞれ Vault ID と File ID をキーにします。各項目には任意の boolean enabled を指定できます。省略時は 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 機能の Bundle。Schedule の作成、照会、削除をまとめて制御します。
`create_forward_schedule`	Schedule の作成のみを制御します。
`list_forward_schedules`	Schedule の照会のみを制御します。
`delete_forward_schedule`	Schedule の削除のみを制御します。
`drive`	Drive 機能全体を制御します。

各値は boolean 型の enabled のみを含むオブジェクトでなければなりません。Identity の差分オーバーライドでは、Template で使用する enabled_tools 配列は受け付けません。不明なセレクター、追加フィールド、enabled の欠落、型の誤りは HTTP 400 を返します。list_drive_entries などの drive の実行ツール名を、セレクターとして直接使用することはできません。同じ Identity Config に schedule と個別の Schedule セレクターが両方含まれる場合は、schedule の値が優先されます。例えば、同じレイヤーで list_forward_schedules.enabled=true を設定していても、schedule.enabled=false は 3 つの Schedule 機能をすべて無効化します。schedule が設定されていない場合は、個別のセレクターで Template から継承した Schedule 機能をそれぞれ上書きできます。schedule を null に設定すると、その Bundle のオーバーライドのみが削除され、保存済みの個別オーバーライドは削除されません。

GitHub リポジトリのオーバーライド

identity_config.github_repositories はキー付きオーバーレイです。Template から継承した同名の binding を上書きするか、新しい binding を追加できます。

Field	Type	Description
`url`	string\|null	継承したリポジトリの HTTPS URL を上書きします。検証と正規化は Template と同じルールです。
`authorization_token`	string\|null	リポジトリアクセストークンを上書きします。書き込み専用で、読み取り API からは返されません。
`mount_path`	string\|null	Session のマウントパスを上書きします。空でない値は `/` 以外の正規化された絶対パスである必要があります。`null` はこのフィールドのオーバーライドを削除します。Effective Config に継承可能なパスがない場合、デフォルトは `/data/workspace/<リポジトリ名>` です。
`enabled`	boolean\|null	`false` で無効化、`true` で明示的に有効化、`null` でこのフィールドのオーバーライドを削除します。

Request shape	Semantics
`github_repositories` を省略	現在のリポジトリオーバーレイを保持します。
`github_repositories: null`	リポジトリオーバーレイ全体を削除し、Template の継承に戻します。
binding を省略	既存のオーバーライドを保持し、存在しない場合は Template から継承します。
binding が `null`	binding のオーバーライドを削除し、Template の継承に戻します。
binding の `enabled` が `false`	同じキーの継承 binding を無効にします。
binding が object	同じキーの binding にフィールドをマージします。

マージ後の Effective Config で有効にできる binding は最大 20 個です。同じキーの binding で mount_path を省略すると Template の値を継承します。新しい binding に継承可能なパスがない場合は /data/workspace/<リポジトリ名> がデフォルトになります。有効化された各 binding は有効な url、authorization_token、mount_path に解決され、正規化後の URL とマウントパスが重複してはなりません。

環境変数のオーバーライド

identity_config.environment_variables は、環境変数名をキーとするオーバーライドオブジェクトです。

{
  "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" }`	Template に同名変数が設定されていても、Effective Config からその変数を削除します。
変数項目を省略	既存の Identity Config オーバーライドを保持し、オーバーライドがない場合は Template を継承します。
変数項目が `null`	その変数の Identity Config オーバーライドを削除し、Template の継承に戻します。
`environment_variables: null`	環境変数のオーバーライドレイヤー全体を削除し、Template のすべてのデフォルト値を復元します。

Update semantics

Request shape	Semantics
フィールドが省略されている	既存の値を保持します。
フィールドが非 null 値で存在する	そのフィールドを更新します。
フィールドが `null` で存在する	現在の Identity Config からそのフィールドを削除します。
`metadata` が省略されている	既存のメタデータを保持します。
`metadata` オブジェクト	既存のメタデータを置き換えます。
`metadata` `null`	メタデータをクリアします。

Resource map semantics

skills、vaults、files はリソース ID をマップキーとして使用します。マップ項目の内部に skill_id、vault_id、file_id、id、resource_id を含めないでください。これらのランタイムフィールドは、Forward がコンパイルした Effective Config にのみ現れます。

Map item value	Semantics
`{ "enabled": true }`	リソースを明示的に有効化またはオーバーライドします。
`{ "enabled": false }`	Template のベースラインに存在していても、リソースを明示的に無効化します。
項目が省略されている	Template のベースラインを継承します。
項目の値が `null`	このオーバーライドを削除し、Template の継承を復元します。

Example request

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": {}
  }'

Example response

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"
}

Response fields

Field	Type	Description
`type`	string	常に `config`。
`identity_id`	string	Forward Identity ID。
`template_id`	string	Forward Template ID。
`name`	string	Config の表示名。
`status`	string	Config のステータス。
`effective_hash`	string	コンパイルされた有効な構成のハッシュ。
`created_at`	string	作成タイムスタンプ。
`updated_at`	string	更新タイムスタンプ。

Errors

HTTP	Type	Code	発生条件
400	`invalid_request_error`	-	Config フィールド、GitHub binding の構造または値が不正、未対応の Environment オーバーライドが指定されている、またはリクエストボディが不正です。
401	`authentication_error`	`authentication_required`	PAT または SAT が無効または期限切れです。
404	`not_found_error`	-	Identity、Template、Skill、Vault、または File が存在しません。
409	`conflict_error`	-	Config の状態が競合しているか、Effective GitHub リポジトリの正規化済み URL またはマウントパスが重複しています。

Notes

省略された config フィールドは変更されません。
フィールドを null に設定すると、現在の Identity Config からそのフィールドが削除されます。
managed_tool_config はセレクターごとにマージされる差分オーバーライドであり、配列全体の置換ではありません。
リソースマップは、そのリソース ID をマップキーとして使用します。1 つのリソースの継承を復元するには、そのマップエントリを null に設定します。
Identity Config は environment_id のオーバーライドをサポートしていません。
identity_config.github_repositories.*.authorization_token は書き込み専用で、Config または Effective Config のレスポンスには含まれません。

アイデンティティ構成を作成または更新する

Headers

Path parameters

Body parameters

Identity config object

System

Model

Tools

Toolsets

MCP servers

Skills

Vaults and Files

Forward 管理対象機能のオーバーライド

GitHub リポジトリのオーバーライド

環境変数のオーバーライド

Update semantics

Resource map semantics

Example request

Example response

Response fields

Errors

Notes

アイデンティティ構成を取得する

有効な構成を取得する

​Headers

​Path parameters

​Body parameters

​Identity config object

​System

​Model

​Tools

​Toolsets

​MCP servers

​Skills

​Vaults and Files

​Forward 管理対象機能のオーバーライド

​GitHub リポジトリのオーバーライド

​環境変数のオーバーライド

​Update semantics

​Resource map semantics

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related

アイデンティティ構成を取得する

有効な構成を取得する

Headers

Path parameters

Body parameters

Identity config object

System

Model

Tools

Toolsets

MCP servers

Skills

Vaults and Files

Forward 管理対象機能のオーバーライド

GitHub リポジトリのオーバーライド

環境変数のオーバーライド

Update semantics

Resource map semantics

Example request

Example response

Response fields

Errors

Notes

Related