动态修改 Agent 配置（Claw 模式）

Claw 模式支持在运行时按用户或按会话动态调整 Agent 配置（更换模型、装卸 Skill、绑定插件工具），无需修改应用配置，也无需重新发布。本文说明该机制的启用前提、调用链路，以及各类配置变更的接口用法。

一、前提条件

前提 1：开启「允许在对话中动态修改配置」开关

在应用的高级设置中开启该开关（也可通过 ModifyApp 接口开启）。它是动态配置能力的总开关：仅当开关开启时，后续传入的用户级 AgentId 与运行时配置才会生效；否则对话仅使用应用发布时的固定配置。

通过接口开启开关：

req = models.ModifyAppRequest()req.AppId = app_idreq.Config = models.AppConfig()req.Config.Mode = models.AppModeConfig()req.Config.Mode.ClawAgentConfig = models.ClawAgentConfig()req.Config.Mode.ClawAgentConfig.CustomConfig = models.ClawAgentCustomConfig()req.Config.Mode.ClawAgentConfig.CustomConfig.Enabled = Truereq.UpdateMask = models.FieldMask()req.UpdateMask.Paths = ["Config.Mode.ClawAgentConfig"]client.ModifyApp(req)

注意：

修改开关后需要调用 CreateRelease 重新发布才能生效，可参考从零搭建一个 Claw 模式应用 > 发布应用。

前提 2：获取用户级 Agent

按用户维度修改配置，需要一个归属于该用户的 Agent 实例，而非直接修改应用的配置端 Agent。通过 CopyAgentFromApp 从应用复制出用户级 Agent：

Kind 枚举值（关于开发者/使用者的概念，详情请参见 概览）：

req = models.CopyAgentFromAppRequest()req.AppId = app_idreq.Kind = 1                  # 用户级 Agentresp = client.CopyAgentFromApp(req)agent_id = resp.ParentAgentId   # 该用户后续对话与改配置都用这个 AgentIdprint(f"agent_id={agent_id}")

二、将用户级 Agent 绑定到会话

创建会话时将上一步的 AgentId 传入 CreateConversation（仅在开关开启时可用）：

Type 枚举值：5 = API 接入。详情请参见 从零搭建一个 Claw 模式应用 > 步骤 6：创建会话。

req = models.CreateConversationRequest()req.Type = 5                  # API 接入req.AppId = app_idreq.AppKey = APP_KEYreq.UserId = USER_IDreq.AgentId = agent_id       # 绑定用户级 Agentresp = client.CreateConversation(req)conversation_id = resp.ConversationId

绑定后，针对该 AgentId 的任何配置变更仅作用于该用户的会话链路。

三、动态修改配置

应用级 vs Agent 级：开启动态配置开关是应用级设置（通过 ModifyApp，所有 Agent 共享），而下文的模型/Skill/工具变更是 Agent 级设置（通过 ModifyAgent，每个用户级 Agent 独立）。关于两者的区别详细请参见 从零搭建一个 Claw 模式应用 > 步骤 4：修改配置（可选）。

所有 Agent 级配置变更均通过 ModifyAgent 完成，由 UpdateMask.Paths 指定需更新的字段，其余字段保持不变。

3.1 更换模型

先通过 DescribeModelList 拉取 Claw 场景可用模型（ModelScene=18 为 Claw 模式可用模型，完整场景枚举见 API 文档），再调用 ModifyAgent 更新 Model 字段：

req = models.DescribeModelListRequest()
req.SpaceId = space_id
req.ModelScene = 18
req.PageNumber = 0
req.PageSize = 20
resp = client.DescribeModelList(req)
new_model_id = resp.ModelList[0].ModelBasic.ModelId

req = models.ModifyAgentRequest()
req.AppId = app_id
req.AgentId = agent_id
req.Agent = models.AgentSpec()
req.Agent.Model = models.AgentModelConfig()
req.Agent.Model.ModelId = new_model_id
req.Agent.Model.ContextWordsLimit = 20000
req.Agent.Model.InstructionsWordsLimit = 20000
req.UpdateMask = models.FiledMask()
req.UpdateMask.Paths = ["Model"]
client.ModifyAgent(req)

3.2 装卸 Skill

先通过 DescribeSkillSummaryList 拉取可选 Skill（可配合 DescribeSkillCategoryList 按分类浏览），再使用 ModifyAgent 提交更新后的完整 SkillList（全量覆盖，非增量）：


req = models.ModifyAgentRequest()
req.AppId = app_id
req.AgentId = agent_id
req.Agent = models.AgentSpec()

skill_list = []
for skill_id in skill_ids:
    skill = models.AgentSkill()
    skill.SkillId = skill_id
    skill_list.append(skill)
    
req.Agent.SkillList = skill_list
req.UpdateMask = models.FieldMask()
req.UpdateMask.Paths = ["SkilList"]
client.ModifyAgent(req)

装载 Skill：将新的 SkillId 加入列表后整体提交。

卸载 Skill：将目标 SkillId 从列表中移除后整体提交。

清空全部：提交空数组 []。

3.3 绑定 / 解绑插件工具

先通过 DescribePluginSummaryList 拉取可用插件（Module=1 表示应用已装载的插件，完整枚举见 API 文档），再使用 ModifyAgent 更新 PluginList 与 ToolList：

req = models.DescribePluginSummaryListRequest()
req.SpaceId = space_id
req.Module = 1
resp = client.DescribePluginSummaryList(req)

req = models.ModifyAgentRequest()
req AppId = app_id
req AgentId = agent_id
req.Agent = models.AgentSpec()

plugin = models.AgentPluginConfig ()
plugin.PluginId = "bf8ad2f3-1e5c-410a-ae81-abd7c5c14f1c"
plugin.AuthType = 0

req Agent.PluginList = [ plugin ]
req.UpdateMask = models FieldMask
req.UpdateMask.Paths = ["PluginList"]
client ModifyAgent (req)

四、透传自定义变量（无需修改 Agent）

若仅需向 Agent 传递运行时上下文（用户信息、部门等），无需 CopyAgentFromApp，也无需修改 Agent——只需在对话请求的 Contents 中追加一个 custom_variables 块即可（同样受开关约束）：

import json

contents = [
    {"Type": "text", "Text": "帮我生成本月周报"},
    {"Type": "custom_variables", "CustomVariables": {
        # value 若是对象/数组，必须先序列化成字符串
        "account": json.dumps({"id": "u_123", "name": "张三"}, ensure_ascii=False),
        "department": "数据科学部",
    }},
]
# 把 contents 作为 /adp/v2/chat 请求体的 Contents 字段发送（见「从零搭建一个 Claw 应用」的发起对话步骤）

CustomVariables 的 value 若为对象或数组，必须先经 json.dumps 序列化为字符串再传入，否则 Agent 无法正确接收。

五、机制小结

ModifyApp(Config.Mode.ClawAgentConfig) + CreateRelease  ← 通过 API 开启总开关（或在网页高级设置中开启）        ↓CopyAgentFromApp(AppId, Kind=1) → ParentAgentId         ← 获取用户级 Agent（修改配置时必需）        ↓CreateConversation(AgentId=ParentAgentId)               ← 绑定到会话        ↓ModifyAgent(AgentId, UpdateMask=[...])                  ← 更换模型 / 装卸 Skill / 绑定工具