diff --git a/core/main_terminal_parts/tools_execution.py b/core/main_terminal_parts/tools_execution.py
index 96d51f98..814fc6ef 100644
--- a/core/main_terminal_parts/tools_execution.py
+++ b/core/main_terminal_parts/tools_execution.py
@@ -2180,12 +2180,10 @@ class MainTerminalToolsExecutionMixin:
                                 _is_web = '/web/users/' in _data_dir.replace("\\", "/")
                                 _runtime_dir = None if _is_web else _custom_dir
                                 existing_ids = {r.role_id for r in list_roles(runtime_dir=_runtime_dir, custom_dir=_custom_dir)}
-                                if role_id in existing_ids:
-                                    result = {"success": False, "error": f"角色 {role_id} 已存在"}
-                                else:
-                                    role = RoleConfig(role_id=role_id, name=name, description=description, body_prompt=body_prompt, thinking_mode=thinking_mode_arg, model_key=model_key_arg, is_custom=True)
-                                    f = save_custom_role(role, custom_dir=_custom_dir)
-                                    result = {"success": True, "role_id": role_id, "file": str(f)}
+                                # 同 role_id 重复创建 = 覆盖式修改（仅影响之后创建的实例；运行中实例 prompt 已快照冻结）
+                                role = RoleConfig(role_id=role_id, name=name, description=description, body_prompt=body_prompt, thinking_mode=thinking_mode_arg, model_key=model_key_arg, is_custom=True)
+                                f = save_custom_role(role, custom_dir=_custom_dir)
+                                result = {"success": True, "role_id": role_id, "name": name, "file": str(f), "overwritten": role_id in existing_ids}
                         except Exception as exc:
                             result = {"success": False, "error": str(exc)}
 
diff --git a/modules/multi_agent/tools.py b/modules/multi_agent/tools.py
index 30d938e1..6b020296 100644
--- a/modules/multi_agent/tools.py
+++ b/modules/multi_agent/tools.py
@@ -147,7 +147,11 @@ def _master_tool_create_custom_agent() -> Dict[str, Any]:
         "type": "function",
         "function": {
             "name": "create_custom_agent",
-            "description": "创建/保存一个自定义角色到后端（~/.astrion/astrion/host/mutiagents/agents/）。后续可用 create_sub_agent 指定该角色。",
+            "description": (
+                "创建/保存一个自定义角色到后端（~/.astrion/astrion/host/mutiagents/agents/）。"
+                "后续可用 create_sub_agent 指定该角色。role_id 已存在时覆盖更新该角色设定；"
+                "注意：覆盖只影响之后新创建的实例，已在运行的实例 prompt 已快照冻结，不受影响。"
+            ),
             "parameters": {
                 "type": "object",
                 "properties": _inject_intent({
diff --git a/utils/tool_result_formatter/agent_context.py b/utils/tool_result_formatter/agent_context.py
index 5ad92a22..b7e5d921 100644
--- a/utils/tool_result_formatter/agent_context.py
+++ b/utils/tool_result_formatter/agent_context.py
@@ -291,6 +291,8 @@ def _format_create_custom_agent(result_data: Dict[str, Any]) -> str:
         return _format_failure("create_custom_agent", result_data)
     role_id = result_data.get("role_id")
     name = result_data.get("name") or role_id
+    if result_data.get("overwritten"):
+        return f"已覆盖更新角色 {role_id}（{name}）。新设定对之后创建的实例生效，运行中的实例不受影响。"
     return f"已创建自定义角色 {role_id}（{name}）。"