From fd3e1738e916c2cef96530252ee5ba457fc5c01f Mon Sep 17 00:00:00 2001
From: GatewayJ <835269233@qq.com>
Date: Fri, 26 Jun 2026 17:04:03 +0800
Subject: [PATCH 1/7] docs(openclaw): add MCP restart plan

---
 docs/openclaw-mcp-restart-plan.zh.md | 434 +++++++++++++++++++++++++++
 1 file changed, 434 insertions(+)
 create mode 100644 docs/openclaw-mcp-restart-plan.zh.md

diff --git a/docs/openclaw-mcp-restart-plan.zh.md b/docs/openclaw-mcp-restart-plan.zh.md
new file mode 100644
index 00000000..919e06cb
--- /dev/null
+++ b/docs/openclaw-mcp-restart-plan.zh.md
@@ -0,0 +1,434 @@
+# OpenClaw MCP 配置接入方案
+
+本文档约束 CSGClaw 为 `openclaw_sandbox` worker 增加 MCP 能力的实现方案。阶段一采用“变更后需要重建”的策略：MCP 配置保存后先进入 CSGClaw 持久化状态，只有执行 agent recreate 后才写入并生效到新的 OpenClaw gateway 进程。
+
+## 1. 目标与边界
+
+目标：
+
+- 只支持 `openclaw_sandbox` worker 的 MCP 配置。
+- MCP 配置由 CSGClaw 管理，并渲染到 OpenClaw 原生 `mcp.servers` 配置块。
+- 创建 agent 时 MCP 配置随 OpenClaw 初次启动直接生效。
+- 修改已有 agent 的 MCP 配置后，标记“需要重建”，通过现有 agent recreate 流程生效。
+- API 和前端不回显 MCP secret 明文。
+
+非目标：
+
+- 不在阶段一支持 PicoClaw MCP。
+- 不改 bootstrap manager 的运行时策略。
+- 不依赖 OpenClaw gateway 热加载 MCP。
+- 不把 MCP 写入 workspace 文件让 OpenClaw 扫描发现。
+- 不做 MCP marketplace、自动安装、连接测试或动态发现。
+
+## 2. 当前 OpenClaw 配置注入路径
+
+CSGClaw 当前已经通过配置文件注入 OpenClaw 运行参数，路径如下：
+
+```text
+Agent create/recreate provisioning
+  -> internal/agent.Service.provisionRuntime(...)
+  -> openclawsandbox.Runtime.Provision(...)
+  -> openclawsandbox.EnsureConfig(...)
+  -> renderConfig(defaults/openclaw-gateway.json + CSGClaw runtime inputs)
+  -> ~/.csgclaw/agents/<agent-name>/.openclaw/openclaw.json
+```
+
+`EnsureConfig` 会创建宿主机目录：
+
+```text
+~/.csgclaw/agents/<agent-name>/.openclaw/
+```
+
+并写入：
+
+```text
+~/.csgclaw/agents/<agent-name>/.openclaw/openclaw.json
+~/.csgclaw/agents/<agent-name>/.openclaw/exec-approvals.json
+```
+
+OpenClaw sandbox 创建时，CSGClaw 会把该目录挂载进容器：
+
+```text
+宿主机: ~/.csgclaw/agents/<agent-name>/.openclaw
+容器内: /home/node/.openclaw
+```
+
+同时设置：
+
+```text
+HOME=/home/node
+```
+
+OpenClaw gateway 启动命令为：
+
+```bash
+node /app/openclaw.mjs gateway --allow-unconfigured --bind lan --port 18789
+```
+
+因此 OpenClaw 读取的是默认路径：
+
+```text
+/home/node/.openclaw/openclaw.json
+```
+
+结论：CSGClaw 的 OpenClaw 配置注入不是把文件写进 workspace，也不是通过 task wrapper 或 `OPENCLAW_CONFIG_PATH` 指向临时文件，而是维护每个 agent 的长期 OpenClaw 配置根目录，并通过 sandbox mount 让 OpenClaw gateway 按默认路径读取。
+
+## 3. MCP 配置形态
+
+CSGClaw API 建议接收与 Multica 一致的输入形态：
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "uvx",
+      "args": ["context7-mcp"],
+      "env": {
+        "CONTEXT7_API_KEY": "secret"
+      }
+    },
+    "remote-search": {
+      "url": "https://mcp.example.com/mcp",
+      "transport": "streamable-http",
+      "headers": {
+        "Authorization": "Bearer secret"
+      }
+    }
+  }
+}
+```
+
+渲染到 OpenClaw 时转换为 OpenClaw 原生配置：
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "context7": {
+        "command": "uvx",
+        "args": ["context7-mcp"],
+        "env": {
+          "CONTEXT7_API_KEY": "secret"
+        }
+      }
+    }
+  }
+}
+```
+
+约束：
+
+- 每个 server entry 必须是 JSON object。
+- 每个 server entry 必须声明 `command` 或 `url`。
+- stdio server 使用 `command`、`args`、`env`。
+- HTTP/SSE server 使用 `url`，并直接使用 OpenClaw 识别的 `transport`，例如 `streamable-http`，不自动把 Claude 的 `type` 翻译成 OpenClaw 字段。
+- server 名称排序后写入，保证 `openclaw.json` 输出稳定。
+- MCP command 在 OpenClaw sandbox 内执行，不在宿主机执行；需要的二进制必须在镜像内存在，或通过 workspace/projects 等已有挂载路径可访问。
+
+三态语义：
+
+| 输入 | 语义 | 渲染结果 |
+| --- | --- | --- |
+| 字段缺失 | 保持现有 MCP 配置不变 | update 时不修改保存值 |
+| `null` | 清除 CSGClaw 管理的 MCP 配置 | recreate 后不写 `mcp.servers` |
+| `{}` 或 `{"mcpServers": {}}` | 显式托管空集合 | recreate 后写入 `mcp.servers: {}` |
+| 非空 `mcpServers` | 使用 CSGClaw 托管集合 | recreate 后写入对应 `mcp.servers` |
+
+阶段一不支持直接提交完整 OpenClaw `mcp` 对象。这样可以保持 API 稳定，并避免用户把 OpenClaw 其它 `mcp.*` 设置和 server 列表混在一起造成合并语义不清。
+
+## 4. 后端设计
+
+### 4.1 数据模型
+
+不要把 MCP 配置放进 `RuntimeOptions`。当前 `runtime_options` 会原样出现在 API 和前端模型中，MCP 配置可能包含 `env`、`headers`、token 等 secret。
+
+建议新增显式字段：
+
+```go
+type Agent struct {
+    MCPConfig json.RawMessage `json:"mcp_config,omitempty"`
+}
+```
+
+需要同步扩展：
+
+- `agent.Agent`
+- `agent.persistedAgent`
+- `agent.CreateAgentSpec`
+- `agent.UpdateRequest`
+- `apitypes.CreateAgentRequest`
+- API response 的 redacted MCP summary
+- participant agent binding 中的 create/update payload
+
+API response 不返回 `mcp_config` 原文，返回脱敏摘要：
+
+```json
+{
+  "mcp_configured": true,
+  "mcp_servers": [
+    {
+      "name": "context7",
+      "kind": "stdio",
+      "command": "uvx",
+      "env_keys": ["CONTEXT7_API_KEY"]
+    },
+    {
+      "name": "remote-search",
+      "kind": "http",
+      "url": "https://mcp.example.com/mcp",
+      "header_keys": ["Authorization"]
+    }
+  ]
+}
+```
+
+### 4.2 ProvisionRequest 传递
+
+在 runtime provision 边界加入 MCP 配置：
+
+```go
+type ProvisionRequest struct {
+    MCPConfig json.RawMessage
+}
+```
+
+调用链：
+
+```text
+Agent.MCPConfig
+  -> Service.provisionRuntimeForAgent(...)
+  -> agentruntime.ProvisionRequest.MCPConfig
+  -> openclawsandbox.Runtime.Provision(...)
+  -> openclawsandbox.EnsureConfig(...)
+  -> renderConfig(...)
+  -> openclaw.json
+```
+
+`openclawsandbox.EnsureConfig` 新增参数后，`renderConfig` 在现有步骤之后追加：
+
+```text
+updateOpenClawModelProvider
+updateOpenClawCsgclawChannel
+updateOpenClawFeishuChannel
+updateOpenClawGatewayAuth
+updateOpenClawMCP
+```
+
+`updateOpenClawMCP` 负责解析 CSGClaw 保存的 `mcp_config`，并写入 `cfg["mcp"]["servers"]`。
+
+### 4.3 保存与重建
+
+MCP 修改时不直接依赖 OpenClaw hot reload。
+
+保存已有 agent 的 MCP 配置时：
+
+1. 校验 JSON 和 server entry。
+2. 持久化到 agent state。
+3. 如果 runtime kind 是 `openclaw_sandbox`，设置 `agent_profile.env_restart_required = true`。
+4. 不主动写运行中的 `/home/node/.openclaw/openclaw.json`。
+5. 不主动 stop running gateway。
+
+生效方式：
+
+1. 用户点击“重建”或“保存并重建”。
+2. 后端调用现有 `POST /api/v1/agents/{id}/recreate`。
+3. `Service.Recreate` 删除旧 sandbox handle。
+4. `Provision` 使用最新 `Agent.MCPConfig` 重新写入宿主机 `openclaw.json`。
+5. 新 sandbox 挂载同一 `.openclaw` 目录并启动 OpenClaw gateway。
+6. `persistRecreatedAgent` 成功后清除 `env_restart_required`。
+
+这不是重启 CSGClaw server，而是重建该 OpenClaw agent 的 sandbox/gateway。
+
+### 4.4 与现有 profile 更新路径的关系
+
+当前 OpenClaw profile runtime input 变化时，CSGClaw 已有 `syncGatewayHostConfig` 路径会重写 OpenClaw host config。MCP 阶段一不要复用这条热更新路径。
+
+原因：
+
+- `EnsureConfig` 当前已有注释说明，运行中写 `openclaw.json` 会触发 OpenClaw hot reload，并可能遇到 gateway lock race。
+- MCP server 可能创建子进程、HTTP session、tool registry cache，热替换行为需要 OpenClaw 侧明确保证。
+- recreate 能用现有生命周期语义保证新 gateway 从干净状态加载 MCP。
+
+## 5. API 设计
+
+### 5.1 Create Agent
+
+`POST /api/v1/agents` 和 participant agent binding create payload 增加：
+
+```json
+{
+  "runtime_kind": "openclaw_sandbox",
+  "mcp_config": {
+    "mcpServers": {
+      "context7": {
+        "command": "uvx",
+        "args": ["context7-mcp"]
+      }
+    }
+  }
+}
+```
+
+创建时 MCP 配置直接参与 provision，agent 首次启动后生效，不需要额外 recreate。
+
+### 5.2 Update Agent
+
+`PATCH /api/v1/agents/{id}` 增加：
+
+```json
+{
+  "mcp_config": {
+    "mcpServers": {
+      "context7": {
+        "command": "uvx",
+        "args": ["context7-mcp"]
+      }
+    }
+  }
+}
+```
+
+语义：
+
+- 字段缺失：不修改 MCP。
+- `mcp_config: null`：清除 MCP。
+- object：替换整个 MCP 配置。
+
+成功返回的 agent response 应带：
+
+```json
+{
+  "agent_profile": {
+    "env_restart_required": true
+  },
+  "mcp_configured": true,
+  "mcp_servers": []
+}
+```
+
+前端可继续使用已有 `env_restart_required` badge 和 recreate action。
+
+### 5.3 可选 CLI
+
+后续可以给 CLI 增加：
+
+```bash
+csgclaw agent create --name alice --runtime openclaw_sandbox --mcp-config-file ./mcp.json
+csgclaw agent update alice --mcp-config-file ./mcp.json
+csgclaw agent update alice --clear-mcp-config
+```
+
+不建议提供 `--mcp-config '<json>'` 作为主入口，因为 secret 容易进入 shell history。若实现 inline 参数，也必须在帮助文本里提示风险。
+
+## 6. 前端 UI 设计
+
+### 6.1 页面位置
+
+在现有 Agent 编辑路径中增加 OpenClaw 专属 MCP 区域：
+
+- 创建 agent modal：`AgentProfileModal` 的 runtime section 下，只有选择 `openclaw_sandbox` 时展示。
+- Agent 详情页：`AgentDetailPane` 的 runtime section 下，只有当前 agent 是 `openclaw_sandbox` 时展示。
+
+不要把 MCP 做成通用 `RuntimeOptionsFields`。现有 runtime options 控件只支持简单 input/directory，无法承载 JSON 编辑、secret 脱敏、清除语义和 recreate 提示。
+
+### 6.2 区域结构
+
+建议新增一个页面私有或业务组件：
+
+```text
+OpenClawMCPConfigPanel
+```
+
+区域内容：
+
+- 标题：`MCP Servers`
+- 摘要表：server name、类型、command 或 URL、env/header keys。
+- JSON 编辑器：textarea 或轻量 code editor，保存前做 JSON parse。
+- 操作按钮：保存、保存并重建、清除配置、取消。
+- 状态提示：有未生效变更时显示“重建后生效”，并提供“重建”按钮。
+
+创建 agent 时：
+
+- 展示空 JSON 编辑器。
+- 提供示例填充按钮。
+- 保存创建后直接生效，不显示“需要重建”。
+
+编辑已有 agent 时：
+
+- 默认展示脱敏摘要。
+- JSON 编辑区为空，placeholder 表示留空不修改现有 MCP 配置。
+- 用户选择“替换配置”后输入完整 JSON。
+- 用户选择“清除配置”后提交 `mcp_config: null`。
+- 保存成功但未重建时，使用现有 `profileRestartRequired` badge，并在详情页 runtime section 展示重建 CTA。
+
+### 6.3 Secret 处理
+
+前端不应拿到原始 secret，因此不能默认把现有 MCP JSON 原样填回编辑器。
+
+编辑体验采用“摘要 + 替换”：
+
+- 摘要表只显示 server 名称和非敏感字段。
+- `env` 只显示 key，不显示 value。
+- `headers` 只显示 key，不显示 value。
+- 如果用户要修改已有 server，需要重新提交完整 `mcp_config`。
+- 如果用户只想保留现有配置，保存其它 agent 字段时不发送 `mcp_config`。
+
+### 6.4 重建交互
+
+MCP 修改保存后，前端不自动刷新或假装生效。
+
+推荐交互：
+
+1. 用户点击“保存”：
+   - 保存配置。
+   - 返回 agent response。
+   - 显示 `Recreate required` badge。
+   - 在 MCP 区域显示“已保存，重建后生效”状态。
+2. 用户点击“保存并重建”：
+   - 先调用 update。
+   - update 成功后调用 `POST /api/v1/agents/{id}/recreate`。
+   - recreate 成功后刷新 agent 列表和详情。
+3. 用户点击已有 agent action 的“重建”：
+   - 复用现有 recreate action。
+   - 成功后 `env_restart_required` 清除。
+
+如果 agent 正在运行，保存 MCP 配置不停止当前 sandbox。当前 OpenClaw gateway 继续使用旧 MCP 配置，直到 recreate 完成。
+
+## 7. 验证计划
+
+后端测试：
+
+- `openclawsandbox.renderConfig` 能把 `mcp_config.mcpServers` 渲染为 `mcp.servers`。
+- `null`、字段缺失、空对象、空 `mcpServers` 的三态语义正确。
+- 非 object server entry 报错。
+- 缺少 `command` 和 `url` 的 server entry 报错。
+- MCP 配置变更后 `openclaw_sandbox` agent 标记 `env_restart_required`。
+- `Recreate` 后重新 provision，并把最新 MCP 写入 `openclaw.json`。
+- API response 不泄漏 `env` value、header value、token。
+
+前端测试：
+
+- `AgentProfileModal` 只在 `openclaw_sandbox` 显示 MCP 区域。
+- `AgentDetailPane` 对 OpenClaw agent 显示 MCP 摘要和编辑入口。
+- 保存普通字段时不误提交 `mcp_config`。
+- 替换 MCP 时提交 object。
+- 清除 MCP 时提交 `null`。
+- 保存并重建按顺序调用 update 和 recreate。
+
+手工验证：
+
+1. 创建 OpenClaw worker，带一个 stdio MCP server。
+2. 检查宿主机 `~/.csgclaw/agents/<agent>/.openclaw/openclaw.json` 包含 `mcp.servers`。
+3. 启动 agent 后确认 OpenClaw gateway 能看到 MCP tool。
+4. 修改 MCP 配置并只保存，确认 UI 标记需要重建，旧 gateway 不被停止。
+5. 点击重建，确认新 `openclaw.json` 生效，`env_restart_required` 清除。
+
+## 8. 实施顺序
+
+1. 增加后端 MCP 数据模型、持久化和 API 脱敏摘要。
+2. 增加 MCP parser/validator 和 `openclawsandbox` 配置渲染。
+3. 扩展 provision request，把 agent MCP 配置传到 OpenClaw runtime。
+4. 增加 update 后标记 `env_restart_required` 的逻辑，但不触发 OpenClaw hot reload。
+5. 接入前端 Agent 创建/详情页 MCP UI。
+6. 增加 CLI `--mcp-config-file` 和 `--clear-mcp-config`。
+7. 补充 `docs/config.zh.md`、`docs/api.zh.md`、`docs/cli.zh.md`。

From 4fd02fe3f91be9f3523011525cb051a4dd64de41 Mon Sep 17 00:00:00 2001
From: GatewayJ <835269233@qq.com>
Date: Fri, 26 Jun 2026 17:26:01 +0800
Subject: [PATCH 2/7] docs: generalize runtime mcp plan

---
 docs/openclaw-mcp-restart-plan.zh.md | 408 +++++++++++++++------------
 1 file changed, 227 insertions(+), 181 deletions(-)

diff --git a/docs/openclaw-mcp-restart-plan.zh.md b/docs/openclaw-mcp-restart-plan.zh.md
index 919e06cb..80a562bd 100644
--- a/docs/openclaw-mcp-restart-plan.zh.md
+++ b/docs/openclaw-mcp-restart-plan.zh.md
@@ -1,28 +1,29 @@
-# OpenClaw MCP 配置接入方案
+# 通用 Runtime MCP 配置接入方案
 
-本文档约束 CSGClaw 为 `openclaw_sandbox` worker 增加 MCP 能力的实现方案。阶段一采用“变更后需要重建”的策略：MCP 配置保存后先进入 CSGClaw 持久化状态，只有执行 agent recreate 后才写入并生效到新的 OpenClaw gateway 进程。
+本文档约束 CSGClaw 为 agent 增加 MCP 能力的实现方案。文件名保留 OpenClaw 历史语境，但方案本身按通用 runtime 能力设计：MCP 配置先存入 agent 的 `runtime_options.mcp`，再由各 runtime adapter 在 provision/recreate 阶段渲染为对应运行时的原生配置。
+
+阶段一采用“变更后需要重建”的策略：MCP 配置保存后进入 CSGClaw 持久化状态，并标记 agent 需要重建；执行 agent recreate 后，新 runtime 进程加载最新 MCP 配置。暂不处理运行中配置写入触发的 hot reload race，只在关键路径打日志，方便后续分析。
 
 ## 1. 目标与边界
 
 目标：
 
-- 只支持 `openclaw_sandbox` worker 的 MCP 配置。
-- MCP 配置由 CSGClaw 管理，并渲染到 OpenClaw 原生 `mcp.servers` 配置块。
-- 创建 agent 时 MCP 配置随 OpenClaw 初次启动直接生效。
+- 所有 runtime kind 使用统一 API 形态：`runtime_options.mcp`。
+- MCP 配置由 CSGClaw 管理，随 agent create/update 持久化。
+- 创建 agent 时，MCP 配置随首次 provision 生效。
 - 修改已有 agent 的 MCP 配置后，标记“需要重建”，通过现有 agent recreate 流程生效。
-- API 和前端不回显 MCP secret 明文。
+- runtime adapter 负责把 `runtime_options.mcp` 转成原生配置；OpenClaw adapter 渲染到 `mcp.servers`。
 
 非目标：
 
-- 不在阶段一支持 PicoClaw MCP。
-- 不改 bootstrap manager 的运行时策略。
-- 不依赖 OpenClaw gateway 热加载 MCP。
-- 不把 MCP 写入 workspace 文件让 OpenClaw 扫描发现。
-- 不做 MCP marketplace、自动安装、连接测试或动态发现。
+- 阶段一不做 MCP marketplace、自动安装、连接测试或动态发现。
+- 阶段一不依赖任一 runtime 的 MCP hot reload 保证。
+- 阶段一不新增 CLI MCP 参数或 `agent update` 子命令。
+- 暂不处理 MCP secret 脱敏体验；API 和前端沿用 `runtime_options` 的现有回显语义。
 
 ## 2. 当前 OpenClaw 配置注入路径
 
-CSGClaw 当前已经通过配置文件注入 OpenClaw 运行参数，路径如下：
+OpenClaw 是第一条需要落地的 runtime adapter。CSGClaw 当前已经通过配置文件注入 OpenClaw 运行参数，路径如下：
 
 ```text
 Agent create/recreate provisioning
@@ -71,34 +72,39 @@ node /app/openclaw.mjs gateway --allow-unconfigured --bind lan --port 18789
 /home/node/.openclaw/openclaw.json
 ```
 
-结论：CSGClaw 的 OpenClaw 配置注入不是把文件写进 workspace，也不是通过 task wrapper 或 `OPENCLAW_CONFIG_PATH` 指向临时文件，而是维护每个 agent 的长期 OpenClaw 配置根目录，并通过 sandbox mount 让 OpenClaw gateway 按默认路径读取。
+结论：OpenClaw MCP adapter 不需要写 workspace 文件，也不需要通过 task wrapper 或 `OPENCLAW_CONFIG_PATH` 指向临时文件；它应该继续维护每个 agent 的长期 OpenClaw 配置根目录，并在 provision/recreate 时把 `runtime_options.mcp` 渲染进 `openclaw.json`。
 
 ## 3. MCP 配置形态
 
-CSGClaw API 建议接收与 Multica 一致的输入形态：
+CSGClaw API 接收与 Multica 一致的 MCP server 输入形态，但位置放在 `runtime_options.mcp`：
 
 ```json
 {
-  "mcpServers": {
-    "context7": {
-      "command": "uvx",
-      "args": ["context7-mcp"],
-      "env": {
-        "CONTEXT7_API_KEY": "secret"
-      }
-    },
-    "remote-search": {
-      "url": "https://mcp.example.com/mcp",
-      "transport": "streamable-http",
-      "headers": {
-        "Authorization": "Bearer secret"
+  "runtime_kind": "openclaw_sandbox",
+  "runtime_options": {
+    "mcp": {
+      "mcpServers": {
+        "context7": {
+          "command": "uvx",
+          "args": ["context7-mcp"],
+          "env": {
+            "CONTEXT7_API_KEY": "secret"
+          }
+        },
+        "remote-search": {
+          "url": "https://mcp.example.com/mcp",
+          "transport": "streamable-http",
+          "headers": {
+            "Authorization": "Bearer secret"
+          }
+        }
       }
     }
   }
 }
 ```
 
-渲染到 OpenClaw 时转换为 OpenClaw 原生配置：
+OpenClaw adapter 渲染到 OpenClaw 原生配置：
 
 ```json
 {
@@ -116,95 +122,91 @@ CSGClaw API 建议接收与 Multica 一致的输入形态：
 }
 ```
 
-约束：
+通用约束：
 
+- 持久化后的 `runtime_options.mcp` 缺失表示该 agent 没有 CSGClaw 管理的 MCP 配置。
+- API update 的字段缺失语义以第 5.2 节为准：`runtime_options` 整体缺失才表示不修改；`runtime_options` 一旦提交就是整体替换。
+- `runtime_options.mcp: null` 表示清除 CSGClaw 管理的 MCP 配置。
+- `runtime_options.mcp: {}` 或 `{"mcpServers": {}}` 表示显式托管空集合。
+- 非空 `mcpServers` 表示使用 CSGClaw 托管集合。
 - 每个 server entry 必须是 JSON object。
 - 每个 server entry 必须声明 `command` 或 `url`。
 - stdio server 使用 `command`、`args`、`env`。
-- HTTP/SSE server 使用 `url`，并直接使用 OpenClaw 识别的 `transport`，例如 `streamable-http`，不自动把 Claude 的 `type` 翻译成 OpenClaw 字段。
-- server 名称排序后写入，保证 `openclaw.json` 输出稳定。
-- MCP command 在 OpenClaw sandbox 内执行，不在宿主机执行；需要的二进制必须在镜像内存在，或通过 workspace/projects 等已有挂载路径可访问。
+- HTTP/SSE server 使用 `url`，并直接使用目标 runtime 识别的 `transport`。
+- server 名称排序后写入，保证生成配置稳定。
 
-三态语义：
+OpenClaw 约束：
 
-| 输入 | 语义 | 渲染结果 |
-| --- | --- | --- |
-| 字段缺失 | 保持现有 MCP 配置不变 | update 时不修改保存值 |
-| `null` | 清除 CSGClaw 管理的 MCP 配置 | recreate 后不写 `mcp.servers` |
-| `{}` 或 `{"mcpServers": {}}` | 显式托管空集合 | recreate 后写入 `mcp.servers: {}` |
-| 非空 `mcpServers` | 使用 CSGClaw 托管集合 | recreate 后写入对应 `mcp.servers` |
-
-阶段一不支持直接提交完整 OpenClaw `mcp` 对象。这样可以保持 API 稳定，并避免用户把 OpenClaw 其它 `mcp.*` 设置和 server 列表混在一起造成合并语义不清。
+- `runtime_options.mcp.mcpServers` 渲染为 OpenClaw `mcp.servers`。
+- 不支持直接提交完整 OpenClaw `mcp` 对象，避免用户把 OpenClaw 其它 `mcp.*` 设置和 server 列表混在一起造成合并语义不清。
+- MCP command 在 OpenClaw sandbox 内执行，不在宿主机执行；需要的二进制必须在镜像内存在，或通过 workspace/projects 等已有挂载路径可访问。
 
 ## 4. 后端设计
 
 ### 4.1 数据模型
 
-不要把 MCP 配置放进 `RuntimeOptions`。当前 `runtime_options` 会原样出现在 API 和前端模型中，MCP 配置可能包含 `env`、`headers`、token 等 secret。
+不要新增 top-level `Agent.MCPConfig`。阶段一把 MCP 配置放在 `Agent.RuntimeOptions["mcp"]`，保持和已有 runtime option 架构一致。
 
-建议新增显式字段：
+需要同步处理：
 
-```go
-type Agent struct {
-    MCPConfig json.RawMessage `json:"mcp_config,omitempty"`
-}
-```
+- `agent.CreateAgentSpec.RuntimeOptions`
+- `agent.UpdateRequest.RuntimeOptions`
+- `apitypes.CreateAgentRequest.RuntimeOptions`
+- participant agent binding 中的 create payload
+- Web `AgentLike.runtime_options`
+- runtime option 保存/合并逻辑
 
-需要同步扩展：
+注意：当前 `PATCH /api/v1/agents/{id}` 的 `runtime_options` 是整体替换语义。前端保存 MCP 时必须基于当前 agent 的 `runtime_options` 合并后提交，避免只提交 `{"mcp": ...}` 时覆盖其它 runtime option，例如 Codex 的 `local_workspace_dir`。
 
-- `agent.Agent`
-- `agent.persistedAgent`
-- `agent.CreateAgentSpec`
-- `agent.UpdateRequest`
-- `apitypes.CreateAgentRequest`
-- API response 的 redacted MCP summary
-- participant agent binding 中的 create/update payload
+建议增加共享 helper：
 
-API response 不返回 `mcp_config` 原文，返回脱敏摘要：
+```go
+const RuntimeOptionMCPKey = "mcp"
 
-```json
-{
-  "mcp_configured": true,
-  "mcp_servers": [
-    {
-      "name": "context7",
-      "kind": "stdio",
-      "command": "uvx",
-      "env_keys": ["CONTEXT7_API_KEY"]
-    },
-    {
-      "name": "remote-search",
-      "kind": "http",
-      "url": "https://mcp.example.com/mcp",
-      "header_keys": ["Authorization"]
-    }
-  ]
-}
+func ExtractMCPConfig(runtimeOptions map[string]any) (MCPConfigState, error)
+func RuntimeOptionsWithMCP(runtimeOptions map[string]any, mcp any) map[string]any
 ```
 
+`MCPConfigState` 至少区分：
+
+- absent
+- cleared/null
+- empty managed set
+- managed server set
+
 ### 4.2 ProvisionRequest 传递
 
-在 runtime provision 边界加入 MCP 配置：
+因为 MCP 已放入 `runtime_options`，provision 边界应传递通用 runtime options，而不是新增 MCP 专用字段：
 
 ```go
 type ProvisionRequest struct {
-    MCPConfig json.RawMessage
+    RuntimeOptions map[string]any
 }
 ```
 
 调用链：
 
 ```text
-Agent.MCPConfig
+Agent.RuntimeOptions["mcp"]
   -> Service.provisionRuntimeForAgent(...)
-  -> agentruntime.ProvisionRequest.MCPConfig
+  -> agentruntime.ProvisionRequest.RuntimeOptions
+  -> concrete runtime Provision(...)
+  -> runtime MCP adapter
+  -> native runtime config
+```
+
+OpenClaw adapter 的调用链：
+
+```text
+runtime_options.mcp
   -> openclawsandbox.Runtime.Provision(...)
   -> openclawsandbox.EnsureConfig(...)
   -> renderConfig(...)
-  -> openclaw.json
+  -> updateOpenClawMCP(...)
+  -> ~/.csgclaw/agents/<agent-name>/.openclaw/openclaw.json
 ```
 
-`openclawsandbox.EnsureConfig` 新增参数后，`renderConfig` 在现有步骤之后追加：
+`openclawsandbox.EnsureConfig` 新增 runtime options 参数后，`renderConfig` 在现有步骤之后追加：
 
 ```text
 updateOpenClawModelProvider
@@ -214,55 +216,97 @@ updateOpenClawGatewayAuth
 updateOpenClawMCP
 ```
 
-`updateOpenClawMCP` 负责解析 CSGClaw 保存的 `mcp_config`，并写入 `cfg["mcp"]["servers"]`。
+### 4.3 Runtime adapter 策略
+
+每个 runtime kind 都通过同一个 `runtime_options.mcp` 输入获得 MCP 配置，但落地方式由 runtime adapter 决定。
 
-### 4.3 保存与重建
+建议定义 runtime MCP policy：
+
+```go
+type RuntimeMCPPolicy interface {
+    ValidateMCPConfig(runtimeOptions map[string]any) error
+    MCPRestartRequired(previous, current map[string]any) bool
+}
+```
 
-MCP 修改时不直接依赖 OpenClaw hot reload。
+对 provisioner runtime，adapter 在 `Provision` 期间渲染原生配置。对非 provisioner runtime，如果 MCP 需要写入启动前配置，也应把写入逻辑放在 runtime 自己的 host-side preparation 路径中，不要散落到 API handler 或 agent service。
+
+阶段一默认策略：
+
+- `runtime_options.mcp` 变更后需要重建。
+- 不依赖 runtime hot reload。
+- 如果某个 runtime adapter 已确认支持安全热应用，可以后续单独改 policy。
+
+OpenClaw adapter：
+
+- 渲染到 `openclaw.json` 的 `mcp.servers`。
+- `null` 清除 CSGClaw 管理的 `mcp.servers`。
+- `{}` 或空 `mcpServers` 写入 `mcp.servers: {}`。
+
+PicoClaw/Codex/其它 runtime：
+
+- 复用相同 `runtime_options.mcp` 输入和校验。
+- 由对应 runtime adapter 渲染为其原生 MCP 配置或启动参数。
+- 不允许静默忽略已保存 MCP 配置；如果 adapter 暂无可生效路径，应在 validate/provision 阶段返回明确错误，避免用户误以为配置已经生效。
+
+### 4.4 保存与重建
 
 保存已有 agent 的 MCP 配置时：
 
-1. 校验 JSON 和 server entry。
-2. 持久化到 agent state。
-3. 如果 runtime kind 是 `openclaw_sandbox`，设置 `agent_profile.env_restart_required = true`。
-4. 不主动写运行中的 `/home/node/.openclaw/openclaw.json`。
-5. 不主动 stop running gateway。
+1. 合并并校验新的 `runtime_options`。
+2. 校验 `runtime_options.mcp` 的 JSON 和 server entry。
+3. 持久化到 agent state。
+4. 如果 `runtime_options.mcp` 发生变化，设置 `agent_profile.env_restart_required = true`。
+5. 不主动 stop running runtime。
+6. 不依赖 runtime hot reload。
 
 生效方式：
 
 1. 用户点击“重建”或“保存并重建”。
 2. 后端调用现有 `POST /api/v1/agents/{id}/recreate`。
-3. `Service.Recreate` 删除旧 sandbox handle。
-4. `Provision` 使用最新 `Agent.MCPConfig` 重新写入宿主机 `openclaw.json`。
-5. 新 sandbox 挂载同一 `.openclaw` 目录并启动 OpenClaw gateway。
+3. `Service.Recreate` 删除旧 runtime handle。
+4. `Provision` 使用最新 `Agent.RuntimeOptions` 重新生成 runtime 原生配置。
+5. 新 runtime 进程启动并加载 MCP。
 6. `persistRecreatedAgent` 成功后清除 `env_restart_required`。
 
-这不是重启 CSGClaw server，而是重建该 OpenClaw agent 的 sandbox/gateway。
+这不是重启 CSGClaw server，而是重建该 agent 的 runtime 进程。
+
+### 4.5 与现有 profile 热同步路径的关系
 
-### 4.4 与现有 profile 更新路径的关系
+当前 gateway runtime 的 profile runtime input 变化时，CSGClaw 已有 `syncGatewayHostConfig` 路径会重写 host config。阶段一暂不处理这条路径和 MCP 变更之间的 hot reload race。
 
-当前 OpenClaw profile runtime input 变化时，CSGClaw 已有 `syncGatewayHostConfig` 路径会重写 OpenClaw host config。MCP 阶段一不要复用这条热更新路径。
+实现要求：
 
-原因：
+- 保持现有 `syncGatewayHostConfig` 行为。
+- 不因为 MCP pending 状态阻塞 profile 配置热同步。
+- 在 `syncGatewayHostConfig` 即将写 host config 时，如果当前 agent 配置了 `runtime_options.mcp` 或 `env_restart_required = true`，打印结构化日志。
+- 日志至少包含 `agent_id`、`agent_name`、`runtime_kind`、`mcp_configured`、`env_restart_required`、`stage`。
+- 日志不要求解决 race，只要求后续能定位“保存 MCP 后是否又发生了 host config 写入”。
 
-- `EnsureConfig` 当前已有注释说明，运行中写 `openclaw.json` 会触发 OpenClaw hot reload，并可能遇到 gateway lock race。
-- MCP server 可能创建子进程、HTTP session、tool registry cache，热替换行为需要 OpenClaw 侧明确保证。
-- recreate 能用现有生命周期语义保证新 gateway 从干净状态加载 MCP。
+建议日志点：
+
+- MCP 配置保存成功。
+- MCP 配置清除成功。
+- runtime provision 开始渲染 MCP。
+- runtime provision 写入原生配置成功。
+- `syncGatewayHostConfig` 在 MCP configured 或 restart required 状态下执行。
 
 ## 5. API 设计
 
 ### 5.1 Create Agent
 
-`POST /api/v1/agents` 和 participant agent binding create payload 增加：
+`POST /api/v1/agents` 和 participant agent binding create payload 使用现有 `runtime_options`：
 
 ```json
 {
   "runtime_kind": "openclaw_sandbox",
-  "mcp_config": {
-    "mcpServers": {
-      "context7": {
-        "command": "uvx",
-        "args": ["context7-mcp"]
+  "runtime_options": {
+    "mcp": {
+      "mcpServers": {
+        "context7": {
+          "command": "uvx",
+          "args": ["context7-mcp"]
+        }
       }
     }
   }
@@ -273,15 +317,17 @@ MCP 修改时不直接依赖 OpenClaw hot reload。
 
 ### 5.2 Update Agent
 
-`PATCH /api/v1/agents/{id}` 增加：
+`PATCH /api/v1/agents/{id}` 继续使用 `runtime_options`：
 
 ```json
 {
-  "mcp_config": {
-    "mcpServers": {
-      "context7": {
-        "command": "uvx",
-        "args": ["context7-mcp"]
+  "runtime_options": {
+    "mcp": {
+      "mcpServers": {
+        "context7": {
+          "command": "uvx",
+          "args": ["context7-mcp"]
+        }
       }
     }
   }
@@ -290,59 +336,68 @@ MCP 修改时不直接依赖 OpenClaw hot reload。
 
 语义：
 
-- 字段缺失：不修改 MCP。
-- `mcp_config: null`：清除 MCP。
-- object：替换整个 MCP 配置。
+- `runtime_options` 字段缺失：不修改 runtime options，也不修改 MCP。
+- `runtime_options` 字段存在：整体替换当前 runtime options。
+- `runtime_options.mcp` 缺失：提交后的 runtime options 不再包含 MCP。
+- `runtime_options.mcp: null`：清除 MCP。
+- `runtime_options.mcp` 为 object：替换整个 MCP 配置。
 
-成功返回的 agent response 应带：
+因此前端保存 MCP 时应总是提交合并后的完整 `runtime_options`：
 
 ```json
 {
-  "agent_profile": {
-    "env_restart_required": true
-  },
-  "mcp_configured": true,
-  "mcp_servers": []
+  "runtime_options": {
+    "local_workspace_dir": "/path/kept-from-existing-options",
+    "mcp": {
+      "mcpServers": {
+        "context7": {
+          "command": "uvx",
+          "args": ["context7-mcp"]
+        }
+      }
+    }
+  }
 }
 ```
 
-前端可继续使用已有 `env_restart_required` badge 和 recreate action。
-
-### 5.3 可选 CLI
+成功返回沿用现有 agent response，`runtime_options` 中包含当前 MCP 配置：
 
-后续可以给 CLI 增加：
-
-```bash
-csgclaw agent create --name alice --runtime openclaw_sandbox --mcp-config-file ./mcp.json
-csgclaw agent update alice --mcp-config-file ./mcp.json
-csgclaw agent update alice --clear-mcp-config
+```json
+{
+  "agent_profile": {
+    "env_restart_required": true
+  },
+  "runtime_options": {
+    "mcp": {
+      "mcpServers": {}
+    }
+  }
+}
 ```
 
-不建议提供 `--mcp-config '<json>'` 作为主入口，因为 secret 容易进入 shell history。若实现 inline 参数，也必须在帮助文本里提示风险。
+前端继续使用已有 `env_restart_required` badge 和 recreate action。
 
 ## 6. 前端 UI 设计
 
 ### 6.1 页面位置
 
-在现有 Agent 编辑路径中增加 OpenClaw 专属 MCP 区域：
+在现有 Agent 创建和编辑路径中增加通用 MCP 区域：
 
-- 创建 agent modal：`AgentProfileModal` 的 runtime section 下，只有选择 `openclaw_sandbox` 时展示。
-- Agent 详情页：`AgentDetailPane` 的 runtime section 下，只有当前 agent 是 `openclaw_sandbox` 时展示。
+- 创建 agent modal：`AgentProfileModal` 的 runtime section 下展示。
+- Agent 详情页：`AgentDetailPane` 的 runtime section 下展示。
+- 控件读写 `draft.runtime_options.mcp`，不引入 top-level `mcp_config` 状态。
 
-不要把 MCP 做成通用 `RuntimeOptionsFields`。现有 runtime options 控件只支持简单 input/directory，无法承载 JSON 编辑、secret 脱敏、清除语义和 recreate 提示。
-
-### 6.2 区域结构
-
-建议新增一个页面私有或业务组件：
+MCP 区域可以做成专用组件，但它必须作为 runtime options 的编辑器存在：
 
 ```text
-OpenClawMCPConfigPanel
+MCPRuntimeOptionsPanel
 ```
 
+### 6.2 区域结构
+
 区域内容：
 
 - 标题：`MCP Servers`
-- 摘要表：server name、类型、command 或 URL、env/header keys。
 - JSON 编辑器：textarea 或轻量 code editor，保存前做 JSON parse。
 - 操作按钮：保存、保存并重建、清除配置、取消。
 - 状态提示：有未生效变更时显示“重建后生效”，并提供“重建”按钮。
@@ -355,32 +410,19 @@ OpenClawMCPConfigPanel
 
 编辑已有 agent 时：
 
-- 默认展示脱敏摘要。
-- JSON 编辑区为空，placeholder 表示留空不修改现有 MCP 配置。
-- 用户选择“替换配置”后输入完整 JSON。
-- 用户选择“清除配置”后提交 `mcp_config: null`。
+- 默认把现有 `runtime_options.mcp` 填回编辑器。
+- 用户保存时，前端将编辑后的 MCP 合并回完整 `runtime_options` 后提交。
+- 用户选择“清除配置”后，提交合并后的 `runtime_options`，其中 `mcp` 为 `null` 或删除 `mcp` key。
 - 保存成功但未重建时，使用现有 `profileRestartRequired` badge，并在详情页 runtime section 展示重建 CTA。
 
-### 6.3 Secret 处理
-
-前端不应拿到原始 secret，因此不能默认把现有 MCP JSON 原样填回编辑器。
-
-编辑体验采用“摘要 + 替换”：
-
-- 摘要表只显示 server 名称和非敏感字段。
-- `env` 只显示 key，不显示 value。
-- `headers` 只显示 key，不显示 value。
-- 如果用户要修改已有 server，需要重新提交完整 `mcp_config`。
-- 如果用户只想保留现有配置，保存其它 agent 字段时不发送 `mcp_config`。
-
-### 6.4 重建交互
+### 6.3 重建交互
 
 MCP 修改保存后，前端不自动刷新或假装生效。
 
 推荐交互：
 
 1. 用户点击“保存”：
-   - 保存配置。
+   - 保存合并后的 `runtime_options`。
    - 返回 agent response。
    - 显示 `Recreate required` badge。
    - 在 MCP 区域显示“已保存，重建后生效”状态。
@@ -392,43 +434,47 @@ MCP 修改保存后，前端不自动刷新或假装生效。
    - 复用现有 recreate action。
    - 成功后 `env_restart_required` 清除。
 
-如果 agent 正在运行，保存 MCP 配置不停止当前 sandbox。当前 OpenClaw gateway 继续使用旧 MCP 配置，直到 recreate 完成。
+如果 agent 正在运行，保存 MCP 配置不停止当前 runtime。当前 runtime 继续使用旧 MCP 配置，直到 recreate 完成。
 
 ## 7. 验证计划
 
 后端测试：
 
-- `openclawsandbox.renderConfig` 能把 `mcp_config.mcpServers` 渲染为 `mcp.servers`。
-- `null`、字段缺失、空对象、空 `mcpServers` 的三态语义正确。
+- `runtime_options.mcp` 的缺失、`null`、空对象、空 `mcpServers`、非空 `mcpServers` 语义正确。
 - 非 object server entry 报错。
 - 缺少 `command` 和 `url` 的 server entry 报错。
-- MCP 配置变更后 `openclaw_sandbox` agent 标记 `env_restart_required`。
-- `Recreate` 后重新 provision，并把最新 MCP 写入 `openclaw.json`。
-- API response 不泄漏 `env` value、header value、token。
+- 保存 MCP 时保留其它 runtime options。
+- MCP 配置变更后 agent 标记 `env_restart_required`。
+- `Recreate` 后重新 provision，并把最新 MCP 传给 runtime adapter。
+- `openclawsandbox.renderConfig` 能把 `runtime_options.mcp.mcpServers` 渲染为 `mcp.servers`。
+- OpenClaw `null` 清除和空集合渲染行为正确。
+- `syncGatewayHostConfig` 在 MCP configured 或 restart required 状态下会打出可诊断日志。
 
 前端测试：
 
-- `AgentProfileModal` 只在 `openclaw_sandbox` 显示 MCP 区域。
-- `AgentDetailPane` 对 OpenClaw agent 显示 MCP 摘要和编辑入口。
-- 保存普通字段时不误提交 `mcp_config`。
-- 替换 MCP 时提交 object。
-- 清除 MCP 时提交 `null`。
+- `AgentProfileModal` 能编辑 `runtime_options.mcp`。
+- `AgentDetailPane` 能显示和编辑 `runtime_options.mcp`。
+- 保存 MCP 时不覆盖其它 runtime options。
+- 替换 MCP 时提交合并后的 `runtime_options`。
+- 清除 MCP 时提交合并后的 `runtime_options`。
 - 保存并重建按顺序调用 update 和 recreate。
 
 手工验证：
 
-1. 创建 OpenClaw worker，带一个 stdio MCP server。
-2. 检查宿主机 `~/.csgclaw/agents/<agent>/.openclaw/openclaw.json` 包含 `mcp.servers`。
-3. 启动 agent 后确认 OpenClaw gateway 能看到 MCP tool。
-4. 修改 MCP 配置并只保存，确认 UI 标记需要重建，旧 gateway 不被停止。
-5. 点击重建，确认新 `openclaw.json` 生效，`env_restart_required` 清除。
+1. 创建 agent，带一个 stdio MCP server。
+2. 对 OpenClaw agent，检查宿主机 `~/.csgclaw/agents/<agent>/.openclaw/openclaw.json` 包含 `mcp.servers`。
+3. 启动 agent 后确认 runtime 能看到 MCP tool。
+4. 修改 MCP 配置并只保存，确认 UI 标记需要重建，旧 runtime 不被停止。
+5. 点击重建，确认新配置生效，`env_restart_required` 清除。
+6. 在 MCP pending 状态下修改 profile，确认日志能看到 host config sync 记录。
 
 ## 8. 实施顺序
 
-1. 增加后端 MCP 数据模型、持久化和 API 脱敏摘要。
-2. 增加 MCP parser/validator 和 `openclawsandbox` 配置渲染。
-3. 扩展 provision request，把 agent MCP 配置传到 OpenClaw runtime。
-4. 增加 update 后标记 `env_restart_required` 的逻辑，但不触发 OpenClaw hot reload。
-5. 接入前端 Agent 创建/详情页 MCP UI。
-6. 增加 CLI `--mcp-config-file` 和 `--clear-mcp-config`。
-7. 补充 `docs/config.zh.md`、`docs/api.zh.md`、`docs/cli.zh.md`。
+1. 增加 `runtime_options.mcp` parser/validator 和共享 helper。
+2. 扩展 provision request，把 `Agent.RuntimeOptions` 传到 runtime provision 边界。
+3. 增加通用 MCP restart policy：`runtime_options.mcp` 变化后标记 `env_restart_required`。
+4. 增加关键路径结构化日志，尤其是 MCP save/provision 和 gateway host config sync。
+5. 实现 OpenClaw adapter，把 `runtime_options.mcp.mcpServers` 渲染到 `openclaw.json` 的 `mcp.servers`。
+6. 接入其它 runtime adapter 的 MCP 原生渲染路径；没有可生效路径时返回明确错误，不静默忽略。
+7. 接入前端 Agent 创建/详情页 MCP runtime options UI。
+8. 补充 `docs/api.zh.md` 和相关英文 API 文档。

From 908a1d2baf86dfc88c4032e96baa8f75a02e344a Mon Sep 17 00:00:00 2001
From: GatewayJ <835269233@qq.com>
Date: Fri, 26 Jun 2026 17:58:49 +0800
Subject: [PATCH 3/7] docs: update mcp plan for automatic recreate

---
 docs/openclaw-mcp-restart-plan.zh.md | 104 +++++++++++++++------------
 1 file changed, 60 insertions(+), 44 deletions(-)

diff --git a/docs/openclaw-mcp-restart-plan.zh.md b/docs/openclaw-mcp-restart-plan.zh.md
index 80a562bd..6537519a 100644
--- a/docs/openclaw-mcp-restart-plan.zh.md
+++ b/docs/openclaw-mcp-restart-plan.zh.md
@@ -2,7 +2,7 @@
 
 本文档约束 CSGClaw 为 agent 增加 MCP 能力的实现方案。文件名保留 OpenClaw 历史语境，但方案本身按通用 runtime 能力设计：MCP 配置先存入 agent 的 `runtime_options.mcp`，再由各 runtime adapter 在 provision/recreate 阶段渲染为对应运行时的原生配置。
 
-阶段一采用“变更后需要重建”的策略：MCP 配置保存后进入 CSGClaw 持久化状态，并标记 agent 需要重建；执行 agent recreate 后，新 runtime 进程加载最新 MCP 配置。暂不处理运行中配置写入触发的 hot reload race，只在关键路径打日志，方便后续分析。
+阶段一沿用现有 gateway runtime 配置变更路径：MCP 配置保存后进入 CSGClaw 持久化状态，并立即触发现有 agent recreate 流程；recreate 成功后，新 runtime 进程加载最新 MCP 配置，`env_restart_required` 被清除。recreate 失败时，已保存的 MCP 配置保留在 agent state 中，`env_restart_required` 继续为 true，用户可通过现有“重建”动作重试。阶段一不依赖 runtime hot reload。
 
 ## 1. 目标与边界
 
@@ -11,7 +11,7 @@
 - 所有 runtime kind 使用统一 API 形态：`runtime_options.mcp`。
 - MCP 配置由 CSGClaw 管理，随 agent create/update 持久化。
 - 创建 agent 时，MCP 配置随首次 provision 生效。
-- 修改已有 agent 的 MCP 配置后，标记“需要重建”，通过现有 agent recreate 流程生效。
+- 修改已有 agent 的 MCP 配置后，后端通过现有 agent recreate 流程自动生效。
 - runtime adapter 负责把 `runtime_options.mcp` 转成原生配置；OpenClaw adapter 渲染到 `mcp.servers`。
 
 非目标：
@@ -233,7 +233,10 @@ type RuntimeMCPPolicy interface {
 
 阶段一默认策略：
 
-- `runtime_options.mcp` 变更后需要重建。
+- `runtime_options.mcp` 变更后需要通过 recreate 生效。
+- 后端保存已有 agent 的 MCP 配置后，立即调用现有 recreate 流程。
+- recreate 成功后清除 `env_restart_required`。
+- recreate 失败时保留 `env_restart_required = true`，让用户可通过现有重建动作重试。
 - 不依赖 runtime hot reload。
 - 如果某个 runtime adapter 已确认支持安全热应用，可以后续单独改 policy。
 
@@ -249,39 +252,43 @@ PicoClaw/Codex/其它 runtime：
 - 由对应 runtime adapter 渲染为其原生 MCP 配置或启动参数。
 - 不允许静默忽略已保存 MCP 配置；如果 adapter 暂无可生效路径，应在 validate/provision 阶段返回明确错误，避免用户误以为配置已经生效。
 
-### 4.4 保存与重建
+### 4.4 保存与自动重建
 
 保存已有 agent 的 MCP 配置时：
 
 1. 合并并校验新的 `runtime_options`。
 2. 校验 `runtime_options.mcp` 的 JSON 和 server entry。
 3. 持久化到 agent state。
-4. 如果 `runtime_options.mcp` 发生变化，设置 `agent_profile.env_restart_required = true`。
-5. 不主动 stop running runtime。
-6. 不依赖 runtime hot reload。
+4. 如果 `runtime_options.mcp` 发生变化，设置 `agent_profile.env_restart_required = true`，作为持久化重建标记。
+5. 对支持 MCP 渲染的 gateway runtime，立即调用现有 `Service.Recreate`。
+6. `Recreate` 成功后，新 runtime 进程加载最新 MCP 配置，`persistRecreatedAgent` 清除 `env_restart_required`。
+7. `Recreate` 失败时，返回错误；已保存 MCP 配置保留，`env_restart_required` 保留为 true，用户可通过现有 recreate action 重试。
+8. 不依赖 runtime hot reload。
 
 生效方式：
 
-1. 用户点击“重建”或“保存并重建”。
-2. 后端调用现有 `POST /api/v1/agents/{id}/recreate`。
-3. `Service.Recreate` 删除旧 runtime handle。
-4. `Provision` 使用最新 `Agent.RuntimeOptions` 重新生成 runtime 原生配置。
-5. 新 runtime 进程启动并加载 MCP。
-6. `persistRecreatedAgent` 成功后清除 `env_restart_required`。
+1. 用户保存 MCP 配置。
+2. 后端持久化最新 `Agent.RuntimeOptions`。
+3. 后端调用现有 `Service.Recreate`。
+4. `Service.Recreate` 删除旧 runtime handle。
+5. `Provision` 使用最新 `Agent.RuntimeOptions` 重新生成 runtime 原生配置。
+6. 新 runtime 进程启动并加载 MCP。
+7. `persistRecreatedAgent` 成功后清除 `env_restart_required`。
 
 这不是重启 CSGClaw server，而是重建该 agent 的 runtime 进程。
 
 ### 4.5 与现有 profile 热同步路径的关系
 
-当前 gateway runtime 的 profile runtime input 变化时，CSGClaw 已有 `syncGatewayHostConfig` 路径会重写 host config。阶段一暂不处理这条路径和 MCP 变更之间的 hot reload race。
+当前 gateway runtime 的 profile runtime input 变化时，CSGClaw 已有 `syncGatewayHostConfig` 路径会重写 host config。因为 OpenClaw 配置是从 embedded defaults 重新渲染，而不是读旧文件做增量修改，所以该路径也必须接收当前 agent 的 `runtime_options`，并在重写 host config 时保留/渲染 `runtime_options.mcp`。否则 profile 热同步会把已经生效的 `mcp.servers` 覆盖掉。
 
 实现要求：
 
-- 保持现有 `syncGatewayHostConfig` 行为。
-- 不因为 MCP pending 状态阻塞 profile 配置热同步。
-- 在 `syncGatewayHostConfig` 即将写 host config 时，如果当前 agent 配置了 `runtime_options.mcp` 或 `env_restart_required = true`，打印结构化日志。
+- 保持现有 `syncGatewayHostConfig` 的 profile 热同步能力。
+- `syncGatewayHostConfig` 调用 OpenClaw/PicoClaw `EnsureConfig` 时必须传入当前 `Agent.RuntimeOptions`。
+- `EnsureConfig`/`renderConfig` 每次写 host config 都应根据当前 `runtime_options.mcp` 渲染 runtime 原生 MCP 配置。
+- 如果当前 agent 配置了 `runtime_options.mcp` 或 `env_restart_required = true`，打印结构化日志。
 - 日志至少包含 `agent_id`、`agent_name`、`runtime_kind`、`mcp_configured`、`env_restart_required`、`stage`。
-- 日志不要求解决 race，只要求后续能定位“保存 MCP 后是否又发生了 host config 写入”。
+- 日志用于定位“保存 MCP 后是否又发生了 host config 写入”，但正确性必须由重新渲染 MCP 保证。
 
 建议日志点：
 
@@ -290,6 +297,8 @@ PicoClaw/Codex/其它 runtime：
 - runtime provision 开始渲染 MCP。
 - runtime provision 写入原生配置成功。
 - `syncGatewayHostConfig` 在 MCP configured 或 restart required 状态下执行。
+- recreate 成功。
+- recreate 失败且保留 `env_restart_required`。
 
 ## 5. API 设计
 
@@ -360,12 +369,12 @@ PicoClaw/Codex/其它 runtime：
 }
 ```
 
-成功返回沿用现有 agent response，`runtime_options` 中包含当前 MCP 配置：
+成功返回沿用现有 agent response，`runtime_options` 中包含当前 MCP 配置。已有 agent 的 MCP 变更会在返回前尝试自动 recreate；如果 recreate 成功，`env_restart_required` 为 false 或省略：
 
 ```json
 {
   "agent_profile": {
-    "env_restart_required": true
+    "env_restart_required": false
   },
   "runtime_options": {
     "mcp": {
@@ -375,7 +384,7 @@ PicoClaw/Codex/其它 runtime：
 }
 ```
 
-前端继续使用已有 `env_restart_required` badge 和 recreate action。
+如果 update 已持久化但 recreate 失败，后端返回错误；前端应刷新 agent 状态并继续使用已有 `env_restart_required` badge 和 recreate action 作为重试入口。
 
 ## 6. 前端 UI 设计
 
@@ -399,8 +408,8 @@ MCPRuntimeOptionsPanel
 
 - 标题：`MCP Servers`
 - JSON 编辑器：textarea 或轻量 code editor，保存前做 JSON parse。
-- 操作按钮：保存、保存并重建、清除配置、取消。
-- 状态提示：有未生效变更时显示“重建后生效”，并提供“重建”按钮。
+- 操作按钮：保存、清除配置、取消。
+- 状态提示：保存时提示会自动重建 runtime；如果后端返回 recreate 失败，刷新 agent 并显示现有 `env_restart_required` badge 和“重建”按钮。
 
 创建 agent 时：
 
@@ -413,28 +422,30 @@ MCPRuntimeOptionsPanel
 - 默认把现有 `runtime_options.mcp` 填回编辑器。
 - 用户保存时，前端将编辑后的 MCP 合并回完整 `runtime_options` 后提交。
 - 用户选择“清除配置”后，提交合并后的 `runtime_options`，其中 `mcp` 为 `null` 或删除 `mcp` key。
-- 保存成功但未重建时，使用现有 `profileRestartRequired` badge，并在详情页 runtime section 展示重建 CTA。
+- 保存成功表示后端已完成自动 recreate 并刷新为新 runtime。
+- 保存失败时刷新 agent；如果 `env_restart_required` 为 true，使用现有 `profileRestartRequired` badge，并在详情页 runtime section 展示重建 CTA。
 
-### 6.3 重建交互
+### 6.3 自动重建交互
 
-MCP 修改保存后，前端不自动刷新或假装生效。
+MCP 修改保存后，后端负责自动重建 runtime；前端不再提供专门的“保存并重建”主流程。
 
 推荐交互：
 
 1. 用户点击“保存”：
    - 保存合并后的 `runtime_options`。
-   - 返回 agent response。
-   - 显示 `Recreate required` badge。
-   - 在 MCP 区域显示“已保存，重建后生效”状态。
-2. 用户点击“保存并重建”：
-   - 先调用 update。
-   - update 成功后调用 `POST /api/v1/agents/{id}/recreate`。
-   - recreate 成功后刷新 agent 列表和详情。
+   - 后端自动调用 recreate。
+   - update 成功返回 agent response。
+   - 刷新 agent 列表和详情。
+   - 不显示 `Recreate required` badge。
+2. update 返回错误：
+   - 展示错误。
+   - 刷新 agent 列表和详情。
+   - 如果刷新后的 agent 仍有 `env_restart_required`，显示现有重建 CTA。
 3. 用户点击已有 agent action 的“重建”：
    - 复用现有 recreate action。
    - 成功后 `env_restart_required` 清除。
 
-如果 agent 正在运行，保存 MCP 配置不停止当前 runtime。当前 runtime 继续使用旧 MCP 配置，直到 recreate 完成。
+如果 agent 正在运行，保存 MCP 配置会触发 runtime recreate。当前路径会重建该 agent 的 runtime 进程，不依赖 hot reload。
 
 ## 7. 验证计划
 
@@ -444,11 +455,13 @@ MCP 修改保存后，前端不自动刷新或假装生效。
 - 非 object server entry 报错。
 - 缺少 `command` 和 `url` 的 server entry 报错。
 - 保存 MCP 时保留其它 runtime options。
-- MCP 配置变更后 agent 标记 `env_restart_required`。
+- MCP 配置变更后先标记 `env_restart_required`，随后自动调用 `Recreate`。
 - `Recreate` 后重新 provision，并把最新 MCP 传给 runtime adapter。
+- 自动 `Recreate` 成功后清除 `env_restart_required`。
+- 自动 `Recreate` 失败后保留已保存的 `runtime_options.mcp` 和 `env_restart_required = true`。
 - `openclawsandbox.renderConfig` 能把 `runtime_options.mcp.mcpServers` 渲染为 `mcp.servers`。
 - OpenClaw `null` 清除和空集合渲染行为正确。
-- `syncGatewayHostConfig` 在 MCP configured 或 restart required 状态下会打出可诊断日志。
+- `syncGatewayHostConfig` 在 MCP configured 或 restart required 状态下会打出可诊断日志，并且重写 host config 时不会丢失 MCP 配置。
 
 前端测试：
 
@@ -457,24 +470,27 @@ MCP 修改保存后，前端不自动刷新或假装生效。
 - 保存 MCP 时不覆盖其它 runtime options。
 - 替换 MCP 时提交合并后的 `runtime_options`。
 - 清除 MCP 时提交合并后的 `runtime_options`。
-- 保存并重建按顺序调用 update 和 recreate。
+- 保存已有 agent 的 MCP 配置时只调用 update；recreate 由后端自动完成。
+- update 失败后刷新 agent，并能展示现有 recreate required 状态。
 
 手工验证：
 
 1. 创建 agent，带一个 stdio MCP server。
 2. 对 OpenClaw agent，检查宿主机 `~/.csgclaw/agents/<agent>/.openclaw/openclaw.json` 包含 `mcp.servers`。
 3. 启动 agent 后确认 runtime 能看到 MCP tool。
-4. 修改 MCP 配置并只保存，确认 UI 标记需要重建，旧 runtime 不被停止。
-5. 点击重建，确认新配置生效，`env_restart_required` 清除。
-6. 在 MCP pending 状态下修改 profile，确认日志能看到 host config sync 记录。
+4. 修改 MCP 配置并保存，确认后端自动重建 runtime。
+5. 自动重建成功后确认新配置生效，`env_restart_required` 清除。
+6. 模拟 recreate 失败，确认已保存 MCP 配置保留，`env_restart_required` 为 true，现有重建 action 可恢复。
+7. MCP 配置生效后修改 profile，确认 host config sync 不会丢失 `mcp.servers`，并能看到诊断日志。
 
 ## 8. 实施顺序
 
 1. 增加 `runtime_options.mcp` parser/validator 和共享 helper。
 2. 扩展 provision request，把 `Agent.RuntimeOptions` 传到 runtime provision 边界。
-3. 增加通用 MCP restart policy：`runtime_options.mcp` 变化后标记 `env_restart_required`。
+3. 增加通用 MCP recreate policy：`runtime_options.mcp` 变化后标记 `env_restart_required`，并对已支持的 gateway runtime 自动调用现有 `Recreate`。
 4. 增加关键路径结构化日志，尤其是 MCP save/provision 和 gateway host config sync。
 5. 实现 OpenClaw adapter，把 `runtime_options.mcp.mcpServers` 渲染到 `openclaw.json` 的 `mcp.servers`。
-6. 接入其它 runtime adapter 的 MCP 原生渲染路径；没有可生效路径时返回明确错误，不静默忽略。
-7. 接入前端 Agent 创建/详情页 MCP runtime options UI。
-8. 补充 `docs/api.zh.md` 和相关英文 API 文档。
+6. 让 `syncGatewayHostConfig` 重写 host config 时也传入并渲染当前 `Agent.RuntimeOptions`，避免 profile 热同步丢失 MCP。
+7. 接入其它 runtime adapter 的 MCP 原生渲染路径；没有可生效路径时返回明确错误，不静默忽略。
+8. 接入前端 Agent 创建/详情页 MCP runtime options UI。
+9. 补充 `docs/api.zh.md` 和相关英文 API 文档。

From d746dd981ceb76727d8782f46f392bddc72a61c7 Mon Sep 17 00:00:00 2001
From: GatewayJ <835269233@qq.com>
Date: Thu, 2 Jul 2026 12:04:03 +0800
Subject: [PATCH 4/7] feat: add OpenClaw MCP runtime options

---
 docs/openclaw-mcp-restart-plan.zh.md          |  96 ++---
 internal/agent/service.go                     |  28 +-
 internal/agent/service_profiles.go            |  37 +-
 internal/agent/service_test.go                | 355 ++++++++++++++++++
 internal/runtime/mcp_options.go               |   3 +
 internal/runtime/openclawsandbox/config.go    |  13 +-
 .../openclawsandbox/config_controller.go      |  21 ++
 .../runtime/openclawsandbox/config_test.go    | 208 ++++++++++
 internal/runtime/openclawsandbox/mcp.go       | 277 ++++++++++++++
 .../runtime/openclawsandbox/provision_test.go |  29 +-
 internal/runtime/openclawsandbox/runtime.go   |   2 +-
 internal/runtime/provision.go                 |   1 +
 .../MCPRuntimeOptionsPanel.tsx                | 105 ++++++
 .../ProfileControls/ProfileControls.css       |  51 +++
 .../business/ProfileControls/index.ts         |   1 +
 web/app/src/models/agents.ts                  |  60 +++
 .../AgentDetailPane/AgentDetailPane.tsx       |  45 ++-
 .../WorkspaceModals/AgentProfileModal.tsx     |  19 +
 web/app/src/shared/i18n/messages.ts           |  14 +
 .../tests/components/AgentActions.test.tsx    |  83 +++-
 .../components/AgentProfileModal.test.tsx     | 130 ++++++-
 web/app/tests/models/agents.test.ts           |  45 +++
 22 files changed, 1540 insertions(+), 83 deletions(-)
 create mode 100644 internal/runtime/mcp_options.go
 create mode 100644 internal/runtime/openclawsandbox/config_controller.go
 create mode 100644 internal/runtime/openclawsandbox/mcp.go
 create mode 100644 web/app/src/components/business/ProfileControls/MCPRuntimeOptionsPanel.tsx

diff --git a/docs/openclaw-mcp-restart-plan.zh.md b/docs/openclaw-mcp-restart-plan.zh.md
index 6537519a..60b36ad0 100644
--- a/docs/openclaw-mcp-restart-plan.zh.md
+++ b/docs/openclaw-mcp-restart-plan.zh.md
@@ -1,6 +1,6 @@
-# 通用 Runtime MCP 配置接入方案
+# OpenClaw Runtime MCP 配置接入方案
 
-本文档约束 CSGClaw 为 agent 增加 MCP 能力的实现方案。文件名保留 OpenClaw 历史语境，但方案本身按通用 runtime 能力设计：MCP 配置先存入 agent 的 `runtime_options.mcp`，再由各 runtime adapter 在 provision/recreate 阶段渲染为对应运行时的原生配置。
+本文档约束 CSGClaw 为 OpenClaw agent 增加 MCP 能力的阶段一实现方案。阶段一只支持 `openclaw_sandbox`：MCP 配置先存入 agent 的 `runtime_options.mcp`，再由 OpenClaw runtime adapter 在 provision/recreate 阶段渲染为 OpenClaw 原生配置。非 OpenClaw runtime 暂不接收 `runtime_options.mcp`，后续 runtime 如需支持再单独接入。
 
 阶段一沿用现有 gateway runtime 配置变更路径：MCP 配置保存后进入 CSGClaw 持久化状态，并立即触发现有 agent recreate 流程；recreate 成功后，新 runtime 进程加载最新 MCP 配置，`env_restart_required` 被清除。recreate 失败时，已保存的 MCP 配置保留在 agent state 中，`env_restart_required` 继续为 true，用户可通过现有“重建”动作重试。阶段一不依赖 runtime hot reload。
 
@@ -8,17 +8,19 @@
 
 目标：
 
-- 所有 runtime kind 使用统一 API 形态：`runtime_options.mcp`。
-- MCP 配置由 CSGClaw 管理，随 agent create/update 持久化。
+- OpenClaw agent 使用现有 API 形态：`runtime_options.mcp`。
+- MCP 配置由 CSGClaw 管理，随 OpenClaw agent create/update 持久化。
 - 创建 agent 时，MCP 配置随首次 provision 生效。
 - 修改已有 agent 的 MCP 配置后，后端通过现有 agent recreate 流程自动生效。
-- runtime adapter 负责把 `runtime_options.mcp` 转成原生配置；OpenClaw adapter 渲染到 `mcp.servers`。
+- OpenClaw adapter 负责把 `runtime_options.mcp` 转成 `openclaw.json` 中的 `mcp.servers`。
+- 非 OpenClaw runtime 收到 `runtime_options.mcp` 时返回明确错误，不静默忽略。
 
 非目标：
 
 - 阶段一不做 MCP marketplace、自动安装、连接测试或动态发现。
 - 阶段一不依赖任一 runtime 的 MCP hot reload 保证。
 - 阶段一不新增 CLI MCP 参数或 `agent update` 子命令。
+- 阶段一不抽象通用 MCP runtime policy，也不接入 PicoClaw/Codex。
 - 暂不处理 MCP secret 脱敏体验；API 和前端沿用 `runtime_options` 的现有回显语义。
 
 ## 2. 当前 OpenClaw 配置注入路径
@@ -76,7 +78,7 @@ node /app/openclaw.mjs gateway --allow-unconfigured --bind lan --port 18789
 
 ## 3. MCP 配置形态
 
-CSGClaw API 接收与 Multica 一致的 MCP server 输入形态，但位置放在 `runtime_options.mcp`：
+CSGClaw API 接收与 Multica 一致的 MCP server 配置输入形态，但位置放在 `runtime_options.mcp`。这里的 `mcpServers` 是配置包裹形态，不是 MCP 标准协议的 JSON-RPC 消息格式；真正的 MCP 协议交互由 OpenClaw runtime 和对应 MCP server 处理。
 
 ```json
 {
@@ -122,7 +124,7 @@ OpenClaw adapter 渲染到 OpenClaw 原生配置：
 }
 ```
 
-通用约束：
+输入约束：
 
 - 持久化后的 `runtime_options.mcp` 缺失表示该 agent 没有 CSGClaw 管理的 MCP 配置。
 - API update 的字段缺失语义以第 5.2 节为准：`runtime_options` 整体缺失才表示不修改；`runtime_options` 一旦提交就是整体替换。
@@ -158,16 +160,13 @@ OpenClaw 约束：
 
 注意：当前 `PATCH /api/v1/agents/{id}` 的 `runtime_options` 是整体替换语义。前端保存 MCP 时必须基于当前 agent 的 `runtime_options` 合并后提交，避免只提交 `{"mcp": ...}` 时覆盖其它 runtime option，例如 Codex 的 `local_workspace_dir`。
 
-建议增加共享 helper：
+实现时保留现有 runtime option 边界，只增加最小共享常量和 OpenClaw 内部解析逻辑：
 
 ```go
 const RuntimeOptionMCPKey = "mcp"
-
-func ExtractMCPConfig(runtimeOptions map[string]any) (MCPConfigState, error)
-func RuntimeOptionsWithMCP(runtimeOptions map[string]any, mcp any) map[string]any
 ```
 
-`MCPConfigState` 至少区分：
+OpenClaw 解析状态至少区分：
 
 - absent
 - cleared/null
@@ -191,7 +190,7 @@ Agent.RuntimeOptions["mcp"]
   -> Service.provisionRuntimeForAgent(...)
   -> agentruntime.ProvisionRequest.RuntimeOptions
   -> concrete runtime Provision(...)
-  -> runtime MCP adapter
+  -> OpenClaw MCP adapter
   -> native runtime config
 ```
 
@@ -216,29 +215,13 @@ updateOpenClawGatewayAuth
 updateOpenClawMCP
 ```
 
-### 4.3 Runtime adapter 策略
-
-每个 runtime kind 都通过同一个 `runtime_options.mcp` 输入获得 MCP 配置，但落地方式由 runtime adapter 决定。
-
-建议定义 runtime MCP policy：
-
-```go
-type RuntimeMCPPolicy interface {
-    ValidateMCPConfig(runtimeOptions map[string]any) error
-    MCPRestartRequired(previous, current map[string]any) bool
-}
-```
-
-对 provisioner runtime，adapter 在 `Provision` 期间渲染原生配置。对非 provisioner runtime，如果 MCP 需要写入启动前配置，也应把写入逻辑放在 runtime 自己的 host-side preparation 路径中，不要散落到 API handler 或 agent service。
+### 4.3 OpenClaw adapter 策略
 
-阶段一默认策略：
+阶段一复用现有 `RuntimeConfigController` 扩展点，不新增 MCP 专用跨 runtime 抽象。OpenClaw runtime controller 负责：
 
-- `runtime_options.mcp` 变更后需要通过 recreate 生效。
-- 后端保存已有 agent 的 MCP 配置后，立即调用现有 recreate 流程。
-- recreate 成功后清除 `env_restart_required`。
-- recreate 失败时保留 `env_restart_required = true`，让用户可通过现有重建动作重试。
-- 不依赖 runtime hot reload。
-- 如果某个 runtime adapter 已确认支持安全热应用，可以后续单独改 policy。
+- 校验 `runtime_options.mcp`。
+- 判断 `runtime_options.mcp` 变更是否需要 recreate。
+- 在 `Provision` 期间把 MCP 配置渲染进 `openclaw.json`。
 
 OpenClaw adapter：
 
@@ -246,11 +229,10 @@ OpenClaw adapter：
 - `null` 清除 CSGClaw 管理的 `mcp.servers`。
 - `{}` 或空 `mcpServers` 写入 `mcp.servers: {}`。
 
-PicoClaw/Codex/其它 runtime：
+非 OpenClaw runtime：
 
-- 复用相同 `runtime_options.mcp` 输入和校验。
-- 由对应 runtime adapter 渲染为其原生 MCP 配置或启动参数。
-- 不允许静默忽略已保存 MCP 配置；如果 adapter 暂无可生效路径，应在 validate/provision 阶段返回明确错误，避免用户误以为配置已经生效。
+- 阶段一不支持 `runtime_options.mcp`。
+- create/update/start 等需要校验 runtime config 的路径遇到 `runtime_options.mcp` 时返回明确错误。
 
 ### 4.4 保存与自动重建
 
@@ -284,21 +266,8 @@ PicoClaw/Codex/其它 runtime：
 实现要求：
 
 - 保持现有 `syncGatewayHostConfig` 的 profile 热同步能力。
-- `syncGatewayHostConfig` 调用 OpenClaw/PicoClaw `EnsureConfig` 时必须传入当前 `Agent.RuntimeOptions`。
+- `syncGatewayHostConfig` 调用 OpenClaw `EnsureConfig` 时必须传入当前 `Agent.RuntimeOptions`。
 - `EnsureConfig`/`renderConfig` 每次写 host config 都应根据当前 `runtime_options.mcp` 渲染 runtime 原生 MCP 配置。
-- 如果当前 agent 配置了 `runtime_options.mcp` 或 `env_restart_required = true`，打印结构化日志。
-- 日志至少包含 `agent_id`、`agent_name`、`runtime_kind`、`mcp_configured`、`env_restart_required`、`stage`。
-- 日志用于定位“保存 MCP 后是否又发生了 host config 写入”，但正确性必须由重新渲染 MCP 保证。
-
-建议日志点：
-
-- MCP 配置保存成功。
-- MCP 配置清除成功。
-- runtime provision 开始渲染 MCP。
-- runtime provision 写入原生配置成功。
-- `syncGatewayHostConfig` 在 MCP configured 或 restart required 状态下执行。
-- recreate 成功。
-- recreate 失败且保留 `env_restart_required`。
 
 ## 5. API 设计
 
@@ -390,10 +359,11 @@ PicoClaw/Codex/其它 runtime：
 
 ### 6.1 页面位置
 
-在现有 Agent 创建和编辑路径中增加通用 MCP 区域：
+在现有 Agent 创建和编辑路径中增加 OpenClaw MCP 区域：
 
 - 创建 agent modal：`AgentProfileModal` 的 runtime section 下展示。
 - Agent 详情页：`AgentDetailPane` 的 runtime section 下展示。
+- 仅当 draft 的 `runtime_kind` 为 `openclaw_sandbox` 时展示。
 - 控件读写 `draft.runtime_options.mcp`，不引入 top-level `mcp_config` 状态。
 
 MCP 区域可以做成专用组件，但它必须作为 runtime options 的编辑器存在：
@@ -408,8 +378,8 @@ MCPRuntimeOptionsPanel
 
 - 标题：`MCP Servers`
 - JSON 编辑器：textarea 或轻量 code editor，保存前做 JSON parse。
-- 操作按钮：保存、清除配置、取消。
-- 状态提示：保存时提示会自动重建 runtime；如果后端返回 recreate 失败，刷新 agent 并显示现有 `env_restart_required` badge 和“重建”按钮。
+- 操作按钮：填入示例、清除配置。
+- 保存动作复用创建/编辑表单已有保存按钮，不在 MCP 面板内新增独立保存流程。
 
 创建 agent 时：
 
@@ -461,7 +431,8 @@ MCP 修改保存后，后端负责自动重建 runtime；前端不再提供专
 - 自动 `Recreate` 失败后保留已保存的 `runtime_options.mcp` 和 `env_restart_required = true`。
 - `openclawsandbox.renderConfig` 能把 `runtime_options.mcp.mcpServers` 渲染为 `mcp.servers`。
 - OpenClaw `null` 清除和空集合渲染行为正确。
-- `syncGatewayHostConfig` 在 MCP configured 或 restart required 状态下会打出可诊断日志，并且重写 host config 时不会丢失 MCP 配置。
+- 非 OpenClaw runtime 收到 `runtime_options.mcp` 时返回明确错误。
+- `syncGatewayHostConfig` 重写 OpenClaw host config 时不会丢失 MCP 配置。
 
 前端测试：
 
@@ -487,10 +458,9 @@ MCP 修改保存后，后端负责自动重建 runtime；前端不再提供专
 
 1. 增加 `runtime_options.mcp` parser/validator 和共享 helper。
 2. 扩展 provision request，把 `Agent.RuntimeOptions` 传到 runtime provision 边界。
-3. 增加通用 MCP recreate policy：`runtime_options.mcp` 变化后标记 `env_restart_required`，并对已支持的 gateway runtime 自动调用现有 `Recreate`。
-4. 增加关键路径结构化日志，尤其是 MCP save/provision 和 gateway host config sync。
-5. 实现 OpenClaw adapter，把 `runtime_options.mcp.mcpServers` 渲染到 `openclaw.json` 的 `mcp.servers`。
-6. 让 `syncGatewayHostConfig` 重写 host config 时也传入并渲染当前 `Agent.RuntimeOptions`，避免 profile 热同步丢失 MCP。
-7. 接入其它 runtime adapter 的 MCP 原生渲染路径；没有可生效路径时返回明确错误，不静默忽略。
-8. 接入前端 Agent 创建/详情页 MCP runtime options UI。
-9. 补充 `docs/api.zh.md` 和相关英文 API 文档。
+3. 增加 OpenClaw runtime config controller：`runtime_options.mcp` 变化后标记 `env_restart_required`，并自动调用现有 `Recreate`。
+4. 实现 OpenClaw adapter，把 `runtime_options.mcp.mcpServers` 渲染到 `openclaw.json` 的 `mcp.servers`。
+5. 让 `syncGatewayHostConfig` 重写 OpenClaw host config 时也传入并渲染当前 `Agent.RuntimeOptions`，避免 profile 热同步丢失 MCP。
+6. 拒绝非 OpenClaw runtime 的 `runtime_options.mcp`。
+7. 接入前端 Agent 创建/详情页 MCP runtime options UI。
+8. 补充 `docs/api.zh.md` 和相关英文 API 文档。
diff --git a/internal/agent/service.go b/internal/agent/service.go
index fbb57c02..7b762681 100644
--- a/internal/agent/service.go
+++ b/internal/agent/service.go
@@ -1126,10 +1126,13 @@ func (s *Service) replace(ctx context.Context, req CreateRequest) (Agent, error)
 		return s.ensureManager(ctx, true, managerImageOverride, spec.RuntimeKind)
 	}
 	if shouldCreateWorkerSpec(spec) || strings.EqualFold(existing.Role, RoleWorker) {
+		spec.Role = RoleWorker
+		if err := s.validateReplaceWorkerSpecBeforeDelete(ctx, spec); err != nil {
+			return Agent{}, err
+		}
 		if err := s.Delete(ctx, existing.ID); err != nil {
 			return Agent{}, err
 		}
-		spec.Role = RoleWorker
 		return s.CreateWorker(ctx, spec)
 	}
 
@@ -1139,6 +1142,24 @@ func (s *Service) replace(ctx context.Context, req CreateRequest) (Agent, error)
 	return s.createNew(ctx, spec)
 }
 
+func (s *Service) validateReplaceWorkerSpecBeforeDelete(ctx context.Context, spec CreateAgentSpec) error {
+	runtimeKind := strings.TrimSpace(spec.RuntimeKind)
+	switch {
+	case runtimeKind == "":
+		return fmt.Errorf("runtime_kind is required")
+	case isGatewayRuntimeKind(runtimeKind) && strings.TrimSpace(spec.Image) == "":
+		return fmt.Errorf("image is required for runtime_kind %q", runtimeKind)
+	}
+	if _, err := s.runtimeForKind(runtimeKind); err != nil {
+		return err
+	}
+	resolvedProfile, err := s.profileForCreateRequest(ctx, &spec)
+	if err != nil {
+		return err
+	}
+	return s.validateRuntimeConfig(ctx, runtimeKind, runtimeConfigSnapshotForAgent(s.hydrateProfileFromCatalog(resolvedProfile), spec.RuntimeOptions))
+}
+
 func (s *Service) managerImageOverrideForReplace(ctx context.Context, existing Agent, runtimeKind string) string {
 	runtimeKind = strings.TrimSpace(runtimeKind)
 	if runtimeKind == "" {
@@ -1877,6 +1898,9 @@ func (s *Service) CreateWorker(ctx context.Context, spec CreateAgentSpec) (Agent
 	if err != nil {
 		return Agent{}, err
 	}
+	if err := validateMCPRuntimeOptionSupport(runtimeKind, spec.RuntimeOptions); err != nil {
+		return Agent{}, err
+	}
 	resolvedProfile, err := s.profileForCreateRequest(ctx, &spec)
 	if err != nil {
 		return Agent{}, err
@@ -1892,6 +1916,7 @@ func (s *Service) CreateWorker(ctx context.Context, spec CreateAgentSpec) (Agent
 		ParticipantID:    participantIDForAgent(name, id),
 		AgentName:        name,
 		Profile:          runtimeProfile,
+		RuntimeOptions:   utils.CloneAnyMap(spec.RuntimeOptions),
 		WorkspaceOverlay: strings.TrimSpace(spec.FromTemplate),
 	}); err != nil {
 		return Agent{}, fmt.Errorf("provision worker runtime: %w", err)
@@ -2112,6 +2137,7 @@ func (s *Service) provisionRuntimeForAgent(ctx context.Context, rt agentruntime.
 		ParticipantID:    participantIDForAgent(got.Name, got.ID),
 		AgentName:        strings.TrimSpace(got.Name),
 		Profile:          s.runtimeProfileForAgent(got),
+		RuntimeOptions:   utils.CloneAnyMap(got.RuntimeOptions),
 		WorkspaceOverlay: strings.TrimSpace(workspaceOverlay),
 	})
 }
diff --git a/internal/agent/service_profiles.go b/internal/agent/service_profiles.go
index 7d4dabd2..b29ad499 100644
--- a/internal/agent/service_profiles.go
+++ b/internal/agent/service_profiles.go
@@ -164,13 +164,13 @@ func (s *Service) syncGatewayAfterProfileChange(ctx context.Context, id string,
 		_, err := s.EnsureManager(ctx, false)
 		return err
 	}
-	if gatewayProfileRuntimeRestartRequired(previous, normalized) {
-		return s.syncGatewayHostConfig(got, runtimeNormalized)
-	}
 	if restartRequired {
 		_, err := s.Recreate(ctx, id)
 		return err
 	}
+	if gatewayProfileRuntimeRestartRequired(previous, normalized) {
+		return s.syncGatewayHostConfig(got, runtimeNormalized)
+	}
 	return nil
 }
 
@@ -192,7 +192,7 @@ func (s *Service) syncGatewayHostConfig(got Agent, profile AgentProfile) error {
 			return err
 		}
 		feishuProvider := s.currentFeishuProviderForRuntime(RuntimeKindOpenClawSandbox)
-		if _, err := openclawsandbox.EnsureConfig(agentHome, participantID, got.ID, s.server, modelCfg, resolveManagerBaseURL, feishuProvider); err != nil {
+		if _, err := openclawsandbox.EnsureConfigWithRuntimeOptions(agentHome, participantID, got.ID, s.server, modelCfg, got.RuntimeOptions, resolveManagerBaseURL, feishuProvider); err != nil {
 			return fmt.Errorf("sync gateway openclaw config: %w", err)
 		}
 	default:
@@ -353,6 +353,10 @@ func (s *Service) Update(ctx context.Context, id string, req UpdateRequest) (Age
 				req.RuntimeOptions = &empty
 			}
 			patch = *req.RuntimeOptions
+			if err := validateMCPRuntimeOptionSupport(runtimeKind, patch); err != nil {
+				s.mu.Unlock()
+				return Agent{}, err
+			}
 		}
 		mergedFlat := runtimeOptionsAfterPatch(current.RuntimeKind, current.RuntimeOptions, nil)
 		if runtimeOptionsUpdated {
@@ -478,6 +482,17 @@ func runtimeConfigSnapshotForAgent(profile AgentProfile, options map[string]any)
 	}
 }
 
+func validateMCPRuntimeOptionSupport(runtimeKind string, options map[string]any) error {
+	_, ok := options[agentruntime.RuntimeOptionMCPKey]
+	if !ok {
+		return nil
+	}
+	if strings.TrimSpace(runtimeKind) == RuntimeKindOpenClawSandbox {
+		return nil
+	}
+	return fmt.Errorf("runtime_options.%s is only supported for runtime_kind %q", agentruntime.RuntimeOptionMCPKey, RuntimeKindOpenClawSandbox)
+}
+
 func (s *Service) hydrateProfileFromCatalog(profile AgentProfile) AgentProfile {
 	if s == nil {
 		return profile
@@ -547,6 +562,9 @@ func (s *Service) validateRuntimeConfig(ctx context.Context, runtimeKind string,
 	if runtimeKind == "" {
 		return nil
 	}
+	if err := validateMCPRuntimeOptionSupport(runtimeKind, current.Options); err != nil {
+		return err
+	}
 	rt, err := s.runtimeForKind(runtimeKind)
 	if err != nil {
 		return err
@@ -755,11 +773,12 @@ func (s *Service) recreate(ctx context.Context, id string, imageFor func(context
 		return Agent{}, fmt.Errorf("refresh gateway template skills: %w", err)
 	}
 	if err := s.provisionRuntime(ctx, runtimeImpl, runtimeKind, agentruntime.ProvisionRequest{
-		RuntimeID:     createSpec.RuntimeID,
-		AgentID:       createSpec.AgentID,
-		ParticipantID: participantIDForAgent(createSpec.AgentName, createSpec.AgentID),
-		AgentName:     createSpec.AgentName,
-		Profile:       runtimeProfile,
+		RuntimeID:      createSpec.RuntimeID,
+		AgentID:        createSpec.AgentID,
+		ParticipantID:  participantIDForAgent(createSpec.AgentName, createSpec.AgentID),
+		AgentName:      createSpec.AgentName,
+		Profile:        runtimeProfile,
+		RuntimeOptions: utils.CloneAnyMap(got.RuntimeOptions),
 	}); err != nil {
 		return Agent{}, fmt.Errorf("provision agent runtime: %w", err)
 	}
diff --git a/internal/agent/service_test.go b/internal/agent/service_test.go
index ea924ae4..d9c993b7 100644
--- a/internal/agent/service_test.go
+++ b/internal/agent/service_test.go
@@ -8,6 +8,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"reflect"
 	"strings"
 	"syscall"
 	"testing"
@@ -1512,6 +1513,360 @@ func TestUpdateCodexLocalWorkspaceDirMarksRunningRuntimeForRestart(t *testing.T)
 	}
 }
 
+func TestUpdateOpenClawMCPRuntimeOptionsRecreatesAndProvisionsLatestOptions(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+
+	var provisionCalls []agentruntime.ProvisionRequest
+	reconcileCalls := 0
+	svc, err := NewService(
+		testModelConfig(),
+		config.ServerConfig{
+			ListenAddr:       "127.0.0.1:18080",
+			AdvertiseBaseURL: "http://127.0.0.1:18080",
+			AccessToken:      "shared-token",
+		},
+		"openclaw-image:test",
+		"",
+		WithRuntime(fakeAgentRuntime{
+			kind: RuntimeKindOpenClawSandbox,
+			restart: func(change agentruntime.RuntimeConfigChange) (bool, error) {
+				return !reflect.DeepEqual(change.Previous.Options["mcp"], change.Current.Options["mcp"]), nil
+			},
+			reconcile: func(context.Context, agentruntime.Handle, agentruntime.RuntimeConfigChange) error {
+				reconcileCalls++
+				return nil
+			},
+			provision: func(_ context.Context, req agentruntime.ProvisionRequest) error {
+				provisionCalls = append(provisionCalls, req)
+				return nil
+			},
+			new: func(_ context.Context, spec agentruntime.Spec) (agentruntime.Handle, error) {
+				return agentruntime.Handle{RuntimeID: spec.RuntimeID, HandleID: "openclaw-box-new"}, nil
+			},
+			info: func(context.Context, agentruntime.Handle) (agentruntime.Info, error) {
+				return agentruntime.Info{
+					HandleID:  "openclaw-box-new",
+					State:     agentruntime.StateRunning,
+					CreatedAt: time.Date(2026, 6, 26, 9, 0, 0, 0, time.UTC),
+				}, nil
+			},
+		}),
+	)
+	if err != nil {
+		t.Fatalf("NewService() error = %v", err)
+	}
+	currentProfile := AgentProfile{
+		Name:            "alice",
+		Provider:        ProviderAPI,
+		BaseURL:         "https://api.example/v1",
+		APIKey:          "api-key",
+		ModelID:         "qwen3.7-max",
+		ProfileComplete: true,
+	}
+	svc.agents["u-alice"] = Agent{
+		ID:          "u-alice",
+		Name:        "alice",
+		RuntimeID:   "rt-u-alice",
+		RuntimeKind: RuntimeKindOpenClawSandbox,
+		Image:       "openclaw-image:test",
+		BoxID:       "openclaw-box-old",
+		Role:        RoleWorker,
+		Status:      string(agentruntime.StateRunning),
+		RuntimeOptions: map[string]any{
+			"local_workspace_dir": "/tmp/keep",
+		},
+		AgentProfile:    currentProfile,
+		ProfileComplete: true,
+		CreatedAt:       time.Date(2026, 5, 18, 9, 0, 0, 0, time.UTC),
+	}
+
+	nextRuntimeOptions := map[string]any{
+		"local_workspace_dir": "/tmp/keep",
+		"mcp": map[string]any{
+			"mcpServers": map[string]any{
+				"context7": map[string]any{
+					"command": "uvx",
+					"args":    []any{"context7-mcp"},
+				},
+			},
+		},
+	}
+	updated, err := svc.Update(context.Background(), "u-alice", UpdateRequest{RuntimeOptions: &nextRuntimeOptions})
+	if err != nil {
+		t.Fatalf("Update() error = %v", err)
+	}
+	if reconcileCalls != 1 {
+		t.Fatalf("ReconcileConfig() calls = %d, want 1", reconcileCalls)
+	}
+	if len(provisionCalls) != 1 {
+		t.Fatalf("Provision() calls = %d, want 1", len(provisionCalls))
+	}
+	if got, want := provisionCalls[0].RuntimeOptions["local_workspace_dir"], "/tmp/keep"; got != want {
+		t.Fatalf("Provision().RuntimeOptions local_workspace_dir = %#v, want %q", got, want)
+	}
+	mcpRoot, ok := provisionCalls[0].RuntimeOptions["mcp"].(map[string]any)
+	if !ok {
+		t.Fatalf("Provision().RuntimeOptions[mcp] = %#v, want object", provisionCalls[0].RuntimeOptions["mcp"])
+	}
+	servers := mcpRoot["mcpServers"].(map[string]any)
+	if _, ok := servers["context7"]; !ok {
+		t.Fatalf("Provision().RuntimeOptions mcpServers = %#v, want context7", servers)
+	}
+	if updated.AgentProfile.EnvRestartRequired {
+		t.Fatal("Update().AgentProfile.EnvRestartRequired = true, want false after successful recreate")
+	}
+	if got, want := updated.BoxID, "openclaw-box-new"; got != want {
+		t.Fatalf("Update().BoxID = %q, want %q", got, want)
+	}
+}
+
+func TestUpdateOpenClawMCPRuntimeOptionsRecreateFailureKeepsRestartRequired(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+
+	svc, err := NewService(
+		testModelConfig(),
+		config.ServerConfig{
+			ListenAddr:       "127.0.0.1:18080",
+			AdvertiseBaseURL: "http://127.0.0.1:18080",
+			AccessToken:      "shared-token",
+		},
+		"openclaw-image:test",
+		"",
+		WithRuntime(fakeAgentRuntime{
+			kind: RuntimeKindOpenClawSandbox,
+			restart: func(change agentruntime.RuntimeConfigChange) (bool, error) {
+				return !reflect.DeepEqual(change.Previous.Options["mcp"], change.Current.Options["mcp"]), nil
+			},
+			provision: func(context.Context, agentruntime.ProvisionRequest) error {
+				return fmt.Errorf("provision failed")
+			},
+		}),
+	)
+	if err != nil {
+		t.Fatalf("NewService() error = %v", err)
+	}
+	currentProfile := AgentProfile{
+		Name:            "alice",
+		Provider:        ProviderAPI,
+		BaseURL:         "https://api.example/v1",
+		APIKey:          "api-key",
+		ModelID:         "qwen3.7-max",
+		ProfileComplete: true,
+	}
+	svc.agents["u-alice"] = Agent{
+		ID:              "u-alice",
+		Name:            "alice",
+		RuntimeID:       "rt-u-alice",
+		RuntimeKind:     RuntimeKindOpenClawSandbox,
+		Image:           "openclaw-image:test",
+		BoxID:           "openclaw-box-old",
+		Role:            RoleWorker,
+		Status:          string(agentruntime.StateRunning),
+		AgentProfile:    currentProfile,
+		ProfileComplete: true,
+		CreatedAt:       time.Date(2026, 5, 18, 9, 0, 0, 0, time.UTC),
+	}
+
+	nextRuntimeOptions := map[string]any{
+		"mcp": map[string]any{
+			"mcpServers": map[string]any{
+				"context7": map[string]any{"command": "uvx"},
+			},
+		},
+	}
+	_, err = svc.Update(context.Background(), "u-alice", UpdateRequest{RuntimeOptions: &nextRuntimeOptions})
+	if err == nil || !strings.Contains(err.Error(), "provision failed") {
+		t.Fatalf("Update() error = %v, want provision failed", err)
+	}
+	got, ok := svc.Agent("u-alice")
+	if !ok {
+		t.Fatal("Agent() ok = false, want true")
+	}
+	if !got.AgentProfile.EnvRestartRequired {
+		t.Fatal("Agent().AgentProfile.EnvRestartRequired = false, want true after failed recreate")
+	}
+	if _, ok := got.RuntimeOptions["mcp"].(map[string]any); !ok {
+		t.Fatalf("Agent().RuntimeOptions = %#v, want saved mcp config", got.RuntimeOptions)
+	}
+	if got.BoxID != "openclaw-box-old" {
+		t.Fatalf("Agent().BoxID = %q, want old box id after failed recreate", got.BoxID)
+	}
+}
+
+func TestUpdateMCPRuntimeOptionsRejectsNonOpenClawRuntime(t *testing.T) {
+	svc, err := NewService(
+		testModelConfig(),
+		config.ServerConfig{},
+		"manager-image:test",
+		"",
+		WithRuntime(fakeAgentRuntime{kind: RuntimeKindPicoClawSandbox}),
+	)
+	if err != nil {
+		t.Fatalf("NewService() error = %v", err)
+	}
+	svc.agents["u-dev"] = Agent{
+		ID:              "u-dev",
+		Name:            "dev",
+		RuntimeID:       "rt-u-dev",
+		RuntimeKind:     RuntimeKindPicoClawSandbox,
+		Image:           "picoclaw-image:test",
+		Role:            RoleWorker,
+		Status:          "profile_incomplete",
+		AgentProfile:    AgentProfile{Name: "dev"},
+		ProfileComplete: false,
+		CreatedAt:       time.Date(2026, 5, 18, 9, 0, 0, 0, time.UTC),
+	}
+
+	nextRuntimeOptions := map[string]any{
+		"mcp": map[string]any{"mcpServers": map[string]any{}},
+	}
+	_, err = svc.Update(context.Background(), "u-dev", UpdateRequest{RuntimeOptions: &nextRuntimeOptions})
+	if err == nil || !strings.Contains(err.Error(), `runtime_options.mcp is only supported`) {
+		t.Fatalf("Update() error = %v, want unsupported mcp runtime", err)
+	}
+}
+
+func TestCreateMCPRuntimeOptionsRejectsNonOpenClawRuntime(t *testing.T) {
+	svc, err := NewService(
+		testModelConfig(),
+		config.ServerConfig{},
+		"manager-image:test",
+		"",
+		WithRuntime(fakeAgentRuntime{kind: RuntimeKindPicoClawSandbox}),
+	)
+	if err != nil {
+		t.Fatalf("NewService() error = %v", err)
+	}
+
+	_, err = svc.Create(context.Background(), CreateRequest{Spec: CreateAgentSpec{
+		Name:        "dev",
+		Role:        RoleWorker,
+		RuntimeKind: RuntimeKindPicoClawSandbox,
+		Image:       "picoclaw-image:test",
+		RuntimeOptions: map[string]any{
+			"mcp": map[string]any{"mcpServers": map[string]any{}},
+		},
+	}})
+	if err == nil || !strings.Contains(err.Error(), `runtime_options.mcp is only supported`) {
+		t.Fatalf("Create() error = %v, want unsupported mcp runtime", err)
+	}
+}
+
+func TestReplaceRejectsInheritedMCPBeforeDeletingExistingAgent(t *testing.T) {
+	svc, err := NewService(
+		testModelConfig(),
+		config.ServerConfig{},
+		"manager-image:test",
+		"",
+		WithRuntime(fakeAgentRuntime{kind: RuntimeKindOpenClawSandbox}),
+		WithRuntime(fakeAgentRuntime{kind: RuntimeKindPicoClawSandbox}),
+	)
+	if err != nil {
+		t.Fatalf("NewService() error = %v", err)
+	}
+	svc.agents["u-dev"] = Agent{
+		ID:          "u-dev",
+		Name:        "dev",
+		RuntimeID:   "rt-u-dev",
+		RuntimeKind: RuntimeKindOpenClawSandbox,
+		Image:       "openclaw-image:test",
+		Role:        RoleWorker,
+		Status:      string(agentruntime.StateStopped),
+		RuntimeOptions: map[string]any{
+			"mcp": map[string]any{"mcpServers": map[string]any{"context7": map[string]any{"command": "uvx"}}},
+		},
+		AgentProfile: AgentProfile{
+			Name:            "dev",
+			Provider:        ProviderAPI,
+			BaseURL:         "https://api.example/v1",
+			APIKey:          "api-key",
+			ModelID:         "qwen3.7-max",
+			ProfileComplete: true,
+		},
+		ProfileComplete: true,
+		CreatedAt:       time.Date(2026, 5, 18, 9, 0, 0, 0, time.UTC),
+	}
+
+	_, err = svc.Create(context.Background(), CreateRequest{
+		Replace:   true,
+		FieldMask: []string{"runtime_kind", "image"},
+		Spec: CreateAgentSpec{
+			ID:          "u-dev",
+			RuntimeKind: RuntimeKindPicoClawSandbox,
+			Image:       "picoclaw-image:test",
+		},
+	})
+	if err == nil || !strings.Contains(err.Error(), `runtime_options.mcp is only supported`) {
+		t.Fatalf("Create(replace) error = %v, want unsupported mcp runtime", err)
+	}
+	got, ok := svc.Agent("u-dev")
+	if !ok {
+		t.Fatal("Agent(u-dev) ok = false, want existing agent preserved after failed replace")
+	}
+	if got.RuntimeKind != RuntimeKindOpenClawSandbox {
+		t.Fatalf("Agent().RuntimeKind = %q, want original %q", got.RuntimeKind, RuntimeKindOpenClawSandbox)
+	}
+	if _, ok := got.RuntimeOptions["mcp"].(map[string]any); !ok {
+		t.Fatalf("Agent().RuntimeOptions = %#v, want original mcp preserved", got.RuntimeOptions)
+	}
+}
+
+func TestReplaceRejectsInvalidOpenClawMCPBeforeDeletingExistingAgent(t *testing.T) {
+	svc, err := NewService(
+		testModelConfig(),
+		config.ServerConfig{},
+		"manager-image:test",
+		"",
+		WithRuntime(openclawsandbox.New(openclawsandbox.Dependencies{})),
+	)
+	if err != nil {
+		t.Fatalf("NewService() error = %v", err)
+	}
+	svc.agents["u-dev"] = Agent{
+		ID:          "u-dev",
+		Name:        "dev",
+		RuntimeID:   "rt-u-dev",
+		RuntimeKind: RuntimeKindOpenClawSandbox,
+		Image:       "openclaw-image:test",
+		Role:        RoleWorker,
+		Status:      string(agentruntime.StateStopped),
+		AgentProfile: AgentProfile{
+			Name:            "dev",
+			Provider:        ProviderAPI,
+			BaseURL:         "https://api.example/v1",
+			APIKey:          "api-key",
+			ModelID:         "qwen3.7-max",
+			ProfileComplete: true,
+		},
+		ProfileComplete: true,
+		CreatedAt:       time.Date(2026, 5, 18, 9, 0, 0, 0, time.UTC),
+	}
+
+	_, err = svc.Create(context.Background(), CreateRequest{
+		Replace:   true,
+		FieldMask: []string{"runtime_options"},
+		Spec: CreateAgentSpec{
+			ID: "u-dev",
+			RuntimeOptions: map[string]any{
+				"mcp": map[string]any{
+					"servers": map[string]any{
+						"context7": map[string]any{"command": "uvx"},
+					},
+				},
+			},
+		},
+	})
+	if err == nil || !strings.Contains(err.Error(), `runtime_options.mcp contains unsupported field`) {
+		t.Fatalf("Create(replace) error = %v, want unsupported mcp field", err)
+	}
+	svc.mu.RLock()
+	_, ok := svc.agents["u-dev"]
+	svc.mu.RUnlock()
+	if !ok {
+		t.Fatal("Agent(u-dev) ok = false, want existing agent preserved after failed replace")
+	}
+}
+
 func TestUpdateFieldMaskClearsRuntimeOptions(t *testing.T) {
 	svc, err := NewService(
 		testModelConfig(),
diff --git a/internal/runtime/mcp_options.go b/internal/runtime/mcp_options.go
new file mode 100644
index 00000000..a619929c
--- /dev/null
+++ b/internal/runtime/mcp_options.go
@@ -0,0 +1,3 @@
+package runtime
+
+const RuntimeOptionMCPKey = "mcp"
diff --git a/internal/runtime/openclawsandbox/config.go b/internal/runtime/openclawsandbox/config.go
index 65a6a729..f55b8515 100644
--- a/internal/runtime/openclawsandbox/config.go
+++ b/internal/runtime/openclawsandbox/config.go
@@ -49,11 +49,15 @@ func HostGatewayLogPath(agentHome string) string {
 }
 
 func EnsureConfig(agentHome, participantID, agentID string, server config.ServerConfig, model config.ModelConfig, resolveBaseURL BaseURLResolver, feishuProvider feishu.AgentCredentialProvider) (string, error) {
+	return EnsureConfigWithRuntimeOptions(agentHome, participantID, agentID, server, model, nil, resolveBaseURL, feishuProvider)
+}
+
+func EnsureConfigWithRuntimeOptions(agentHome, participantID, agentID string, server config.ServerConfig, model config.ModelConfig, runtimeOptions map[string]any, resolveBaseURL BaseURLResolver, feishuProvider feishu.AgentCredentialProvider) (string, error) {
 	hostRoot := Root(agentHome)
 	if err := os.MkdirAll(hostRoot, 0o755); err != nil {
 		return "", fmt.Errorf("create openclaw config dir: %w", err)
 	}
-	data, err := renderConfig(participantID, agentID, server, model, resolveBaseURL, feishuProvider)
+	data, err := renderConfigWithRuntimeOptions(participantID, agentID, server, model, runtimeOptions, resolveBaseURL, feishuProvider)
 	if err != nil {
 		return "", err
 	}
@@ -143,6 +147,10 @@ func updateOpenClawWorkspaceDefault(cfg map[string]any, workspace string) {
 	defaults["workspace"] = workspace
 }
 func renderConfig(participantID, agentID string, server config.ServerConfig, model config.ModelConfig, resolveBaseURL BaseURLResolver, feishuProvider feishu.AgentCredentialProvider) ([]byte, error) {
+	return renderConfigWithRuntimeOptions(participantID, agentID, server, model, nil, resolveBaseURL, feishuProvider)
+}
+
+func renderConfigWithRuntimeOptions(participantID, agentID string, server config.ServerConfig, model config.ModelConfig, runtimeOptions map[string]any, resolveBaseURL BaseURLResolver, feishuProvider feishu.AgentCredentialProvider) ([]byte, error) {
 	participantID = strings.TrimSpace(participantID)
 	agentID = strings.TrimSpace(agentID)
 	if participantID == "" {
@@ -168,6 +176,9 @@ func renderConfig(participantID, agentID string, server config.ServerConfig, mod
 		return nil, err
 	}
 	updateOpenClawWorkspaceDefault(cfg, workspaceGuestPathForGOOS(goruntime.GOOS))
+	if err := updateOpenClawMCP(cfg, runtimeOptions); err != nil {
+		return nil, err
+	}
 	data, err := json.MarshalIndent(cfg, "", "  ")
 	if err != nil {
 		return nil, fmt.Errorf("encode openclaw config: %w", err)
diff --git a/internal/runtime/openclawsandbox/config_controller.go b/internal/runtime/openclawsandbox/config_controller.go
new file mode 100644
index 00000000..d7760784
--- /dev/null
+++ b/internal/runtime/openclawsandbox/config_controller.go
@@ -0,0 +1,21 @@
+package openclawsandbox
+
+import (
+	"context"
+
+	agentruntime "csgclaw/internal/runtime"
+)
+
+var _ agentruntime.RuntimeConfigController = (*Runtime)(nil)
+
+func (r *Runtime) ValidateConfig(_ context.Context, current agentruntime.RuntimeConfigSnapshot) error {
+	return validateOpenClawMCPRuntimeOptions(current.Options)
+}
+
+func (r *Runtime) RestartRequired(change agentruntime.RuntimeConfigChange) (bool, error) {
+	return openClawMCPRestartRequired(change.Previous.Options, change.Current.Options)
+}
+
+func (r *Runtime) ReconcileConfig(context.Context, agentruntime.Handle, agentruntime.RuntimeConfigChange) error {
+	return nil
+}
diff --git a/internal/runtime/openclawsandbox/config_test.go b/internal/runtime/openclawsandbox/config_test.go
index 2c511b61..322d01f5 100644
--- a/internal/runtime/openclawsandbox/config_test.go
+++ b/internal/runtime/openclawsandbox/config_test.go
@@ -179,6 +179,214 @@ func TestRenderAgentOpenClawConfigUsesBridgeWhenBaseURLEmpty(t *testing.T) {
 	}
 }
 
+func TestRenderAgentOpenClawConfigRendersMCPServers(t *testing.T) {
+	data, err := renderConfigWithRuntimeOptions("u-worker-1", "u-worker-1", config.ServerConfig{
+		ListenAddr:       "127.0.0.1:18080",
+		AdvertiseBaseURL: "http://127.0.0.1:18080",
+		AccessToken:      "shared-token",
+	}, config.ModelConfig{
+		ModelID: "MiniMax-M2.7",
+	}, map[string]any{
+		"mcp": map[string]any{
+			"mcpServers": map[string]any{
+				"context7": map[string]any{
+					"command": "uvx",
+					"args":    []any{"context7-mcp"},
+					"env": map[string]any{
+						"CONTEXT7_API_KEY": "secret",
+					},
+				},
+				"remote-search": map[string]any{
+					"command":   nil,
+					"url":       "https://mcp.example.com/mcp",
+					"transport": "streamable-http",
+					"headers": map[string]any{
+						"Authorization": "Bearer secret",
+					},
+				},
+			},
+		},
+	}, testBaseURLResolver, nil)
+	if err != nil {
+		t.Fatalf("renderConfigWithRuntimeOptions() error = %v", err)
+	}
+	var cfg map[string]any
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		t.Fatalf("json.Unmarshal: %v", err)
+	}
+	mcp := cfg["mcp"].(map[string]any)
+	servers := mcp["servers"].(map[string]any)
+	context7 := servers["context7"].(map[string]any)
+	if got, want := context7["command"], "uvx"; got != want {
+		t.Fatalf("context7 command = %#v, want %q", got, want)
+	}
+	if got, want := context7["args"], []any{"context7-mcp"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("context7 args = %#v, want %#v", got, want)
+	}
+	env := context7["env"].(map[string]any)
+	if got, want := env["CONTEXT7_API_KEY"], "secret"; got != want {
+		t.Fatalf("context7 env key = %#v, want %q", got, want)
+	}
+	remote := servers["remote-search"].(map[string]any)
+	if got, want := remote["url"], "https://mcp.example.com/mcp"; got != want {
+		t.Fatalf("remote-search url = %#v, want %q", got, want)
+	}
+	if _, ok := remote["command"]; ok {
+		t.Fatalf("remote-search command is present, want nil optional command omitted: %#v", remote)
+	}
+	if got, want := remote["transport"], "streamable-http"; got != want {
+		t.Fatalf("remote-search transport = %#v, want %q", got, want)
+	}
+	headers := remote["headers"].(map[string]any)
+	if got, want := headers["Authorization"], "Bearer secret"; got != want {
+		t.Fatalf("remote-search Authorization = %#v, want %q", got, want)
+	}
+}
+
+func TestRenderAgentOpenClawConfigMCPEmptyAndClearSemantics(t *testing.T) {
+	baseServer := config.ServerConfig{
+		ListenAddr:       "127.0.0.1:18080",
+		AdvertiseBaseURL: "http://127.0.0.1:18080",
+		AccessToken:      "shared-token",
+	}
+	baseModel := config.ModelConfig{ModelID: "MiniMax-M2.7"}
+	for _, tc := range []struct {
+		name           string
+		runtimeOptions map[string]any
+		wantMCP        bool
+		wantServers    bool
+	}{
+		{
+			name: "absent does not write mcp",
+		},
+		{
+			name:           "null clears managed mcp",
+			runtimeOptions: map[string]any{"mcp": nil},
+		},
+		{
+			name:           "empty object writes empty servers",
+			runtimeOptions: map[string]any{"mcp": map[string]any{}},
+			wantMCP:        true,
+			wantServers:    true,
+		},
+		{
+			name: "empty mcpServers writes empty servers",
+			runtimeOptions: map[string]any{
+				"mcp": map[string]any{"mcpServers": map[string]any{}},
+			},
+			wantMCP:     true,
+			wantServers: true,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			data, err := renderConfigWithRuntimeOptions("u-worker-1", "u-worker-1", baseServer, baseModel, tc.runtimeOptions, testBaseURLResolver, nil)
+			if err != nil {
+				t.Fatalf("renderConfigWithRuntimeOptions() error = %v", err)
+			}
+			var cfg map[string]any
+			if err := json.Unmarshal(data, &cfg); err != nil {
+				t.Fatalf("json.Unmarshal: %v", err)
+			}
+			mcp, hasMCP := cfg["mcp"].(map[string]any)
+			if hasMCP != tc.wantMCP {
+				t.Fatalf("mcp present = %v, want %v; config:\n%s", hasMCP, tc.wantMCP, data)
+			}
+			if !hasMCP {
+				return
+			}
+			servers, hasServers := mcp["servers"].(map[string]any)
+			if hasServers != tc.wantServers {
+				t.Fatalf("mcp.servers present = %v, want %v; mcp=%#v", hasServers, tc.wantServers, mcp)
+			}
+			if hasServers && len(servers) != 0 {
+				t.Fatalf("mcp.servers = %#v, want empty", servers)
+			}
+		})
+	}
+}
+
+func TestRenderAgentOpenClawConfigRejectsInvalidMCPServer(t *testing.T) {
+	baseServer := config.ServerConfig{
+		ListenAddr:       "127.0.0.1:18080",
+		AdvertiseBaseURL: "http://127.0.0.1:18080",
+		AccessToken:      "shared-token",
+	}
+	baseModel := config.ModelConfig{ModelID: "MiniMax-M2.7"}
+	for _, tc := range []struct {
+		name string
+		mcp  any
+		want string
+	}{
+		{
+			name: "mcp root must be object",
+			mcp:  "invalid",
+			want: "must be an object or null",
+		},
+		{
+			name: "mcpServers must be object",
+			mcp:  map[string]any{"mcpServers": []any{}},
+			want: "mcpServers must be an object",
+		},
+		{
+			name: "mcpServers null is invalid",
+			mcp:  map[string]any{"mcpServers": nil},
+			want: "mcpServers must be an object",
+		},
+		{
+			name: "direct openclaw servers object is rejected",
+			mcp:  map[string]any{"servers": map[string]any{"context7": map[string]any{"command": "uvx"}}},
+			want: "contains unsupported field",
+		},
+		{
+			name: "server entry must be object",
+			mcp:  map[string]any{"mcpServers": map[string]any{"broken": "invalid"}},
+			want: "mcpServers.broken must be an object",
+		},
+		{
+			name: "server requires command or url",
+			mcp:  map[string]any{"mcpServers": map[string]any{"broken": map[string]any{"args": []any{"missing-command-or-url"}}}},
+			want: "must declare command or url",
+		},
+		{
+			name: "blank command is invalid even with url",
+			mcp:  map[string]any{"mcpServers": map[string]any{"broken": map[string]any{"command": " ", "url": "https://mcp.example.com/mcp"}}},
+			want: "command must not be blank",
+		},
+		{
+			name: "blank url is invalid even with command",
+			mcp:  map[string]any{"mcpServers": map[string]any{"broken": map[string]any{"command": "uvx", "url": " "}}},
+			want: "url must not be blank",
+		},
+		{
+			name: "args must contain strings",
+			mcp:  map[string]any{"mcpServers": map[string]any{"broken": map[string]any{"command": "uvx", "args": []any{1}}}},
+			want: "args must be an array of strings",
+		},
+		{
+			name: "env values must be strings",
+			mcp:  map[string]any{"mcpServers": map[string]any{"broken": map[string]any{"command": "uvx", "env": map[string]any{"TOKEN": 1}}}},
+			want: "env must be an object with string values",
+		},
+		{
+			name: "trimmed server names must be unique",
+			mcp: map[string]any{
+				"mcpServers": map[string]any{
+					"same":  map[string]any{"command": "uvx"},
+					" same": map[string]any{"command": "uvx"},
+				},
+			},
+			want: `duplicate server name "same"`,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := renderConfigWithRuntimeOptions("u-worker-1", "u-worker-1", baseServer, baseModel, map[string]any{"mcp": tc.mcp}, testBaseURLResolver, nil)
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("renderConfigWithRuntimeOptions() error = %v, want containing %q", err, tc.want)
+			}
+		})
+	}
+}
+
 func TestRenderAgentOpenClawConfigUsesCodexResponsesModelMetadata(t *testing.T) {
 	data, err := renderConfig("u-manager", "u-manager", config.ServerConfig{
 		ListenAddr:       "127.0.0.1:18080",
diff --git a/internal/runtime/openclawsandbox/mcp.go b/internal/runtime/openclawsandbox/mcp.go
new file mode 100644
index 00000000..93909d26
--- /dev/null
+++ b/internal/runtime/openclawsandbox/mcp.go
@@ -0,0 +1,277 @@
+package openclawsandbox
+
+import (
+	"fmt"
+	"reflect"
+	"sort"
+	"strings"
+
+	agentruntime "csgclaw/internal/runtime"
+)
+
+type openClawMCPMode int
+
+const (
+	openClawMCPAbsent openClawMCPMode = iota
+	openClawMCPCleared
+	openClawMCPManaged
+)
+
+type openClawMCPConfig struct {
+	mode    openClawMCPMode
+	servers map[string]any
+}
+
+func validateOpenClawMCPRuntimeOptions(runtimeOptions map[string]any) error {
+	_, err := openClawMCPConfigFromRuntimeOptions(runtimeOptions)
+	return err
+}
+
+func openClawMCPRestartRequired(previous, current map[string]any) (bool, error) {
+	prev, prevErr := openClawMCPConfigFromRuntimeOptions(previous)
+	currentConfig, err := openClawMCPConfigFromRuntimeOptions(current)
+	if err != nil {
+		return false, err
+	}
+	if prevErr != nil {
+		return true, nil
+	}
+	return !reflect.DeepEqual(openClawMCPEffectiveServers(prev), openClawMCPEffectiveServers(currentConfig)), nil
+}
+
+func updateOpenClawMCP(cfg map[string]any, runtimeOptions map[string]any) error {
+	mcpConfig, err := openClawMCPConfigFromRuntimeOptions(runtimeOptions)
+	if err != nil {
+		return err
+	}
+	switch mcpConfig.mode {
+	case openClawMCPAbsent:
+		return nil
+	case openClawMCPCleared:
+		mcpRoot, ok := cfg["mcp"].(map[string]any)
+		if !ok {
+			return nil
+		}
+		delete(mcpRoot, "servers")
+		if len(mcpRoot) == 0 {
+			delete(cfg, "mcp")
+		}
+		return nil
+	case openClawMCPManaged:
+		mcpRoot, _ := cfg["mcp"].(map[string]any)
+		if mcpRoot == nil {
+			mcpRoot = map[string]any{}
+			cfg["mcp"] = mcpRoot
+		}
+		if mcpConfig.servers == nil {
+			mcpConfig.servers = map[string]any{}
+		}
+		mcpRoot["servers"] = mcpConfig.servers
+		return nil
+	default:
+		return nil
+	}
+}
+
+func openClawMCPEffectiveServers(config openClawMCPConfig) map[string]any {
+	if config.mode != openClawMCPManaged {
+		return nil
+	}
+	if config.servers == nil {
+		return map[string]any{}
+	}
+	return config.servers
+}
+
+func openClawMCPConfigFromRuntimeOptions(runtimeOptions map[string]any) (openClawMCPConfig, error) {
+	raw, ok := runtimeOptions[agentruntime.RuntimeOptionMCPKey]
+	if !ok {
+		return openClawMCPConfig{mode: openClawMCPAbsent}, nil
+	}
+	if raw == nil {
+		return openClawMCPConfig{mode: openClawMCPCleared}, nil
+	}
+	mcpRoot, ok := raw.(map[string]any)
+	if !ok {
+		return openClawMCPConfig{}, fmt.Errorf("runtime_options.%s must be an object or null", agentruntime.RuntimeOptionMCPKey)
+	}
+	if unsupported := unsupportedOpenClawMCPRootKeys(mcpRoot); len(unsupported) > 0 {
+		return openClawMCPConfig{}, fmt.Errorf("runtime_options.%s contains unsupported field(s) %q; only mcpServers is supported", agentruntime.RuntimeOptionMCPKey, strings.Join(unsupported, ", "))
+	}
+	if len(mcpRoot) == 0 {
+		return openClawMCPConfig{mode: openClawMCPManaged, servers: map[string]any{}}, nil
+	}
+	rawServers, ok := mcpRoot["mcpServers"]
+	if !ok {
+		return openClawMCPConfig{mode: openClawMCPManaged, servers: map[string]any{}}, nil
+	}
+	serverMap, ok := rawServers.(map[string]any)
+	if !ok {
+		return openClawMCPConfig{}, fmt.Errorf("runtime_options.%s.mcpServers must be an object", agentruntime.RuntimeOptionMCPKey)
+	}
+	servers := make(map[string]any, len(serverMap))
+	for rawName, rawEntry := range serverMap {
+		name := strings.TrimSpace(rawName)
+		if name == "" {
+			return openClawMCPConfig{}, fmt.Errorf("runtime_options.%s.mcpServers contains an empty server name", agentruntime.RuntimeOptionMCPKey)
+		}
+		if _, exists := servers[name]; exists {
+			return openClawMCPConfig{}, fmt.Errorf("runtime_options.%s.mcpServers contains duplicate server name %q", agentruntime.RuntimeOptionMCPKey, name)
+		}
+		entry, ok := rawEntry.(map[string]any)
+		if !ok {
+			return openClawMCPConfig{}, fmt.Errorf("runtime_options.%s.mcpServers.%s must be an object", agentruntime.RuntimeOptionMCPKey, name)
+		}
+		normalized, err := normalizeOpenClawMCPServerEntry(name, entry)
+		if err != nil {
+			return openClawMCPConfig{}, err
+		}
+		servers[name] = normalized
+	}
+	return openClawMCPConfig{mode: openClawMCPManaged, servers: servers}, nil
+}
+
+func unsupportedOpenClawMCPRootKeys(root map[string]any) []string {
+	out := make([]string, 0)
+	for key := range root {
+		if key != "mcpServers" {
+			out = append(out, key)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+func normalizeOpenClawMCPServerEntry(name string, entry map[string]any) (map[string]any, error) {
+	normalized, ok := cloneMCPJSONObject(entry).(map[string]any)
+	if !ok {
+		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s must be an object", agentruntime.RuntimeOptionMCPKey, name)
+	}
+	command, hasCommand, err := mcpStringField(normalized, "command")
+	if err != nil {
+		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s.command %s", agentruntime.RuntimeOptionMCPKey, name, err)
+	}
+	url, hasURL, err := mcpStringField(normalized, "url")
+	if err != nil {
+		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s.url %s", agentruntime.RuntimeOptionMCPKey, name, err)
+	}
+	if !hasCommand && !hasURL {
+		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s must declare command or url", agentruntime.RuntimeOptionMCPKey, name)
+	}
+	if hasCommand {
+		normalized["command"] = command
+	} else {
+		delete(normalized, "command")
+	}
+	if hasURL {
+		normalized["url"] = url
+	} else {
+		delete(normalized, "url")
+	}
+	if err := validateMCPStringSliceField(normalized, "args"); err != nil {
+		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s.args must be an array of strings", agentruntime.RuntimeOptionMCPKey, name)
+	}
+	if err := validateMCPStringMapField(normalized, "env"); err != nil {
+		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s.env must be an object with string values", agentruntime.RuntimeOptionMCPKey, name)
+	}
+	if err := validateMCPStringMapField(normalized, "headers"); err != nil {
+		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s.headers must be an object with string values", agentruntime.RuntimeOptionMCPKey, name)
+	}
+	if err := validateMCPStringField(normalized, "transport"); err != nil {
+		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s.transport must be a string", agentruntime.RuntimeOptionMCPKey, name)
+	}
+	return normalized, nil
+}
+
+func mcpStringField(values map[string]any, key string) (string, bool, error) {
+	raw, ok := values[key]
+	if !ok || raw == nil {
+		return "", false, nil
+	}
+	text, ok := raw.(string)
+	if !ok {
+		return "", false, fmt.Errorf("must be a string")
+	}
+	text = strings.TrimSpace(text)
+	if text == "" {
+		return "", false, fmt.Errorf("must not be blank")
+	}
+	return text, true, nil
+}
+
+func validateMCPStringField(values map[string]any, key string) error {
+	raw, ok := values[key]
+	if !ok || raw == nil {
+		return nil
+	}
+	_, ok = raw.(string)
+	if !ok {
+		return fmt.Errorf("not a string")
+	}
+	return nil
+}
+
+func validateMCPStringSliceField(values map[string]any, key string) error {
+	raw, ok := values[key]
+	if !ok || raw == nil {
+		return nil
+	}
+	items, ok := raw.([]any)
+	if !ok {
+		return fmt.Errorf("not an array")
+	}
+	for _, item := range items {
+		if _, ok := item.(string); !ok {
+			return fmt.Errorf("contains non-string value")
+		}
+	}
+	return nil
+}
+
+func validateMCPStringMapField(values map[string]any, key string) error {
+	raw, ok := values[key]
+	if !ok || raw == nil {
+		return nil
+	}
+	items, ok := raw.(map[string]any)
+	if !ok {
+		return fmt.Errorf("not an object")
+	}
+	for _, value := range items {
+		if _, ok := value.(string); !ok {
+			return fmt.Errorf("contains non-string value")
+		}
+	}
+	return nil
+}
+
+func cloneMCPJSONObject(value any) any {
+	switch typed := value.(type) {
+	case map[string]any:
+		out := make(map[string]any, len(typed))
+		for key, item := range typed {
+			out[key] = cloneMCPJSONObject(item)
+		}
+		return out
+	case map[string]string:
+		out := make(map[string]any, len(typed))
+		for key, item := range typed {
+			out[key] = item
+		}
+		return out
+	case []any:
+		out := make([]any, len(typed))
+		for idx, item := range typed {
+			out[idx] = cloneMCPJSONObject(item)
+		}
+		return out
+	case []string:
+		out := make([]any, len(typed))
+		for idx, item := range typed {
+			out[idx] = item
+		}
+		return out
+	default:
+		return value
+	}
+}
diff --git a/internal/runtime/openclawsandbox/provision_test.go b/internal/runtime/openclawsandbox/provision_test.go
index 5c519761..dba83bd6 100644
--- a/internal/runtime/openclawsandbox/provision_test.go
+++ b/internal/runtime/openclawsandbox/provision_test.go
@@ -25,10 +25,17 @@ func TestProvisionPreparesGatewayAssets(t *testing.T) {
 	rt := New(Dependencies{})
 
 	if err := rt.Provision(context.Background(), agentruntime.ProvisionRequest{
-		RuntimeID:        "rt-1",
-		AgentID:          "u-alice",
-		AgentName:        "alice",
-		Profile:          agentruntime.Profile{},
+		RuntimeID: "rt-1",
+		AgentID:   "u-alice",
+		AgentName: "alice",
+		Profile:   agentruntime.Profile{},
+		RuntimeOptions: map[string]any{
+			"mcp": map[string]any{
+				"mcpServers": map[string]any{
+					"context7": map[string]any{"command": "uvx", "args": []any{"context7-mcp"}},
+				},
+			},
+		},
 		WorkspaceOverlay: overlayRoot,
 		Gateway: &agentruntime.GatewayProvision{
 			ModelFallback:     "fallback-model",
@@ -45,6 +52,20 @@ func TestProvisionPreparesGatewayAssets(t *testing.T) {
 	if _, err := os.Stat(filepath.Join(agentHome, HostDir, HostConfig)); err != nil {
 		t.Fatalf("stat openclaw config: %v", err)
 	}
+	configRaw, err := os.ReadFile(filepath.Join(agentHome, HostDir, HostConfig))
+	if err != nil {
+		t.Fatalf("ReadFile(openclaw config) error = %v", err)
+	}
+	var configData map[string]any
+	if err := json.Unmarshal(configRaw, &configData); err != nil {
+		t.Fatalf("json.Unmarshal(openclaw config) error = %v", err)
+	}
+	mcp := configData["mcp"].(map[string]any)
+	servers := mcp["servers"].(map[string]any)
+	context7 := servers["context7"].(map[string]any)
+	if got, want := context7["command"], "uvx"; got != want {
+		t.Fatalf("openclaw config mcp.servers.context7.command = %#v, want %q", got, want)
+	}
 	if _, err := os.Stat(filepath.Join(agentHome, HostDir, HostExecApproval)); err != nil {
 		t.Fatalf("stat openclaw approvals: %v", err)
 	}
diff --git a/internal/runtime/openclawsandbox/runtime.go b/internal/runtime/openclawsandbox/runtime.go
index 5155ae70..0874da86 100644
--- a/internal/runtime/openclawsandbox/runtime.go
+++ b/internal/runtime/openclawsandbox/runtime.go
@@ -83,7 +83,7 @@ func (r *Runtime) Provision(_ context.Context, req agentruntime.ProvisionRequest
 	if participantID == "" {
 		participantID = strings.TrimSpace(req.AgentID)
 	}
-	if _, err := EnsureConfig(agentHome, participantID, req.AgentID, gateway.Server, configModelFromProfile(profile), fixedBaseURL(gateway.ManagerBaseURL), r.CurrentFeishuProvider()); err != nil {
+	if _, err := EnsureConfigWithRuntimeOptions(agentHome, participantID, req.AgentID, gateway.Server, configModelFromProfile(profile), req.RuntimeOptions, fixedBaseURL(gateway.ManagerBaseURL), r.CurrentFeishuProvider()); err != nil {
 		return err
 	}
 	workspaceRoot := r.Layout(agentHome).WorkspaceRoot
diff --git a/internal/runtime/provision.go b/internal/runtime/provision.go
index a14f60d2..3f8979e9 100644
--- a/internal/runtime/provision.go
+++ b/internal/runtime/provision.go
@@ -29,6 +29,7 @@ type ProvisionRequest struct {
 	ParticipantID    string
 	AgentName        string
 	Profile          Profile
+	RuntimeOptions   map[string]any
 	WorkspaceOverlay string
 	Gateway          *GatewayProvision
 }
diff --git a/web/app/src/components/business/ProfileControls/MCPRuntimeOptionsPanel.tsx b/web/app/src/components/business/ProfileControls/MCPRuntimeOptionsPanel.tsx
new file mode 100644
index 00000000..b497cb2f
--- /dev/null
+++ b/web/app/src/components/business/ProfileControls/MCPRuntimeOptionsPanel.tsx
@@ -0,0 +1,105 @@
+import { useEffect, useId, useState } from "react";
+import {
+  MCP_RUNTIME_OPTIONS_EXAMPLE,
+  mcpRuntimeOptionsText,
+  parseMCPRuntimeOptionsText,
+  setMCPRuntimeOptions,
+  type AgentDraft,
+  type JSONRecord,
+} from "@/models/agents";
+import type { TranslateFn } from "@/models/conversations";
+import { Button } from "@/components/ui/Button/Button";
+
+export type MCPRuntimeOptionsPanelProps = {
+  draft: AgentDraft;
+  onDraftChange: (draft: AgentDraft) => void;
+  onInvalidChange?: (invalid: boolean) => void;
+  t: TranslateFn;
+};
+
+function cloneMCPExample(): JSONRecord {
+  return JSON.parse(JSON.stringify(MCP_RUNTIME_OPTIONS_EXAMPLE)) as JSONRecord;
+}
+
+function errorMessageForKey(key: "invalid_json" | "object_required", t: TranslateFn): string {
+  return key === "invalid_json" ? t("profileMCPServersInvalidJSON") : t("profileMCPServersObjectRequired");
+}
+
+export function MCPRuntimeOptionsPanel({ draft, onDraftChange, onInvalidChange, t }: MCPRuntimeOptionsPanelProps) {
+  const textareaId = useId();
+  const draftText = mcpRuntimeOptionsText(draft.runtime_options);
+  const [text, setText] = useState(draftText);
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    setText(draftText);
+    setError("");
+    onInvalidChange?.(false);
+  }, [draftText, onInvalidChange]);
+
+  function commitText(nextText: string) {
+    setText(nextText);
+    const parsed = parseMCPRuntimeOptionsText(nextText);
+    if (!parsed.ok) {
+      setError(errorMessageForKey(parsed.error, t));
+      onInvalidChange?.(true);
+      return;
+    }
+    setError("");
+    onInvalidChange?.(false);
+    onDraftChange({
+      ...draft,
+      runtime_options: setMCPRuntimeOptions(draft.runtime_options, parsed.value),
+    });
+  }
+
+  function fillExample() {
+    const example = cloneMCPExample();
+    setError("");
+    onInvalidChange?.(false);
+    setText(JSON.stringify(example, null, 2));
+    onDraftChange({
+      ...draft,
+      runtime_options: setMCPRuntimeOptions(draft.runtime_options, example),
+    });
+  }
+
+  function clearMCPConfig() {
+    setError("");
+    onInvalidChange?.(false);
+    setText("");
+    onDraftChange({
+      ...draft,
+      runtime_options: setMCPRuntimeOptions(draft.runtime_options, null),
+    });
+  }
+
+  return (
+    <div className="field span-2 mcp-runtime-options-panel">
+      <div className="mcp-runtime-options-header">
+        <label htmlFor={textareaId}>{t("profileMCPServers")}</label>
+        <div className="mcp-runtime-options-actions">
+          <Button variant="secondaryGray" size="sm" onClick={fillExample}>
+            {t("profileMCPServersUseExample")}
+          </Button>
+          <Button variant="secondaryGray" size="sm" onClick={clearMCPConfig}>
+            {t("profileMCPServersClear")}
+          </Button>
+        </div>
+      </div>
+      <textarea
+        id={textareaId}
+        className="compact-textarea mcp-runtime-options-textarea"
+        value={text}
+        aria-invalid={error ? "true" : undefined}
+        aria-describedby={`${textareaId}-hint`}
+        placeholder={t("profileMCPServersPlaceholder")}
+        spellCheck={false}
+        onInput={(event) => commitText(event.currentTarget.value)}
+      />
+      <span id={`${textareaId}-hint`} className={`field-hint${error ? " error" : ""}`.trim()}>
+        {error || t("profileMCPServersHint")}
+      </span>
+    </div>
+  );
+}
diff --git a/web/app/src/components/business/ProfileControls/ProfileControls.css b/web/app/src/components/business/ProfileControls/ProfileControls.css
index 2b517522..c730d07d 100644
--- a/web/app/src/components/business/ProfileControls/ProfileControls.css
+++ b/web/app/src/components/business/ProfileControls/ProfileControls.css
@@ -70,6 +70,57 @@
   background: var(--danger);
 }
 
+.mcp-runtime-options-panel {
+  min-width: 0;
+}
+
+.mcp-runtime-options-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  min-width: 0;
+}
+
+.mcp-runtime-options-header > label {
+  min-width: 0;
+  color: var(--text);
+  font-size: var(--text-sm-size);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--text-sm-line-height);
+}
+
+.mcp-runtime-options-actions {
+  display: inline-flex;
+  flex: 0 0 auto;
+  align-items: center;
+  gap: 8px;
+}
+
+.mcp-runtime-options-textarea {
+  min-height: 168px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 12px;
+  line-height: 18px;
+  resize: vertical;
+}
+
+@media (max-width: 680px) {
+  .mcp-runtime-options-header {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .mcp-runtime-options-actions {
+    width: 100%;
+  }
+
+  .mcp-runtime-options-actions .btn {
+    flex: 1 1 0;
+    min-width: 0;
+  }
+}
+
 .field .field-label {
   display: inline-flex;
   align-items: center;
diff --git a/web/app/src/components/business/ProfileControls/index.ts b/web/app/src/components/business/ProfileControls/index.ts
index 68082796..76ce18a6 100644
--- a/web/app/src/components/business/ProfileControls/index.ts
+++ b/web/app/src/components/business/ProfileControls/index.ts
@@ -6,6 +6,7 @@ export * from "./CLIProxyAuthControl";
 export * from "./ClipboardCopyButton";
 export * from "./EnvKeyValueEditor";
 export * from "./FieldHelpTooltip";
+export * from "./MCPRuntimeOptionsPanel";
 export * from "./ModelProviderModelList";
 export * from "./ModelOptionLabel";
 export * from "./NotifierControls";
diff --git a/web/app/src/models/agents.ts b/web/app/src/models/agents.ts
index 41bab28b..4552399f 100644
--- a/web/app/src/models/agents.ts
+++ b/web/app/src/models/agents.ts
@@ -25,6 +25,20 @@ export type BotType = typeof BOT_TYPE_NORMAL | typeof BOT_TYPE_NOTIFICATION | st
 export type ProviderName = "csghub_lite" | "csghub" | "codex" | "claude_code" | "api" | string;
 export type JSONRecord = Record<string, unknown>;
 
+export const MCP_RUNTIME_OPTION_KEY = "mcp";
+export const MCP_RUNTIME_OPTIONS_EXAMPLE: JSONRecord = {
+  mcpServers: {
+    context7: {
+      command: "npx",
+      args: ["-y", "context7-mcp"],
+    },
+  },
+};
+
+export type MCPRuntimeOptionsParseResult =
+  | { ok: true; value: JSONRecord | null }
+  | { ok: false; error: "invalid_json" | "object_required" };
+
 export type RuntimeOptionSchema = {
   key?: string | null;
   path?: string | null;
@@ -515,6 +529,52 @@ function normalizeRuntimeOptionsRecord(value: unknown): JSONRecord {
   return { ...(value as JSONRecord) };
 }
 
+function isJSONRecord(value: unknown): value is JSONRecord {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+export function supportsMCPRuntimeOptions(runtimeKind: unknown): boolean {
+  return normalizeRuntimeKind(runtimeKind) === "openclaw_sandbox";
+}
+
+export function mcpRuntimeOptionsText(runtimeOptions: JSONRecord | null | undefined): string {
+  const value = normalizeRuntimeOptionsRecord(runtimeOptions)[MCP_RUNTIME_OPTION_KEY];
+  if (value == null) {
+    return "";
+  }
+  return JSON.stringify(value, null, 2);
+}
+
+export function parseMCPRuntimeOptionsText(text: string): MCPRuntimeOptionsParseResult {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return { ok: true, value: null };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed) as unknown;
+  } catch {
+    return { ok: false, error: "invalid_json" };
+  }
+  if (!isJSONRecord(parsed)) {
+    return { ok: false, error: "object_required" };
+  }
+  return { ok: true, value: parsed };
+}
+
+export function setMCPRuntimeOptions(
+  runtimeOptions: JSONRecord | null | undefined,
+  value: JSONRecord | null,
+): JSONRecord {
+  const next = normalizeRuntimeOptionsRecord(runtimeOptions);
+  if (value == null) {
+    delete next[MCP_RUNTIME_OPTION_KEY];
+    return next;
+  }
+  next[MCP_RUNTIME_OPTION_KEY] = value;
+  return next;
+}
+
 export function isManagerAgent(item: AgentLike | null | undefined): boolean {
   return item?.role === MANAGER_AGENT_ROLE || item?.id === MANAGER_AGENT_ID;
 }
diff --git a/web/app/src/pages/AgentPage/components/AgentDetailPane/AgentDetailPane.tsx b/web/app/src/pages/AgentPage/components/AgentDetailPane/AgentDetailPane.tsx
index 181472fc..3daa43f2 100644
--- a/web/app/src/pages/AgentPage/components/AgentDetailPane/AgentDetailPane.tsx
+++ b/web/app/src/pages/AgentPage/components/AgentDetailPane/AgentDetailPane.tsx
@@ -18,6 +18,7 @@ import { AGENT_PROFILE_ACTIVE_TAB_STORAGE_KEY } from "@/shared/storage/keys";
 import {
   EnvKeyValueEditor,
   FieldHelpTooltip,
+  MCPRuntimeOptionsPanel,
   ModelOptionLabel,
   NotifierControls,
   requiredFieldLabel,
@@ -43,6 +44,7 @@ import {
   isManagerAgent,
   isNotifierRuntimeDraftOnAgentPage,
   runtimeOptionSchemasForAgent,
+  supportsMCPRuntimeOptions,
 } from "@/models/agents";
 import type { AgentDraft, AgentLike } from "@/models/agents";
 import {
@@ -209,6 +211,7 @@ export function AgentDetailPane({
   const [selectedSkillNames, setSelectedSkillNames] = useState<string[]>([]);
   const [deleteSkillDialogOpen, setDeleteSkillDialogOpen] = useState(false);
   const [skillPendingDelete, setSkillPendingDelete] = useState<SlashSkillOption | null>(null);
+  const [mcpRuntimeOptionsInvalid, setMcpRuntimeOptionsInvalid] = useState(false);
   const descriptionInputRef = useRef<HTMLTextAreaElement | null>(null);
   const nameInputRef = useRef<HTMLInputElement | null>(null);
   const isManager = isManagerAgent(item);
@@ -225,7 +228,7 @@ export function AgentDetailPane({
   const canPublish = runtimeKind === "picoclaw_sandbox" || runtimeKind === "openclaw_sandbox";
   const hasUnsavedChanges =
     hasUnsavedChangesProp ?? Boolean(draft && savedDraft && JSON.stringify(draft) !== JSON.stringify(savedDraft));
-  const saveDisabled = agentProfilePageSaveDisabled(draft, item, { saving, savedDraft });
+  const saveDisabled = agentProfilePageSaveDisabled(draft, item, { saving, savedDraft }) || mcpRuntimeOptionsInvalid;
   const updateDraft = (patch: Partial<AgentDraft>) => onDraftChange?.({ ...(draft || agentToDraft(item)), ...patch });
   const runtimeOptionSchemas = runtimeOptionSchemasForAgent(draft?.runtime_kind || runtimeKind, item);
   const fallbackProviderID = String(draft?.model_provider_id || "").trim();
@@ -251,6 +254,9 @@ export function AgentDetailPane({
   const selectedProviderModels = selectedProvider?.models ?? [];
   const selectedModelValue = draft?.model_id || "";
   const isNotifierDraft = Boolean(draft && isNotifierRuntimeDraftOnAgentPage(draft, item));
+  const showMCPRuntimeOptions = Boolean(
+    draft && !isNotifierDraft && supportsMCPRuntimeOptions(draft.runtime_kind || item.runtime_kind),
+  );
   const profileTabs = useMemo(
     () =>
       draft
@@ -304,6 +310,18 @@ export function AgentDetailPane({
     }
   }, [addSkillsDialogOpen]);
 
+  useEffect(() => {
+    if (visibleActiveProfileTab && activeProfileTab !== visibleActiveProfileTab) {
+      setActiveProfileTab(visibleActiveProfileTab);
+    }
+  }, [activeProfileTab, visibleActiveProfileTab]);
+
+  useEffect(() => {
+    if (!showMCPRuntimeOptions) {
+      setMcpRuntimeOptionsInvalid(false);
+    }
+  }, [showMCPRuntimeOptions]);
+
   async function handleAddSkillsConfirm(): Promise<void> {
     if (!selectedSkillNames.length) {
       return;
@@ -612,6 +630,19 @@ export function AgentDetailPane({
                 onDisconnectFeishu={onDisconnectFeishu}
               />
             ) : null}
+            {visibleActiveProfileTab === "runtime" ? (
+              <AgentRuntimePanel
+                draft={draft}
+                item={item}
+                locale={locale}
+                runtimeKind={runtimeKind}
+                runtimeOptionSchemas={runtimeOptionSchemas}
+                t={t}
+                onDraftChange={onDraftChange}
+                onMCPRuntimeOptionsInvalidChange={setMcpRuntimeOptionsInvalid}
+                showMCPRuntimeOptions={showMCPRuntimeOptions}
+              />
+            ) : null}
 
             {visibleActiveProfileTab === "instructions" && !isNotifierDraft ? (
               <AgentInstructionsPanel draft={draft} t={t} updateDraft={updateDraft} />
@@ -787,8 +818,10 @@ type AgentRuntimePanelProps = {
   item: AgentLike;
   locale: LocaleCode;
   onDraftChange?: (draft: AgentDraft) => void;
+  onMCPRuntimeOptionsInvalidChange: (invalid: boolean) => void;
   runtimeKind: string;
   runtimeOptionSchemas: RuntimeOptionSchemaList;
+  showMCPRuntimeOptions: boolean;
   t: TranslateFn;
 };
 
@@ -797,8 +830,10 @@ function AgentRuntimePanel({
   item,
   locale,
   onDraftChange,
+  onMCPRuntimeOptionsInvalidChange,
   runtimeKind,
   runtimeOptionSchemas,
+  showMCPRuntimeOptions,
   t,
 }: AgentRuntimePanelProps) {
   const isNotifierDraft = isNotifierRuntimeDraftOnAgentPage(draft, item);
@@ -845,6 +880,14 @@ function AgentRuntimePanel({
               embedded
             />
           ) : null}
+          {showMCPRuntimeOptions ? (
+            <MCPRuntimeOptionsPanel
+              draft={draft}
+              t={t}
+              onDraftChange={onDraftChange || (() => {})}
+              onInvalidChange={onMCPRuntimeOptionsInvalidChange}
+            />
+          ) : null}
         </div>
       </div>
     </section>
diff --git a/web/app/src/pages/WorkspacePage/components/WorkspaceModals/AgentProfileModal.tsx b/web/app/src/pages/WorkspacePage/components/WorkspaceModals/AgentProfileModal.tsx
index d65f58bc..19e1ca12 100644
--- a/web/app/src/pages/WorkspacePage/components/WorkspaceModals/AgentProfileModal.tsx
+++ b/web/app/src/pages/WorkspacePage/components/WorkspaceModals/AgentProfileModal.tsx
@@ -9,6 +9,7 @@ import {
   EnvKeyValueEditor,
   FieldHelpTooltip,
   isBlank,
+  MCPRuntimeOptionsPanel,
   ModelOptionLabel,
   NotifierControls,
   requiredFieldLabel,
@@ -30,6 +31,7 @@ import {
   pickDefaultAgentTemplate,
   defaultWorkerImageForRuntime,
   runtimeOptionSchemasForAgent,
+  supportsMCPRuntimeOptions,
   templateMatchesRuntime,
   workerSelectableTemplates,
 } from "@/models/agents";
@@ -108,6 +110,7 @@ export function AgentProfileModal({
   onSave,
 }: AgentProfileModalProps) {
   const [isEditorScrolling, setIsEditorScrolling] = useState(false);
+  const [mcpRuntimeOptionsInvalid, setMcpRuntimeOptionsInvalid] = useState(false);
   const editorScrollTimerRef = useRef<number | null>(null);
   const lastTemplateIDRef = useRef("");
   const createBotKind = agentModalMode === "create" ? agentCreateBotKind : undefined;
@@ -116,6 +119,7 @@ export function AgentProfileModal({
   const isTemplateCreate = isWorkerCreate && agentCreateMode === "template";
   const isCustomCreate = isWorkerCreate && agentCreateMode === "custom";
   const templateLocked = agentCreateTemplateLocked(agentDraft, agentModalMode);
+  const showMCPRuntimeOptions = !isNotificationContext && supportsMCPRuntimeOptions(agentDraft.runtime_kind);
   const runtimeOptionSchemas = isNotificationContext
     ? []
     : runtimeOptionSchemasForAgent(
@@ -245,6 +249,12 @@ export function AgentProfileModal({
     [],
   );
 
+  useEffect(() => {
+    if (!showMCPRuntimeOptions) {
+      setMcpRuntimeOptionsInvalid(false);
+    }
+  }, [showMCPRuntimeOptions]);
+
   function onEditorShellScroll() {
     setIsEditorScrolling(true);
     if (editorScrollTimerRef.current) {
@@ -548,6 +558,14 @@ export function AgentProfileModal({
                       embedded
                     />
                   ) : null}
+                  {showMCPRuntimeOptions ? (
+                    <MCPRuntimeOptionsPanel
+                      draft={agentDraft}
+                      t={t}
+                      onDraftChange={onAgentDraftChange}
+                      onInvalidChange={setMcpRuntimeOptionsInvalid}
+                    />
+                  ) : null}
                 </div>
               </div>
             </section>
@@ -718,6 +736,7 @@ export function AgentProfileModal({
             size="md"
             disabled={
               agentBusy ||
+              mcpRuntimeOptionsInvalid ||
               isBlank(agentDraft.name) ||
               (isNotificationContext
                 ? !notifierFormIsComplete(agentDraft, editingAgent)
diff --git a/web/app/src/shared/i18n/messages.ts b/web/app/src/shared/i18n/messages.ts
index 8e856691..753c662d 100644
--- a/web/app/src/shared/i18n/messages.ts
+++ b/web/app/src/shared/i18n/messages.ts
@@ -534,6 +534,13 @@ export const messages = {
     profileModelSection: "模型配置",
     profileModelSectionDescription: "选择模型并调整推理方式。",
     profileRuntimeOptions: "运行时选项",
+    profileMCPServers: "MCP Servers",
+    profileMCPServersHint: '推荐形态：{"mcpServers":{...}}。',
+    profileMCPServersPlaceholder: '{\n  "mcpServers": {}\n}',
+    profileMCPServersUseExample: "填入示例",
+    profileMCPServersClear: "清除配置",
+    profileMCPServersInvalidJSON: "请输入有效的 JSON object。",
+    profileMCPServersObjectRequired: "MCP 配置必须是 JSON object。",
     profileAPIProvider: "API Provider",
     profileNotifierSection: "通知投递",
     profileNotifierSectionDescription: "配置通知的投递方式与连接信息。",
@@ -1423,6 +1430,13 @@ export const messages = {
     profileModelSection: "Model configuration",
     profileModelSectionDescription: "Choose a model and adjust its reasoning behavior.",
     profileRuntimeOptions: "Runtime Options",
+    profileMCPServers: "MCP Servers",
+    profileMCPServersHint: 'Recommended shape: {"mcpServers":{...}}.',
+    profileMCPServersPlaceholder: '{\n  "mcpServers": {}\n}',
+    profileMCPServersUseExample: "Use example",
+    profileMCPServersClear: "Clear config",
+    profileMCPServersInvalidJSON: "Enter a valid JSON object.",
+    profileMCPServersObjectRequired: "MCP config must be a JSON object.",
     profileAPIProvider: "API Provider",
     profileNotifierSection: "Notifications",
     profileNotifierSectionDescription: "Configure notification delivery and connection details.",
diff --git a/web/app/tests/components/AgentActions.test.tsx b/web/app/tests/components/AgentActions.test.tsx
index db2168db..fadc3274 100644
--- a/web/app/tests/components/AgentActions.test.tsx
+++ b/web/app/tests/components/AgentActions.test.tsx
@@ -1,4 +1,4 @@
-import { render, screen, within } from "@testing-library/react";
+import { fireEvent, render, screen, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { useState } from "react";
 import { AgentDetailPane, AgentRow, AgentView, NotificationParticipantDetailPane } from "@/pages/AgentPage/components";
@@ -59,6 +59,13 @@ const labels: Record<string, string> = {
   profileRuntimeKind: "Runtime",
   profileRuntimeSection: "Runtime environment",
   close: "Close",
+  profileMCPServers: "MCP Servers",
+  profileMCPServersHint: 'Recommended shape: {"mcpServers":{...}}.',
+  profileMCPServersPlaceholder: '{\n  "mcpServers": {}\n}',
+  profileMCPServersUseExample: "Use example",
+  profileMCPServersClear: "Clear config",
+  profileMCPServersInvalidJSON: "Enter a valid JSON object.",
+  profileMCPServersObjectRequired: "MCP config must be a JSON object.",
   agentName: "Name",
   agentDescription: "Description",
   agentImage: "Image",
@@ -799,6 +806,80 @@ describe("agent action visibility", () => {
     expect(screen.queryByLabelText("Image")).not.toBeInTheDocument();
   });
 
+  it("edits MCP runtime options in the detail runtime section for OpenClaw agents", async () => {
+    const user = userEvent.setup();
+    const onDraftChange = vi.fn();
+    const item = {
+      ...worker,
+      runtime_kind: "openclaw_sandbox",
+      runtime_options: {
+        local_workspace_dir: "/tmp/project",
+        mcp: {
+          mcpServers: {
+            existing: {
+              command: "node",
+            },
+          },
+        },
+      },
+    };
+
+    render(
+      <AgentDetailPane
+        item={item}
+        t={t}
+        activeRoom={null}
+        busyKey=""
+        error=""
+        draft={agentToDraft(item)}
+        models={[]}
+        modelBusy={false}
+        saving={false}
+        publishBusy={false}
+        saveError=""
+        authStatuses={{}}
+        authBusyProvider=""
+        notifierWebhookPublicOrigin="http://127.0.0.1:18080"
+        onDraftChange={onDraftChange}
+        onSave={vi.fn()}
+        onPublish={vi.fn()}
+        onProviderLogin={vi.fn()}
+        onStart={vi.fn()}
+        onStop={vi.fn()}
+        onRecreate={vi.fn()}
+        onDelete={vi.fn()}
+        onInvite={vi.fn()}
+        onOpenDM={vi.fn()}
+      />,
+    );
+
+    await user.click(screen.getByRole("button", { name: "Runtime environment" }));
+
+    const editor = screen.getByLabelText("MCP Servers");
+    expect((editor as HTMLTextAreaElement).value).toContain('"existing"');
+
+    fireEvent.input(editor, {
+      target: {
+        value: '{"mcpServers":{"context7":{"command":"npx"}}}',
+      },
+    });
+
+    expect(onDraftChange).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        runtime_options: {
+          local_workspace_dir: "/tmp/project",
+          mcp: {
+            mcpServers: {
+              context7: {
+                command: "npx",
+              },
+            },
+          },
+        },
+      }),
+    );
+  });
+
   it("shows a saved status instead of a save button when the draft is unchanged", () => {
     const draft = agentToDraft(worker);
     render(
diff --git a/web/app/tests/components/AgentProfileModal.test.tsx b/web/app/tests/components/AgentProfileModal.test.tsx
index 7ca7d38d..cccba6cf 100644
--- a/web/app/tests/components/AgentProfileModal.test.tsx
+++ b/web/app/tests/components/AgentProfileModal.test.tsx
@@ -1,4 +1,4 @@
-import { render, screen } from "@testing-library/react";
+import { fireEvent, render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { useState } from "react";
 import { AgentProfileModal } from "@/pages/WorkspacePage/components";
@@ -30,7 +30,14 @@ const labels: Record<string, string> = {
   modelProviderModelSearch: "Search models",
   modelProviderNoModels: "No models",
   profileRuntimeOptions: "Runtime Options",
-  profileProvider: "Model Provider",
+  profileMCPServers: "MCP Servers",
+  profileMCPServersHint: 'Recommended shape: {"mcpServers":{...}}.',
+  profileMCPServersPlaceholder: '{\n  "mcpServers": {}\n}',
+  profileMCPServersUseExample: "Use example",
+  profileMCPServersClear: "Clear config",
+  profileMCPServersInvalidJSON: "Enter a valid JSON object.",
+  profileMCPServersObjectRequired: "MCP config must be a JSON object.",
+  profileProvider: "Provider",
   profileRuntimeKind: "Runtime",
   profileEnv: "Environment",
   profileSandboxEnabled: "Sandbox",
@@ -43,6 +50,8 @@ const labels: Record<string, string> = {
   statusDisabled: "Disabled",
   templateLabel: "Template",
   templateNone: "No template",
+  agentCreateSave: "Create",
+  agentUpdateSave: "Save",
 };
 
 function t(key: string): string {
@@ -845,6 +854,123 @@ describe("AgentProfileModal", () => {
     );
   });
 
+  it("edits MCP runtime options only for OpenClaw agent drafts", async () => {
+    const user = userEvent.setup();
+    const onAgentDraftChange = vi.fn();
+    const openclawDraft = {
+      ...agentToDraft({ ...worker, runtime_kind: "openclaw_sandbox" }),
+      model_provider_id: "api",
+      runtime_kind: "openclaw_sandbox",
+      runtime_options: {
+        local_workspace_dir: "/tmp/project",
+        mcp: {
+          mcpServers: {
+            existing: {
+              command: "node",
+            },
+          },
+        },
+      },
+    };
+
+    const { rerender } = render(
+      <AgentProfileModal
+        t={t}
+        agentModalMode="create"
+        editingAgent={null}
+        agentDraft={openclawDraft}
+        locale="en"
+        onAgentDraftChange={onAgentDraftChange}
+        onAgentModelsReset={vi.fn()}
+        hubTemplates={[]}
+        bootstrapConfig={{}}
+        managerAgent={null}
+        agentModels={[]}
+        agentModelBusy={false}
+        authStatuses={{}}
+        authBusyProvider=""
+        agentCreateBotKind="worker"
+        agentCreateMode="custom"
+        onAgentCreateBotKindChange={vi.fn()}
+        notifierWebhookPublicOrigin="http://127.0.0.1:18080"
+        onProviderLogin={vi.fn()}
+        agentError=""
+        agentProgress={null}
+        agentBusy={false}
+        onClose={vi.fn()}
+        onSave={vi.fn()}
+      />,
+    );
+
+    const editor = screen.getByLabelText("MCP Servers");
+    expect((editor as HTMLTextAreaElement).value).toContain('"existing"');
+
+    fireEvent.input(editor, {
+      target: {
+        value: '{"mcpServers":{"context7":{"command":"npx"}}}',
+      },
+    });
+
+    expect(onAgentDraftChange).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        runtime_options: {
+          local_workspace_dir: "/tmp/project",
+          mcp: {
+            mcpServers: {
+              context7: {
+                command: "npx",
+              },
+            },
+          },
+        },
+      }),
+    );
+
+    await user.click(screen.getByRole("button", { name: "Clear config" }));
+
+    expect(onAgentDraftChange).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        runtime_options: {
+          local_workspace_dir: "/tmp/project",
+        },
+      }),
+    );
+
+    rerender(
+      <AgentProfileModal
+        t={t}
+        agentModalMode="create"
+        editingAgent={null}
+        agentDraft={{
+          ...openclawDraft,
+          runtime_kind: "picoclaw_sandbox",
+        }}
+        locale="en"
+        onAgentDraftChange={onAgentDraftChange}
+        onAgentModelsReset={vi.fn()}
+        hubTemplates={[]}
+        bootstrapConfig={{}}
+        managerAgent={null}
+        agentModels={[]}
+        agentModelBusy={false}
+        authStatuses={{}}
+        authBusyProvider=""
+        agentCreateBotKind="worker"
+        agentCreateMode="custom"
+        onAgentCreateBotKindChange={vi.fn()}
+        notifierWebhookPublicOrigin="http://127.0.0.1:18080"
+        onProviderLogin={vi.fn()}
+        agentError=""
+        agentProgress={null}
+        agentBusy={false}
+        onClose={vi.fn()}
+        onSave={vi.fn()}
+      />,
+    );
+
+    expect(screen.queryByLabelText("MCP Servers")).not.toBeInTheDocument();
+  });
+
   it("shows provider logos only in the provider field, not in the model field", () => {
     const { container } = render(
       <AgentProfileModal
diff --git a/web/app/tests/models/agents.test.ts b/web/app/tests/models/agents.test.ts
index 195b80c4..69a5ccab 100644
--- a/web/app/tests/models/agents.test.ts
+++ b/web/app/tests/models/agents.test.ts
@@ -30,12 +30,14 @@ import {
   mergeAgentIntoList,
   isNotificationBotAgent,
   mapToEnvRows,
+  mcpRuntimeOptionsText,
   partitionWorkspaceAgentItems,
   notifierComputedPullRoutes,
   notifierFormIsComplete,
   notifierThirdPartyRelayWebhookURL,
   normalizeAuthProviderName,
   normalizeRuntimeKind,
+  parseMCPRuntimeOptionsText,
   notificationPushWebhookPathForBot,
   parseJSONMap,
   pickDefaultAgentTemplate,
@@ -47,8 +49,10 @@ import {
   resolveAgentAvatarSource,
   runtimeImageForKind,
   runtimeOptionSchemasForAgent,
+  setMCPRuntimeOptions,
   localizedRuntimeOptionLabel,
   localizedRuntimeOptionDescription,
+  supportsMCPRuntimeOptions,
   shouldWaitForManagerRuntimeAfterProfileSave,
   workerSelectableTemplates,
 } from "@/models/agents";
@@ -506,6 +510,47 @@ describe("agent model helpers", () => {
     ).toBe("Leave empty to use the default agent workspace.");
   });
 
+  it("parses and saves OpenClaw MCP runtime options under runtime_options.mcp", () => {
+    const parsed = parseMCPRuntimeOptionsText('{"mcpServers":{"context7":{"command":"npx","args":["-y"]}}}');
+
+    expect(parsed).toEqual({
+      ok: true,
+      value: {
+        mcpServers: {
+          context7: {
+            command: "npx",
+            args: ["-y"],
+          },
+        },
+      },
+    });
+    expect(parseMCPRuntimeOptionsText("")).toEqual({ ok: true, value: null });
+    expect(parseMCPRuntimeOptionsText("[1]")).toEqual({ ok: false, error: "object_required" });
+    expect(parseMCPRuntimeOptionsText("{")).toEqual({ ok: false, error: "invalid_json" });
+    expect(supportsMCPRuntimeOptions("openclaw_sandbox")).toBe(true);
+    expect(supportsMCPRuntimeOptions("picoclaw_sandbox")).toBe(false);
+
+    const runtimeOptions = setMCPRuntimeOptions(
+      { local_workspace_dir: "/tmp/project" },
+      { mcpServers: { context7: { command: "npx" } } },
+    );
+    expect(runtimeOptions).toEqual({
+      local_workspace_dir: "/tmp/project",
+      mcp: {
+        mcpServers: {
+          context7: {
+            command: "npx",
+          },
+        },
+      },
+    });
+    expect(mcpRuntimeOptionsText(runtimeOptions)).toContain('"mcpServers"');
+    expect(draftRuntimeOptionsForSave({ runtime_options: runtimeOptions })).toEqual(runtimeOptions);
+    expect(setMCPRuntimeOptions(runtimeOptions, null)).toEqual({
+      local_workspace_dir: "/tmp/project",
+    });
+  });
+
   it("selects runtime-specific templates and images", () => {
     const templates = [
       { id: "builtin.picoclaw-manager", name: "picoclaw-manager", role: "manager", runtime_kind: "picoclaw_sandbox" },

From b79c2cc0d06633fb9da04cda3404740cd95a6c8f Mon Sep 17 00:00:00 2001
From: GatewayJ <835269233@qq.com>
Date: Fri, 3 Jul 2026 17:10:03 +0800
Subject: [PATCH 5/7] fix(web): clear mcp options on runtime switch

---
 .../WorkspaceModals/AgentProfileModal.tsx     | 129 +++++++++++-------
 .../components/AgentProfileModal.test.tsx     |  79 +++++++++++
 2 files changed, 159 insertions(+), 49 deletions(-)

diff --git a/web/app/src/pages/WorkspacePage/components/WorkspaceModals/AgentProfileModal.tsx b/web/app/src/pages/WorkspacePage/components/WorkspaceModals/AgentProfileModal.tsx
index 19e1ca12..9d618142 100644
--- a/web/app/src/pages/WorkspacePage/components/WorkspaceModals/AgentProfileModal.tsx
+++ b/web/app/src/pages/WorkspacePage/components/WorkspaceModals/AgentProfileModal.tsx
@@ -1,7 +1,4 @@
-import {
-  BOT_TYPE_NORMAL,
-  DEFAULT_RUNTIME_KIND,
-} from "@/shared/constants/agents";
+import { BOT_TYPE_NORMAL, DEFAULT_RUNTIME_KIND } from "@/shared/constants/agents";
 import { useEffect, useRef, useState, type SetStateAction } from "react";
 import {
   AgentCreateProgress,
@@ -24,6 +21,7 @@ import {
   composeLegacyRuntimeKind,
   formatRuntimeKindLabel,
   isNotificationBotDraftContext,
+  MCP_RUNTIME_OPTION_KEY,
   normalizeRuntimeKind,
   normalizeRuntimeName,
   normalizeTemplateSelection,
@@ -31,6 +29,7 @@ import {
   pickDefaultAgentTemplate,
   defaultWorkerImageForRuntime,
   runtimeOptionSchemasForAgent,
+  setMCPRuntimeOptions,
   supportsMCPRuntimeOptions,
   templateMatchesRuntime,
   workerSelectableTemplates,
@@ -166,12 +165,30 @@ export function AgentProfileModal({
     agentDraft.runtime_name || (sandboxEnabled ? defaultSandboxRuntimeName : "codex"),
   );
 
+  function runtimeOptionsForRuntimeKind(
+    runtimeOptions: AgentDraft["runtime_options"],
+    runtimeKind: string,
+  ): AgentDraft["runtime_options"] {
+    if (supportsMCPRuntimeOptions(runtimeKind) || !runtimeOptions || !(MCP_RUNTIME_OPTION_KEY in runtimeOptions)) {
+      return runtimeOptions;
+    }
+    const next = setMCPRuntimeOptions(runtimeOptions, null);
+    return Object.keys(next).length > 0 ? next : undefined;
+  }
+
+  function draftWithRuntimeOptionsForRuntimeKind(draft: AgentDraft): AgentDraft {
+    return {
+      ...draft,
+      runtime_options: runtimeOptionsForRuntimeKind(draft.runtime_options, draft.runtime_kind),
+    };
+  }
+
   function defaultCustomWorkerDraft(baseDraft: AgentDraft): AgentDraft {
     const codexAvailable = codexChoice?.installed !== false;
     const runtimeName = codexAvailable ? "codex" : defaultSandboxRuntimeName;
     const nextSandboxEnabled = !codexAvailable;
     const runtimeKind = composeLegacyRuntimeKind(runtimeName, nextSandboxEnabled) || DEFAULT_RUNTIME_KIND;
-    return {
+    return draftWithRuntimeOptionsForRuntimeKind({
       ...baseDraft,
       bot_type: BOT_TYPE_NORMAL,
       description: "",
@@ -190,7 +207,7 @@ export function AgentProfileModal({
         : "",
       from_template: "",
       template_name: "",
-    };
+    });
   }
 
   useEffect(() => {
@@ -209,34 +226,38 @@ export function AgentProfileModal({
     if (nextSandboxEnabled) {
       const runtimeName = defaultSandboxRuntimeName;
       const runtimeKind = composeLegacyRuntimeKind(runtimeName, true) || DEFAULT_RUNTIME_KIND;
-      onAgentDraftChange({
+      onAgentDraftChange(
+        draftWithRuntimeOptionsForRuntimeKind({
+          ...agentDraft,
+          bot_type: BOT_TYPE_NORMAL,
+          sandbox_enabled: true,
+          runtime_name: runtimeName,
+          runtime_kind: runtimeKind,
+          image: defaultWorkerImageForRuntime(
+            hubTemplates,
+            runtimeKind,
+            bootstrapConfig,
+            agentDraft.default_image || managerAgent?.image || "",
+          ),
+          from_template: "",
+          template_name: "",
+        }),
+      );
+      onAgentModelsReset();
+      return;
+    }
+    onAgentDraftChange(
+      draftWithRuntimeOptionsForRuntimeKind({
         ...agentDraft,
         bot_type: BOT_TYPE_NORMAL,
-        sandbox_enabled: true,
-        runtime_name: runtimeName,
-        runtime_kind: runtimeKind,
-        image: defaultWorkerImageForRuntime(
-          hubTemplates,
-          runtimeKind,
-          bootstrapConfig,
-          agentDraft.default_image || managerAgent?.image || "",
-        ),
+        sandbox_enabled: false,
+        runtime_name: "codex",
+        runtime_kind: "codex",
+        image: "",
         from_template: "",
         template_name: "",
-      });
-      onAgentModelsReset();
-      return;
-    }
-    onAgentDraftChange({
-      ...agentDraft,
-      bot_type: BOT_TYPE_NORMAL,
-      sandbox_enabled: false,
-      runtime_name: "codex",
-      runtime_kind: "codex",
-      image: "",
-      from_template: "",
-      template_name: "",
-    });
+      }),
+    );
     onAgentModelsReset();
   }
 
@@ -278,9 +299,12 @@ export function AgentProfileModal({
           pickDefaultAgentTemplate(hubTemplates, agentDraft.runtime_kind, bootstrapConfig) ||
           null,
       );
-      onAgentDraftChange((current) =>
-        current ? applyTemplateToDraft(current, nextTemplate, bootstrapConfig, managerAgent?.image || "") : current,
-      );
+      onAgentDraftChange((current) => {
+        const next = current
+          ? applyTemplateToDraft(current, nextTemplate, bootstrapConfig, managerAgent?.image || "")
+          : current;
+        return next ? draftWithRuntimeOptionsForRuntimeKind(next) : next;
+      });
       return;
     }
     onAgentDraftChange((current) => (current ? defaultCustomWorkerDraft(current) : current));
@@ -379,7 +403,9 @@ export function AgentProfileModal({
                       <textarea
                         className="compact-textarea"
                         value={agentDraft.description}
-                        onInput={(event) => onAgentDraftChange({ ...agentDraft, description: event.currentTarget.value })}
+                        onInput={(event) =>
+                          onAgentDraftChange({ ...agentDraft, description: event.currentTarget.value })
+                        }
                       />
                     </label>
                   </div>
@@ -410,11 +436,13 @@ export function AgentProfileModal({
                         );
                       }}
                       triggerProps={{ "aria-label": t("templateLabel") }}
-                      options={workerTemplates.filter((item) => item.id).map((item) => ({
-                        value: item.id || "",
-                        label: item.name || item.id || "",
-                        description: String(item.description || "").trim() || undefined,
-                      }))}
+                      options={workerTemplates
+                        .filter((item) => item.id)
+                        .map((item) => ({
+                          value: item.id || "",
+                          label: item.name || item.id || "",
+                          description: String(item.description || "").trim() || undefined,
+                        }))}
                     />
                     <small className="field-hint">{t("templateHelp")}</small>
                   </label>
@@ -467,16 +495,18 @@ export function AgentProfileModal({
                           <Select
                             value="codex"
                             onValueChange={(value) => {
-                              onAgentDraftChange({
-                                ...agentDraft,
-                                bot_type: BOT_TYPE_NORMAL,
-                                sandbox_enabled: false,
-                                runtime_name: normalizeRuntimeName(value) || "codex",
-                                runtime_kind: "codex",
-                                image: "",
-                                from_template: "",
-                                template_name: "",
-                              });
+                              onAgentDraftChange(
+                                draftWithRuntimeOptionsForRuntimeKind({
+                                  ...agentDraft,
+                                  bot_type: BOT_TYPE_NORMAL,
+                                  sandbox_enabled: false,
+                                  runtime_name: normalizeRuntimeName(value) || "codex",
+                                  runtime_kind: "codex",
+                                  image: "",
+                                  from_template: "",
+                                  template_name: "",
+                                }),
+                              );
                             }}
                             triggerProps={{ "aria-label": t("profileRuntimeKind") }}
                             options={[
@@ -531,6 +561,7 @@ export function AgentProfileModal({
                                 bootstrapConfig,
                                 managerAgent?.image || "",
                               );
+                              nextDraft = draftWithRuntimeOptionsForRuntimeKind(nextDraft);
                               onAgentDraftChange(nextDraft);
                               onAgentModelsReset();
                             }}
diff --git a/web/app/tests/components/AgentProfileModal.test.tsx b/web/app/tests/components/AgentProfileModal.test.tsx
index cccba6cf..ab7663e7 100644
--- a/web/app/tests/components/AgentProfileModal.test.tsx
+++ b/web/app/tests/components/AgentProfileModal.test.tsx
@@ -971,6 +971,85 @@ describe("AgentProfileModal", () => {
     expect(screen.queryByLabelText("MCP Servers")).not.toBeInTheDocument();
   });
 
+  it("drops MCP runtime options when OpenClaw drafts switch to unsupported runtimes", async () => {
+    const user = userEvent.setup();
+    const onAgentDraftChange = vi.fn();
+    const openclawDraft: AgentDraft = {
+      ...agentToDraft({ ...worker, runtime_kind: "openclaw_sandbox" }),
+      from_template: "",
+      model_provider_id: "api",
+      runtime_name: "openclaw",
+      runtime_kind: "openclaw_sandbox",
+      sandbox_enabled: true,
+      runtime_options: {
+        local_workspace_dir: "/tmp/project",
+        mcp: {
+          mcpServers: {
+            context7: {
+              command: "npx",
+            },
+          },
+        },
+      },
+    };
+
+    function TestModal() {
+      const [draft, setDraft] = useState<AgentDraft>(openclawDraft);
+      return (
+        <AgentProfileModal
+          t={t}
+          agentModalMode="create"
+          editingAgent={null}
+          agentDraft={draft}
+          locale="en"
+          onAgentDraftChange={(update) => {
+            onAgentDraftChange(update);
+            setDraft((current) => {
+              const next = typeof update === "function" ? update(current) : update;
+              return next ?? current;
+            });
+          }}
+          onAgentModelsReset={vi.fn()}
+          hubTemplates={[]}
+          bootstrapConfig={{
+            worker_runtime_choices: [
+              { name: "codex", sandbox_enabled: false, installed: true, label: "Codex CLI" },
+              { name: "openclaw", sandbox_enabled: true, installed: true, label: "OpenClaw" },
+              { name: "picoclaw", sandbox_enabled: true, installed: true, label: "PicoClaw" },
+            ],
+          }}
+          managerAgent={null}
+          agentModels={[]}
+          agentModelBusy={false}
+          authStatuses={{}}
+          authBusyProvider=""
+          agentCreateBotKind="worker"
+          agentCreateMode="custom"
+          onAgentCreateBotKindChange={vi.fn()}
+          notifierWebhookPublicOrigin="http://127.0.0.1:18080"
+          onProviderLogin={vi.fn()}
+          agentError=""
+          agentProgress={null}
+          agentBusy={false}
+          onClose={vi.fn()}
+          onSave={vi.fn()}
+        />
+      );
+    }
+
+    render(<TestModal />);
+
+    expect(screen.getByLabelText("MCP Servers")).toBeInTheDocument();
+
+    await user.click(screen.getByRole("combobox", { name: "Runtime" }));
+    await user.click(screen.getByRole("option", { name: "PicoClaw" }));
+
+    const nextDraft = onAgentDraftChange.mock.calls.at(-1)?.[0] as AgentDraft;
+    expect(nextDraft.runtime_kind).toBe("picoclaw_sandbox");
+    expect(nextDraft.runtime_options).toEqual({ local_workspace_dir: "/tmp/project" });
+    expect(screen.queryByLabelText("MCP Servers")).not.toBeInTheDocument();
+  });
+
   it("shows provider logos only in the provider field, not in the model field", () => {
     const { container } = render(
       <AgentProfileModal

From 9a01452208d3df950375ba6485e7319871c85374 Mon Sep 17 00:00:00 2001
From: GatewayJ <835269233@qq.com>
Date: Fri, 3 Jul 2026 23:31:48 +0800
Subject: [PATCH 6/7] docs(mcp): update openclaw mcp documentation

---
 docs/api.md                          | 33 ++++++++++++++
 docs/api.zh.md                       | 29 +++++++++++++
 docs/openclaw-mcp-restart-plan.zh.md | 64 ++++++++++++++++------------
 3 files changed, 98 insertions(+), 28 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 80714e88..76b46f58 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -290,6 +290,36 @@ Additional notes:
 - `field_mask` limits which fields are overwritten during replacement
 - `agent_profile.api_key` is write-only and will be redacted in reads
 
+OpenClaw agents can configure MCP servers through `runtime_options.mcp`. The
+CSGClaw API accepts `mcpServers` input and renders it into OpenClaw's native
+`mcp.servers` config:
+
+```json
+{
+  "name": "alice",
+  "runtime_kind": "openclaw_sandbox",
+  "runtime_options": {
+    "mcp": {
+      "mcpServers": {
+        "workspace-filesystem": {
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-filesystem",
+            "/home/node/.openclaw/workspace"
+          ]
+        }
+      }
+    }
+  },
+  "profile": "api.gpt-5.4"
+}
+```
+
+MCP commands run inside the OpenClaw sandbox, so filesystem server directory
+arguments must be paths visible inside the container. Non-OpenClaw runtimes
+reject `runtime_options.mcp`.
+
 ### `GET /api/v1/agents/{id}`
 
 Gets a single agent.
@@ -322,6 +352,9 @@ Example request body:
 Notes:
 
 - Omitted fields are left unchanged
+- `runtime_options` uses whole-object replacement when submitted; include the full merged `runtime_options` when editing MCP
+- `runtime_options.mcp: null` or a submitted `runtime_options` object without `mcp` clears MCP config
+- Updating MCP config on an OpenClaw agent recreates that agent runtime so the new `openclaw.json` takes effect
 - If `agent_profile.api_key` is sent empty, the server keeps the existing key
 - If `agent_profile.env` changes, `env_restart_required` may become `true` in the response
 
diff --git a/docs/api.zh.md b/docs/api.zh.md
index 39aa8eb8..199ac212 100644
--- a/docs/api.zh.md
+++ b/docs/api.zh.md
@@ -287,6 +287,32 @@ Participant 是 channel-scoped identity，用于房间、消息、mention、通
 - `field_mask` 用于替换时只覆盖指定字段
 - `agent_profile.api_key` 只在写入时使用，读取时会被脱敏
 
+OpenClaw agent 可通过 `runtime_options.mcp` 配置 MCP server。CSGClaw API 接收 `mcpServers` 输入，并在 OpenClaw runtime 配置中渲染为 `mcp.servers`：
+
+```json
+{
+  "name": "alice",
+  "runtime_kind": "openclaw_sandbox",
+  "runtime_options": {
+    "mcp": {
+      "mcpServers": {
+        "workspace-filesystem": {
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-filesystem",
+            "/home/node/.openclaw/workspace"
+          ]
+        }
+      }
+    }
+  },
+  "profile": "api.gpt-5.4"
+}
+```
+
+注意：MCP command 在 OpenClaw sandbox 内执行，filesystem server 的目录参数也必须是容器内可见路径。非 OpenClaw runtime 提交 `runtime_options.mcp` 会返回错误。
+
 ### `GET /api/v1/agents/{id}`
 
 获取单个 agent。
@@ -319,6 +345,9 @@ Participant 是 channel-scoped identity，用于房间、消息、mention、通
 说明：
 
 - 省略的字段不会修改
+- `runtime_options` 一旦提交就是整体替换；修改 MCP 时请提交合并后的完整 `runtime_options`
+- `runtime_options.mcp: null` 或提交不含 `mcp` 的 `runtime_options` 可清除 MCP 配置
+- OpenClaw agent 的 MCP 配置变更会触发该 agent runtime recreate，使新的 `openclaw.json` 生效
 - `agent_profile.api_key` 如果传空，服务端会保留原有密钥
 - 如果 `agent_profile.env` 发生变化，响应中的 `env_restart_required` 可能为 `true`
 
diff --git a/docs/openclaw-mcp-restart-plan.zh.md b/docs/openclaw-mcp-restart-plan.zh.md
index 60b36ad0..1e4869b8 100644
--- a/docs/openclaw-mcp-restart-plan.zh.md
+++ b/docs/openclaw-mcp-restart-plan.zh.md
@@ -1,12 +1,12 @@
-# OpenClaw Runtime MCP 配置接入方案
+# OpenClaw Runtime MCP 配置实现说明
 
-本文档约束 CSGClaw 为 OpenClaw agent 增加 MCP 能力的阶段一实现方案。阶段一只支持 `openclaw_sandbox`：MCP 配置先存入 agent 的 `runtime_options.mcp`，再由 OpenClaw runtime adapter 在 provision/recreate 阶段渲染为 OpenClaw 原生配置。非 OpenClaw runtime 暂不接收 `runtime_options.mcp`，后续 runtime 如需支持再单独接入。
+本文档记录 CSGClaw 为 OpenClaw agent 增加 MCP 能力的当前实现。当前阶段只支持 `openclaw_sandbox`：MCP 配置先存入 agent 的 `runtime_options.mcp`，再由 OpenClaw runtime adapter 在 provision/recreate 阶段渲染为 OpenClaw 原生配置。非 OpenClaw runtime 暂不接收 `runtime_options.mcp`，后续 runtime 如需支持再单独接入。
 
-阶段一沿用现有 gateway runtime 配置变更路径：MCP 配置保存后进入 CSGClaw 持久化状态，并立即触发现有 agent recreate 流程；recreate 成功后，新 runtime 进程加载最新 MCP 配置，`env_restart_required` 被清除。recreate 失败时，已保存的 MCP 配置保留在 agent state 中，`env_restart_required` 继续为 true，用户可通过现有“重建”动作重试。阶段一不依赖 runtime hot reload。
+当前实现沿用现有 gateway runtime 配置变更路径：MCP 配置保存后进入 CSGClaw 持久化状态，并立即触发现有 agent recreate 流程；recreate 成功后，新 runtime 进程加载最新 MCP 配置，`env_restart_required` 被清除。recreate 失败时，已保存的 MCP 配置保留在 agent state 中，`env_restart_required` 继续为 true，用户可通过现有“重建”动作重试。当前实现不依赖 runtime hot reload。
 
 ## 1. 目标与边界
 
-目标：
+已实现目标：
 
 - OpenClaw agent 使用现有 API 形态：`runtime_options.mcp`。
 - MCP 配置由 CSGClaw 管理，随 OpenClaw agent create/update 持久化。
@@ -15,17 +15,17 @@
 - OpenClaw adapter 负责把 `runtime_options.mcp` 转成 `openclaw.json` 中的 `mcp.servers`。
 - 非 OpenClaw runtime 收到 `runtime_options.mcp` 时返回明确错误，不静默忽略。
 
-非目标：
+当前未覆盖：
 
-- 阶段一不做 MCP marketplace、自动安装、连接测试或动态发现。
-- 阶段一不依赖任一 runtime 的 MCP hot reload 保证。
-- 阶段一不新增 CLI MCP 参数或 `agent update` 子命令。
-- 阶段一不抽象通用 MCP runtime policy，也不接入 PicoClaw/Codex。
+- 当前不做 MCP marketplace、自动安装、连接测试或动态发现。
+- 当前不依赖任一 runtime 的 MCP hot reload 保证。
+- 当前不新增 CLI MCP 参数或 `agent update` 子命令。
+- 当前不抽象通用 MCP runtime policy，也不接入 PicoClaw/Codex。
 - 暂不处理 MCP secret 脱敏体验；API 和前端沿用 `runtime_options` 的现有回显语义。
 
 ## 2. 当前 OpenClaw 配置注入路径
 
-OpenClaw 是第一条需要落地的 runtime adapter。CSGClaw 当前已经通过配置文件注入 OpenClaw 运行参数，路径如下：
+OpenClaw 是当前已接入 MCP 的 runtime adapter。CSGClaw 通过配置文件注入 OpenClaw 运行参数，路径如下：
 
 ```text
 Agent create/recreate provisioning
@@ -33,26 +33,26 @@ Agent create/recreate provisioning
   -> openclawsandbox.Runtime.Provision(...)
   -> openclawsandbox.EnsureConfig(...)
   -> renderConfig(defaults/openclaw-gateway.json + CSGClaw runtime inputs)
-  -> ~/.csgclaw/agents/<agent-name>/.openclaw/openclaw.json
+  -> ~/.csgclaw/agents/<agent-id>/.openclaw/openclaw.json
 ```
 
 `EnsureConfig` 会创建宿主机目录：
 
 ```text
-~/.csgclaw/agents/<agent-name>/.openclaw/
+~/.csgclaw/agents/<agent-id>/.openclaw/
 ```
 
 并写入：
 
 ```text
-~/.csgclaw/agents/<agent-name>/.openclaw/openclaw.json
-~/.csgclaw/agents/<agent-name>/.openclaw/exec-approvals.json
+~/.csgclaw/agents/<agent-id>/.openclaw/openclaw.json
+~/.csgclaw/agents/<agent-id>/.openclaw/exec-approvals.json
 ```
 
 OpenClaw sandbox 创建时，CSGClaw 会把该目录挂载进容器：
 
 ```text
-宿主机: ~/.csgclaw/agents/<agent-name>/.openclaw
+宿主机: ~/.csgclaw/agents/<agent-id>/.openclaw
 容器内: /home/node/.openclaw
 ```
 
@@ -74,7 +74,7 @@ node /app/openclaw.mjs gateway --allow-unconfigured --bind lan --port 18789
 /home/node/.openclaw/openclaw.json
 ```
 
-结论：OpenClaw MCP adapter 不需要写 workspace 文件，也不需要通过 task wrapper 或 `OPENCLAW_CONFIG_PATH` 指向临时文件；它应该继续维护每个 agent 的长期 OpenClaw 配置根目录，并在 provision/recreate 时把 `runtime_options.mcp` 渲染进 `openclaw.json`。
+结论：OpenClaw MCP adapter 不需要写 workspace 文件，也不需要通过 task wrapper 或 `OPENCLAW_CONFIG_PATH` 指向临时文件；它维护每个 agent 的长期 OpenClaw 配置根目录，并在 provision/recreate 时把 `runtime_options.mcp` 渲染进 `openclaw.json`。
 
 ## 3. MCP 配置形态
 
@@ -142,12 +142,13 @@ OpenClaw 约束：
 - `runtime_options.mcp.mcpServers` 渲染为 OpenClaw `mcp.servers`。
 - 不支持直接提交完整 OpenClaw `mcp` 对象，避免用户把 OpenClaw 其它 `mcp.*` 设置和 server 列表混在一起造成合并语义不清。
 - MCP command 在 OpenClaw sandbox 内执行，不在宿主机执行；需要的二进制必须在镜像内存在，或通过 workspace/projects 等已有挂载路径可访问。
+- filesystem MCP server 的目录参数也是容器内可见路径，例如 `/home/node/.openclaw/workspace`；直接填写宿主机路径不会自动挂载进容器。
 
 ## 4. 后端设计
 
 ### 4.1 数据模型
 
-不要新增 top-level `Agent.MCPConfig`。阶段一把 MCP 配置放在 `Agent.RuntimeOptions["mcp"]`，保持和已有 runtime option 架构一致。
+不要新增 top-level `Agent.MCPConfig`。当前实现把 MCP 配置放在 `Agent.RuntimeOptions["mcp"]`，保持和已有 runtime option 架构一致。
 
 需要同步处理：
 
@@ -202,7 +203,7 @@ runtime_options.mcp
   -> openclawsandbox.EnsureConfig(...)
   -> renderConfig(...)
   -> updateOpenClawMCP(...)
-  -> ~/.csgclaw/agents/<agent-name>/.openclaw/openclaw.json
+  -> ~/.csgclaw/agents/<agent-id>/.openclaw/openclaw.json
 ```
 
 `openclawsandbox.EnsureConfig` 新增 runtime options 参数后，`renderConfig` 在现有步骤之后追加：
@@ -217,7 +218,7 @@ updateOpenClawMCP
 
 ### 4.3 OpenClaw adapter 策略
 
-阶段一复用现有 `RuntimeConfigController` 扩展点，不新增 MCP 专用跨 runtime 抽象。OpenClaw runtime controller 负责：
+当前实现复用现有 `RuntimeConfigController` 扩展点，不新增 MCP 专用跨 runtime 抽象。OpenClaw runtime controller 负责：
 
 - 校验 `runtime_options.mcp`。
 - 判断 `runtime_options.mcp` 变更是否需要 recreate。
@@ -231,7 +232,7 @@ OpenClaw adapter：
 
 非 OpenClaw runtime：
 
-- 阶段一不支持 `runtime_options.mcp`。
+- 当前不支持 `runtime_options.mcp`。
 - create/update/start 等需要校验 runtime config 的路径遇到 `runtime_options.mcp` 时返回明确错误。
 
 ### 4.4 保存与自动重建
@@ -417,9 +418,9 @@ MCP 修改保存后，后端负责自动重建 runtime；前端不再提供专
 
 如果 agent 正在运行，保存 MCP 配置会触发 runtime recreate。当前路径会重建该 agent 的 runtime 进程，不依赖 hot reload。
 
-## 7. 验证计划
+## 7. 验证与测试
 
-后端测试：
+后端覆盖：
 
 - `runtime_options.mcp` 的缺失、`null`、空对象、空 `mcpServers`、非空 `mcpServers` 语义正确。
 - 非 object server entry 报错。
@@ -434,7 +435,7 @@ MCP 修改保存后，后端负责自动重建 runtime；前端不再提供专
 - 非 OpenClaw runtime 收到 `runtime_options.mcp` 时返回明确错误。
 - `syncGatewayHostConfig` 重写 OpenClaw host config 时不会丢失 MCP 配置。
 
-前端测试：
+前端覆盖：
 
 - `AgentProfileModal` 能编辑 `runtime_options.mcp`。
 - `AgentDetailPane` 能显示和编辑 `runtime_options.mcp`。
@@ -444,17 +445,24 @@ MCP 修改保存后，后端负责自动重建 runtime；前端不再提供专
 - 保存已有 agent 的 MCP 配置时只调用 update；recreate 由后端自动完成。
 - update 失败后刷新 agent，并能展示现有 recreate required 状态。
 
-手工验证：
+可手工验证：
 
 1. 创建 agent，带一个 stdio MCP server。
-2. 对 OpenClaw agent，检查宿主机 `~/.csgclaw/agents/<agent>/.openclaw/openclaw.json` 包含 `mcp.servers`。
+2. 对 OpenClaw agent，检查宿主机 `~/.csgclaw/agents/<agent-id>/.openclaw/openclaw.json` 包含 `mcp.servers`。
 3. 启动 agent 后确认 runtime 能看到 MCP tool。
 4. 修改 MCP 配置并保存，确认后端自动重建 runtime。
 5. 自动重建成功后确认新配置生效，`env_restart_required` 清除。
 6. 模拟 recreate 失败，确认已保存 MCP 配置保留，`env_restart_required` 为 true，现有重建 action 可恢复。
-7. MCP 配置生效后修改 profile，确认 host config sync 不会丢失 `mcp.servers`，并能看到诊断日志。
+7. MCP 配置生效后修改 profile，确认 host config sync 不会丢失 `mcp.servers`。
 
-## 8. 实施顺序
+本 PR 使用过的定向验证命令：
+
+```bash
+go test ./internal/runtime/openclawsandbox ./internal/agent -run 'Test(RenderAgentOpenClawConfig.*MCP|UpdateOpenClawMCP|UpdateMCPRuntimeOptions|CreateMCPRuntimeOptions|Replace.*MCP|UpdateFieldMaskClearsRuntimeOptions)'
+pnpm exec vitest run tests/models/agents.test.ts tests/components/AgentProfileModal.test.tsx tests/components/AgentActions.test.tsx
+```
+
+## 8. 已完成改动
 
 1. 增加 `runtime_options.mcp` parser/validator 和共享 helper。
 2. 扩展 provision request，把 `Agent.RuntimeOptions` 传到 runtime provision 边界。
@@ -463,4 +471,4 @@ MCP 修改保存后，后端负责自动重建 runtime；前端不再提供专
 5. 让 `syncGatewayHostConfig` 重写 OpenClaw host config 时也传入并渲染当前 `Agent.RuntimeOptions`，避免 profile 热同步丢失 MCP。
 6. 拒绝非 OpenClaw runtime 的 `runtime_options.mcp`。
 7. 接入前端 Agent 创建/详情页 MCP runtime options UI。
-8. 补充 `docs/api.zh.md` 和相关英文 API 文档。
+8. 补充 `docs/api.zh.md` 和 `docs/api.md` 的 MCP runtime options 示例。

From 2600e4a4b1e595f8813be14752475f56f0c1cd4a Mon Sep 17 00:00:00 2001
From: GatewayJ <835269233@qq.com>
Date: Mon, 6 Jul 2026 23:33:18 +0800
Subject: [PATCH 7/7] feat(agent): add shared MCP config support

---
 docs/api.md                                   |  47 +-
 docs/api.zh.md                                |  37 +-
 docs/openclaw-mcp-restart-plan.zh.md          | 527 ++++++------------
 internal/agent/model.go                       | 117 ++++
 internal/agent/runtime_record.go              |   3 +-
 internal/agent/service.go                     |  61 +-
 internal/agent/service_profiles.go            | 178 +++++-
 internal/agent/service_test.go                | 271 ++++++---
 internal/agent/store.go                       |  12 +
 internal/api/handler.go                       |   8 +
 internal/api/handler_test.go                  | 453 +++++++++++++++
 internal/apitypes/agent.go                    |  56 +-
 internal/apitypes/types.go                    |   1 +
 internal/app/runtimewiring/codex.go           |   1 +
 internal/participant/store.go                 |   3 +
 internal/runtime/codex/config_controller.go   |  20 +
 internal/runtime/codex/runtime.go             |  13 +-
 internal/runtime/codex/runtime_config.go      | 124 ++++-
 internal/runtime/codex/runtime_test.go        |  41 +-
 internal/runtime/mcp_config.go                | 307 ++++++++++
 internal/runtime/openclawsandbox/config.go    |  49 +-
 .../openclawsandbox/config_controller.go      |  17 +-
 internal/runtime/openclawsandbox/mcp.go       | 270 +--------
 .../runtime/openclawsandbox/provision_test.go |   8 +-
 internal/runtime/openclawsandbox/runtime.go   |   2 +-
 internal/runtime/picoclawsandbox/config.go    |  38 +-
 .../picoclawsandbox/config_controller.go      |  21 +
 .../runtime/picoclawsandbox/config_test.go    |  90 +++
 internal/runtime/picoclawsandbox/runtime.go   |   2 +-
 internal/runtime/provision.go                 |   1 +
 web/app/src/api/agents.ts                     |   2 +
 ...imeOptionsPanel.tsx => MCPConfigPanel.tsx} |  32 +-
 .../ProfileControls/ProfileControls.css       |  16 +-
 .../business/ProfileControls/index.ts         |   2 +-
 .../src/hooks/workspace/useAgentController.ts |  49 +-
 web/app/src/models/agents.ts                  |  56 +-
 .../AgentDetailPane/AgentDetailPane.tsx       | 199 ++++---
 .../WorkspaceModals/AgentProfileModal.tsx     |  28 +-
 web/app/src/shared/i18n/messages.ts           | 122 +---
 .../tests/components/AgentActions.test.tsx    | 108 +++-
 .../components/AgentProfileModal.test.tsx     |  46 +-
 web/app/tests/models/agents.test.ts           |  49 +-
 42 files changed, 2371 insertions(+), 1116 deletions(-)
 create mode 100644 internal/runtime/mcp_config.go
 create mode 100644 internal/runtime/picoclawsandbox/config_controller.go
 rename web/app/src/components/business/ProfileControls/{MCPRuntimeOptionsPanel.tsx => MCPConfigPanel.tsx} (71%)

diff --git a/docs/api.md b/docs/api.md
index 76b46f58..8380cccf 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -290,25 +290,24 @@ Additional notes:
 - `field_mask` limits which fields are overwritten during replacement
 - `agent_profile.api_key` is write-only and will be redacted in reads
 
-OpenClaw agents can configure MCP servers through `runtime_options.mcp`. The
-CSGClaw API accepts `mcpServers` input and renders it into OpenClaw's native
-`mcp.servers` config:
+OpenClaw, PicoClaw, and Codex CLI agents can configure MCP servers through the
+top-level `mcp_config` field. The API accepts the same `mcpServers` object for
+all supported runtimes and each runtime adapter renders it into its native
+configuration format:
 
 ```json
 {
   "name": "alice",
   "runtime_kind": "openclaw_sandbox",
-  "runtime_options": {
-    "mcp": {
-      "mcpServers": {
-        "workspace-filesystem": {
-          "command": "npx",
-          "args": [
-            "-y",
-            "@modelcontextprotocol/server-filesystem",
-            "/home/node/.openclaw/workspace"
-          ]
-        }
+  "mcp_config": {
+    "mcpServers": {
+      "workspace-filesystem": {
+        "command": "npx",
+        "args": [
+          "-y",
+          "@modelcontextprotocol/server-filesystem",
+          "/home/node/.openclaw/workspace"
+        ]
       }
     }
   },
@@ -316,9 +315,16 @@ CSGClaw API accepts `mcpServers` input and renders it into OpenClaw's native
 }
 ```
 
-MCP commands run inside the OpenClaw sandbox, so filesystem server directory
-arguments must be paths visible inside the container. Non-OpenClaw runtimes
-reject `runtime_options.mcp`.
+Runtime adapters map this shared input as follows:
+
+- OpenClaw: `mcp_config.mcpServers` -> `openclaw.json` `mcp.servers`
+- PicoClaw: `mcp_config.mcpServers` -> PicoClaw config `tools.mcp.servers`
+- Codex CLI: `mcp_config.mcpServers` -> managed `[mcp_servers."<name>"]` blocks in the isolated Codex home `config.toml`
+
+MCP commands run inside the target runtime environment, so filesystem server
+directory arguments must be paths visible to that runtime. Existing clients
+that still send legacy `runtime_options.mcp` are normalized into `mcp_config`;
+new clients should use `mcp_config`.
 
 ### `GET /api/v1/agents/{id}`
 
@@ -336,6 +342,7 @@ Supported fields:
 - `description`
 - `image`
 - `runtime_options`
+- `mcp_config`
 - `agent_profile`
 
 Example request body:
@@ -352,9 +359,9 @@ Example request body:
 Notes:
 
 - Omitted fields are left unchanged
-- `runtime_options` uses whole-object replacement when submitted; include the full merged `runtime_options` when editing MCP
-- `runtime_options.mcp: null` or a submitted `runtime_options` object without `mcp` clears MCP config
-- Updating MCP config on an OpenClaw agent recreates that agent runtime so the new `openclaw.json` takes effect
+- `runtime_options` uses whole-object replacement when submitted
+- `mcp_config` uses whole-object replacement when submitted; send `null` to clear CSGClaw-managed MCP config
+- Updating MCP config on OpenClaw, PicoClaw, or Codex CLI agents may recreate that agent runtime so the native config takes effect
 - If `agent_profile.api_key` is sent empty, the server keeps the existing key
 - If `agent_profile.env` changes, `env_restart_required` may become `true` in the response
 
diff --git a/docs/api.zh.md b/docs/api.zh.md
index 199ac212..98412148 100644
--- a/docs/api.zh.md
+++ b/docs/api.zh.md
@@ -287,23 +287,21 @@ Participant 是 channel-scoped identity，用于房间、消息、mention、通
 - `field_mask` 用于替换时只覆盖指定字段
 - `agent_profile.api_key` 只在写入时使用，读取时会被脱敏
 
-OpenClaw agent 可通过 `runtime_options.mcp` 配置 MCP server。CSGClaw API 接收 `mcpServers` 输入，并在 OpenClaw runtime 配置中渲染为 `mcp.servers`：
+OpenClaw、PicoClaw 和 Codex CLI agent 可通过顶层 `mcp_config` 字段配置 MCP server。CSGClaw API 对所有已支持 runtime 接收一致的 `mcpServers` 输入，再由各 runtime adapter 渲染为对应的原生配置：
 
 ```json
 {
   "name": "alice",
   "runtime_kind": "openclaw_sandbox",
-  "runtime_options": {
-    "mcp": {
-      "mcpServers": {
-        "workspace-filesystem": {
-          "command": "npx",
-          "args": [
-            "-y",
-            "@modelcontextprotocol/server-filesystem",
-            "/home/node/.openclaw/workspace"
-          ]
-        }
+  "mcp_config": {
+    "mcpServers": {
+      "workspace-filesystem": {
+        "command": "npx",
+        "args": [
+          "-y",
+          "@modelcontextprotocol/server-filesystem",
+          "/home/node/.openclaw/workspace"
+        ]
       }
     }
   },
@@ -311,7 +309,13 @@ OpenClaw agent 可通过 `runtime_options.mcp` 配置 MCP server。CSGClaw API 
 }
 ```
 
-注意：MCP command 在 OpenClaw sandbox 内执行，filesystem server 的目录参数也必须是容器内可见路径。非 OpenClaw runtime 提交 `runtime_options.mcp` 会返回错误。
+各 runtime adapter 的映射关系：
+
+- OpenClaw：`mcp_config.mcpServers` -> `openclaw.json` 的 `mcp.servers`
+- PicoClaw：`mcp_config.mcpServers` -> PicoClaw 配置的 `tools.mcp.servers`
+- Codex CLI：`mcp_config.mcpServers` -> 隔离 Codex home `config.toml` 中由 CSGClaw 管理的 `[mcp_servers."<name>"]` 块
+
+注意：MCP command 在目标 runtime 环境内执行，filesystem server 的目录参数也必须是该 runtime 可见路径。旧客户端继续提交 `runtime_options.mcp` 时会被服务端迁移为 `mcp_config`；新客户端应直接使用 `mcp_config`。
 
 ### `GET /api/v1/agents/{id}`
 
@@ -329,6 +333,7 @@ OpenClaw agent 可通过 `runtime_options.mcp` 配置 MCP server。CSGClaw API 
 - `description`
 - `image`
 - `runtime_options`
+- `mcp_config`
 - `agent_profile`
 
 请求体示例：
@@ -345,9 +350,9 @@ OpenClaw agent 可通过 `runtime_options.mcp` 配置 MCP server。CSGClaw API 
 说明：
 
 - 省略的字段不会修改
-- `runtime_options` 一旦提交就是整体替换；修改 MCP 时请提交合并后的完整 `runtime_options`
-- `runtime_options.mcp: null` 或提交不含 `mcp` 的 `runtime_options` 可清除 MCP 配置
-- OpenClaw agent 的 MCP 配置变更会触发该 agent runtime recreate，使新的 `openclaw.json` 生效
+- `runtime_options` 一旦提交就是整体替换
+- `mcp_config` 一旦提交就是整体替换；传 `null` 可清除 CSGClaw 托管的 MCP 配置
+- OpenClaw、PicoClaw 或 Codex CLI agent 的 MCP 配置变更可能触发该 agent runtime recreate，使原生配置生效
 - `agent_profile.api_key` 如果传空，服务端会保留原有密钥
 - 如果 `agent_profile.env` 发生变化，响应中的 `env_restart_required` 可能为 `true`
 
diff --git a/docs/openclaw-mcp-restart-plan.zh.md b/docs/openclaw-mcp-restart-plan.zh.md
index 1e4869b8..ceb4cb3a 100644
--- a/docs/openclaw-mcp-restart-plan.zh.md
+++ b/docs/openclaw-mcp-restart-plan.zh.md
@@ -1,287 +1,141 @@
-# OpenClaw Runtime MCP 配置实现说明
+# MCP 配置控制器实现说明
 
-本文档记录 CSGClaw 为 OpenClaw agent 增加 MCP 能力的当前实现。当前阶段只支持 `openclaw_sandbox`：MCP 配置先存入 agent 的 `runtime_options.mcp`，再由 OpenClaw runtime adapter 在 provision/recreate 阶段渲染为 OpenClaw 原生配置。非 OpenClaw runtime 暂不接收 `runtime_options.mcp`，后续 runtime 如需支持再单独接入。
-
-当前实现沿用现有 gateway runtime 配置变更路径：MCP 配置保存后进入 CSGClaw 持久化状态，并立即触发现有 agent recreate 流程；recreate 成功后，新 runtime 进程加载最新 MCP 配置，`env_restart_required` 被清除。recreate 失败时，已保存的 MCP 配置保留在 agent state 中，`env_restart_required` 继续为 true，用户可通过现有“重建”动作重试。当前实现不依赖 runtime hot reload。
+本文档记录当前分支对 CSGClaw MCP 配置接入的实现。旧方案把 OpenClaw 的 MCP 配置放在 `runtime_options.mcp`；当前实现已调整为独立的顶层 `mcp_config`，并在 runtime 接口层增加 `MCPConfigController`，由各 runtime adapter 负责把统一输入转换为自己的原生配置格式。
 
 ## 1. 目标与边界
 
 已实现目标：
 
-- OpenClaw agent 使用现有 API 形态：`runtime_options.mcp`。
-- MCP 配置由 CSGClaw 管理，随 OpenClaw agent create/update 持久化。
-- 创建 agent 时，MCP 配置随首次 provision 生效。
-- 修改已有 agent 的 MCP 配置后，后端通过现有 agent recreate 流程自动生效。
-- OpenClaw adapter 负责把 `runtime_options.mcp` 转成 `openclaw.json` 中的 `mcp.servers`。
-- 非 OpenClaw runtime 收到 `runtime_options.mcp` 时返回明确错误，不静默忽略。
+- API、持久化和前端使用统一的顶层 `mcp_config` 字段。
+- `mcp_config` 的输入形态固定为 `{"mcpServers": {...}}`。
+- runtime 层新增 `MCPConfigController`，与现有 start/stop/provision 和 runtime config controller 分离。
+- OpenClaw、PicoClaw、Codex CLI 三类 agent 都接入 MCP server 配置。
+- 前端创建、编辑和详情页使用同一份 MCP Server JSON 配置形态。
+- 旧客户端提交的 `runtime_options.mcp` 会迁移到 `mcp_config`，并从 `runtime_options` 中剥离。
 
 当前未覆盖：
 
-- 当前不做 MCP marketplace、自动安装、连接测试或动态发现。
-- 当前不依赖任一 runtime 的 MCP hot reload 保证。
-- 当前不新增 CLI MCP 参数或 `agent update` 子命令。
-- 当前不抽象通用 MCP runtime policy，也不接入 PicoClaw/Codex。
-- 暂不处理 MCP secret 脱敏体验；API 和前端沿用 `runtime_options` 的现有回显语义。
-
-## 2. 当前 OpenClaw 配置注入路径
-
-OpenClaw 是当前已接入 MCP 的 runtime adapter。CSGClaw 通过配置文件注入 OpenClaw 运行参数，路径如下：
-
-```text
-Agent create/recreate provisioning
-  -> internal/agent.Service.provisionRuntime(...)
-  -> openclawsandbox.Runtime.Provision(...)
-  -> openclawsandbox.EnsureConfig(...)
-  -> renderConfig(defaults/openclaw-gateway.json + CSGClaw runtime inputs)
-  -> ~/.csgclaw/agents/<agent-id>/.openclaw/openclaw.json
-```
-
-`EnsureConfig` 会创建宿主机目录：
-
-```text
-~/.csgclaw/agents/<agent-id>/.openclaw/
-```
-
-并写入：
-
-```text
-~/.csgclaw/agents/<agent-id>/.openclaw/openclaw.json
-~/.csgclaw/agents/<agent-id>/.openclaw/exec-approvals.json
-```
-
-OpenClaw sandbox 创建时，CSGClaw 会把该目录挂载进容器：
-
-```text
-宿主机: ~/.csgclaw/agents/<agent-id>/.openclaw
-容器内: /home/node/.openclaw
-```
-
-同时设置：
+- 不做 MCP marketplace、自动安装、连接测试或动态发现。
+- 不承诺 runtime hot reload；需要重启/重建时仍走现有 runtime recreate 路径。
+- 暂不做 MCP secret 脱敏体验，`mcp_config` 仍按普通 JSON 配置回显。
 
-```text
-HOME=/home/node
-```
-
-OpenClaw gateway 启动命令为：
-
-```bash
-node /app/openclaw.mjs gateway --allow-unconfigured --bind lan --port 18789
-```
+## 2. 统一配置形态
 
-因此 OpenClaw 读取的是默认路径：
-
-```text
-/home/node/.openclaw/openclaw.json
-```
-
-结论：OpenClaw MCP adapter 不需要写 workspace 文件，也不需要通过 task wrapper 或 `OPENCLAW_CONFIG_PATH` 指向临时文件；它维护每个 agent 的长期 OpenClaw 配置根目录，并在 provision/recreate 时把 `runtime_options.mcp` 渲染进 `openclaw.json`。
-
-## 3. MCP 配置形态
-
-CSGClaw API 接收与 Multica 一致的 MCP server 配置输入形态，但位置放在 `runtime_options.mcp`。这里的 `mcpServers` 是配置包裹形态，不是 MCP 标准协议的 JSON-RPC 消息格式；真正的 MCP 协议交互由 OpenClaw runtime 和对应 MCP server 处理。
+API 输入：
 
 ```json
 {
   "runtime_kind": "openclaw_sandbox",
-  "runtime_options": {
-    "mcp": {
-      "mcpServers": {
-        "context7": {
-          "command": "uvx",
-          "args": ["context7-mcp"],
-          "env": {
-            "CONTEXT7_API_KEY": "secret"
-          }
-        },
-        "remote-search": {
-          "url": "https://mcp.example.com/mcp",
-          "transport": "streamable-http",
-          "headers": {
-            "Authorization": "Bearer secret"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-OpenClaw adapter 渲染到 OpenClaw 原生配置：
-
-```json
-{
-  "mcp": {
-    "servers": {
+  "mcp_config": {
+    "mcpServers": {
       "context7": {
         "command": "uvx",
         "args": ["context7-mcp"],
         "env": {
           "CONTEXT7_API_KEY": "secret"
         }
+      },
+      "remote-search": {
+        "url": "https://mcp.example.com/mcp",
+        "transport": "streamable-http",
+        "headers": {
+          "Authorization": "Bearer secret"
+        }
       }
     }
   }
 }
 ```
 
-输入约束：
-
-- 持久化后的 `runtime_options.mcp` 缺失表示该 agent 没有 CSGClaw 管理的 MCP 配置。
-- API update 的字段缺失语义以第 5.2 节为准：`runtime_options` 整体缺失才表示不修改；`runtime_options` 一旦提交就是整体替换。
-- `runtime_options.mcp: null` 表示清除 CSGClaw 管理的 MCP 配置。
-- `runtime_options.mcp: {}` 或 `{"mcpServers": {}}` 表示显式托管空集合。
-- 非空 `mcpServers` 表示使用 CSGClaw 托管集合。
-- 每个 server entry 必须是 JSON object。
-- 每个 server entry 必须声明 `command` 或 `url`。
-- stdio server 使用 `command`、`args`、`env`。
-- HTTP/SSE server 使用 `url`，并直接使用目标 runtime 识别的 `transport`。
-- server 名称排序后写入，保证生成配置稳定。
-
-OpenClaw 约束：
-
-- `runtime_options.mcp.mcpServers` 渲染为 OpenClaw `mcp.servers`。
-- 不支持直接提交完整 OpenClaw `mcp` 对象，避免用户把 OpenClaw 其它 `mcp.*` 设置和 server 列表混在一起造成合并语义不清。
-- MCP command 在 OpenClaw sandbox 内执行，不在宿主机执行；需要的二进制必须在镜像内存在，或通过 workspace/projects 等已有挂载路径可访问。
-- filesystem MCP server 的目录参数也是容器内可见路径，例如 `/home/node/.openclaw/workspace`；直接填写宿主机路径不会自动挂载进容器。
-
-## 4. 后端设计
-
-### 4.1 数据模型
+语义：
 
-不要新增 top-level `Agent.MCPConfig`。当前实现把 MCP 配置放在 `Agent.RuntimeOptions["mcp"]`，保持和已有 runtime option 架构一致。
+- `mcp_config` 字段缺失：不修改已有 MCP 配置。
+- `mcp_config: null`：清除 CSGClaw 托管 MCP 配置。
+- `mcp_config: {}` 或 `{"mcpServers": {}}`：显式托管空集合。
+- 非空 `mcpServers`：使用 CSGClaw 托管 server 集合。
+- 顶层仅支持 `mcpServers`，避免混入 runtime 原生 MCP 配置导致合并语义不清。
 
-需要同步处理：
+校验规则：
 
-- `agent.CreateAgentSpec.RuntimeOptions`
-- `agent.UpdateRequest.RuntimeOptions`
-- `apitypes.CreateAgentRequest.RuntimeOptions`
-- participant agent binding 中的 create payload
-- Web `AgentLike.runtime_options`
-- runtime option 保存/合并逻辑
+- `mcpServers` 必须是 object。
+- server 名称去空白后不能为空，重复名称报错。
+- 每个 server entry 必须是 object。
+- 每个 server entry 必须声明 `command` 或 `url`。
+- `args` 必须是 string array。
+- `env`、`headers` 必须是 string map。
+- `transport` 必须是 string。
 
-注意：当前 `PATCH /api/v1/agents/{id}` 的 `runtime_options` 是整体替换语义。前端保存 MCP 时必须基于当前 agent 的 `runtime_options` 合并后提交，避免只提交 `{"mcp": ...}` 时覆盖其它 runtime option，例如 Codex 的 `local_workspace_dir`。
+## 3. Runtime 接口
 
-实现时保留现有 runtime option 边界，只增加最小共享常量和 OpenClaw 内部解析逻辑：
+共享接口定义在 `internal/runtime/mcp_config.go`：
 
 ```go
-const RuntimeOptionMCPKey = "mcp"
+type MCPConfigController interface {
+    ValidateMCPConfig(ctx context.Context, current MCPConfigSnapshot) error
+    MCPConfigRestartRequired(change MCPConfigChange) (bool, error)
+    ReconcileMCPConfig(ctx context.Context, h Handle, change MCPConfigChange) error
+}
 ```
 
-OpenClaw 解析状态至少区分：
+它的职责：
 
-- absent
-- cleared/null
-- empty managed set
-- managed server set
+- 校验当前 runtime 是否支持 `mcp_config` 以及配置是否符合该 runtime 的约束。
+- 判断 MCP 配置变更是否需要 runtime recreate。
+- 对无需 recreate 的 runtime，或需要即时重写本地配置的 runtime，执行 reconcile。
 
-### 4.2 ProvisionRequest 传递
-
-因为 MCP 已放入 `runtime_options`，provision 边界应传递通用 runtime options，而不是新增 MCP 专用字段：
+`ProvisionRequest` 也新增了独立字段：
 
 ```go
 type ProvisionRequest struct {
-    RuntimeOptions map[string]any
+    MCPConfig map[string]any
 }
 ```
 
-调用链：
+这样 MCP 不再通过通用 `RuntimeOptions` 传递，runtime options 和 MCP 配置的生命周期可以独立演进。
 
-```text
-Agent.RuntimeOptions["mcp"]
-  -> Service.provisionRuntimeForAgent(...)
-  -> agentruntime.ProvisionRequest.RuntimeOptions
-  -> concrete runtime Provision(...)
-  -> OpenClaw MCP adapter
-  -> native runtime config
-```
+## 4. Runtime Adapter 映射
 
-OpenClaw adapter 的调用链：
+### OpenClaw
 
-```text
-runtime_options.mcp
-  -> openclawsandbox.Runtime.Provision(...)
-  -> openclawsandbox.EnsureConfig(...)
-  -> renderConfig(...)
-  -> updateOpenClawMCP(...)
-  -> ~/.csgclaw/agents/<agent-id>/.openclaw/openclaw.json
+OpenClaw 接收统一 `mcp_config.mcpServers`，渲染到 OpenClaw 原生配置：
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "context7": {
+        "command": "uvx",
+        "args": ["context7-mcp"]
+      }
+    }
+  }
+}
 ```
 
-`openclawsandbox.EnsureConfig` 新增 runtime options 参数后，`renderConfig` 在现有步骤之后追加：
+OpenClaw 配置文件路径仍是：
 
 ```text
-updateOpenClawModelProvider
-updateOpenClawCsgclawChannel
-updateOpenClawFeishuChannel
-updateOpenClawGatewayAuth
-updateOpenClawMCP
+~/.csgclaw/agents/<agent-id>/.openclaw/openclaw.json
 ```
 
-### 4.3 OpenClaw adapter 策略
-
-当前实现复用现有 `RuntimeConfigController` 扩展点，不新增 MCP 专用跨 runtime 抽象。OpenClaw runtime controller 负责：
-
-- 校验 `runtime_options.mcp`。
-- 判断 `runtime_options.mcp` 变更是否需要 recreate。
-- 在 `Provision` 期间把 MCP 配置渲染进 `openclaw.json`。
-
-OpenClaw adapter：
-
-- 渲染到 `openclaw.json` 的 `mcp.servers`。
-- `null` 清除 CSGClaw 管理的 `mcp.servers`。
-- `{}` 或空 `mcpServers` 写入 `mcp.servers: {}`。
-
-非 OpenClaw runtime：
-
-- 当前不支持 `runtime_options.mcp`。
-- create/update/start 等需要校验 runtime config 的路径遇到 `runtime_options.mcp` 时返回明确错误。
-
-### 4.4 保存与自动重建
-
-保存已有 agent 的 MCP 配置时：
-
-1. 合并并校验新的 `runtime_options`。
-2. 校验 `runtime_options.mcp` 的 JSON 和 server entry。
-3. 持久化到 agent state。
-4. 如果 `runtime_options.mcp` 发生变化，设置 `agent_profile.env_restart_required = true`，作为持久化重建标记。
-5. 对支持 MCP 渲染的 gateway runtime，立即调用现有 `Service.Recreate`。
-6. `Recreate` 成功后，新 runtime 进程加载最新 MCP 配置，`persistRecreatedAgent` 清除 `env_restart_required`。
-7. `Recreate` 失败时，返回错误；已保存 MCP 配置保留，`env_restart_required` 保留为 true，用户可通过现有 recreate action 重试。
-8. 不依赖 runtime hot reload。
+sandbox 内读取路径：
 
-生效方式：
-
-1. 用户保存 MCP 配置。
-2. 后端持久化最新 `Agent.RuntimeOptions`。
-3. 后端调用现有 `Service.Recreate`。
-4. `Service.Recreate` 删除旧 runtime handle。
-5. `Provision` 使用最新 `Agent.RuntimeOptions` 重新生成 runtime 原生配置。
-6. 新 runtime 进程启动并加载 MCP。
-7. `persistRecreatedAgent` 成功后清除 `env_restart_required`。
-
-这不是重启 CSGClaw server，而是重建该 agent 的 runtime 进程。
-
-### 4.5 与现有 profile 热同步路径的关系
-
-当前 gateway runtime 的 profile runtime input 变化时，CSGClaw 已有 `syncGatewayHostConfig` 路径会重写 host config。因为 OpenClaw 配置是从 embedded defaults 重新渲染，而不是读旧文件做增量修改，所以该路径也必须接收当前 agent 的 `runtime_options`，并在重写 host config 时保留/渲染 `runtime_options.mcp`。否则 profile 热同步会把已经生效的 `mcp.servers` 覆盖掉。
-
-实现要求：
-
-- 保持现有 `syncGatewayHostConfig` 的 profile 热同步能力。
-- `syncGatewayHostConfig` 调用 OpenClaw `EnsureConfig` 时必须传入当前 `Agent.RuntimeOptions`。
-- `EnsureConfig`/`renderConfig` 每次写 host config 都应根据当前 `runtime_options.mcp` 渲染 runtime 原生 MCP 配置。
+```text
+/home/node/.openclaw/openclaw.json
+```
 
-## 5. API 设计
+OpenClaw adapter 使用共享 JSON helper 更新 `mcp.servers`。MCP command 在 OpenClaw sandbox 内执行，filesystem server 参数必须是容器内可见路径。
 
-### 5.1 Create Agent
+### PicoClaw
 
-`POST /api/v1/agents` 和 participant agent binding create payload 使用现有 `runtime_options`：
+PicoClaw 接收同样的 `mcp_config.mcpServers`，渲染到 PicoClaw config：
 
 ```json
 {
-  "runtime_kind": "openclaw_sandbox",
-  "runtime_options": {
+  "tools": {
     "mcp": {
-      "mcpServers": {
+      "enabled": true,
+      "servers": {
         "context7": {
           "command": "uvx",
           "args": ["context7-mcp"]
@@ -292,183 +146,158 @@ OpenClaw adapter：
 }
 ```
 
-创建时 MCP 配置直接参与 provision，agent 首次启动后生效，不需要额外 recreate。
-
-### 5.2 Update Agent
-
-`PATCH /api/v1/agents/{id}` 继续使用 `runtime_options`：
+当 `mcp_config` 缺失时，adapter 会关闭 CSGClaw 托管 MCP：
 
 ```json
 {
-  "runtime_options": {
+  "tools": {
     "mcp": {
-      "mcpServers": {
-        "context7": {
-          "command": "uvx",
-          "args": ["context7-mcp"]
-        }
-      }
+      "enabled": false
     }
   }
 }
 ```
 
-语义：
+### Codex CLI
+
+Codex CLI 接收同样的 `mcp_config.mcpServers`，写入隔离 Codex home 的 `config.toml` 管理块：
 
-- `runtime_options` 字段缺失：不修改 runtime options，也不修改 MCP。
-- `runtime_options` 字段存在：整体替换当前 runtime options。
-- `runtime_options.mcp` 缺失：提交后的 runtime options 不再包含 MCP。
-- `runtime_options.mcp: null`：清除 MCP。
-- `runtime_options.mcp` 为 object：替换整个 MCP 配置。
+```toml
+# BEGIN csgclaw-managed mcp
+[mcp_servers."context7"]
+command = "uvx"
+args = ["context7-mcp"]
+env = { "CONTEXT7_API_KEY" = "secret" }
+# END csgclaw-managed mcp
+```
 
-因此前端保存 MCP 时应总是提交合并后的完整 `runtime_options`：
+远程 server 会写入 Codex 支持的字段：
+
+```toml
+[mcp_servers."remote-search"]
+url = "https://mcp.example.com/mcp"
+bearer_token_env_var = "MCP_TOKEN"
+oauth_client_id = "client-id"
+oauth_resource = "resource"
+```
+
+Codex adapter 会忽略统一输入中 Codex 不支持的共享字段，例如 `headers`、`transport`，但共享 validator 仍保证这些字段是可预测的 string/string-map 类型。
+
+## 5. API 与持久化
+
+涉及字段：
+
+- `agent.Agent.MCPConfig`
+- `agent.CreateAgentSpec.MCPConfig`
+- `agent.UpdateRequest.MCPConfig`
+- `apitypes.Agent.MCPConfig`
+- participant agent binding 中的 create payload
+- Web `AgentLike.mcp_config` / `AgentDraft.mcp_config`
+
+创建 agent：
 
 ```json
 {
-  "runtime_options": {
-    "local_workspace_dir": "/path/kept-from-existing-options",
-    "mcp": {
-      "mcpServers": {
-        "context7": {
-          "command": "uvx",
-          "args": ["context7-mcp"]
-        }
+  "name": "alice",
+  "runtime_kind": "picoclaw_sandbox",
+  "mcp_config": {
+    "mcpServers": {
+      "context7": {
+        "command": "uvx",
+        "args": ["context7-mcp"]
       }
     }
   }
 }
 ```
 
-成功返回沿用现有 agent response，`runtime_options` 中包含当前 MCP 配置。已有 agent 的 MCP 变更会在返回前尝试自动 recreate；如果 recreate 成功，`env_restart_required` 为 false 或省略：
+更新 agent：
 
 ```json
 {
-  "agent_profile": {
-    "env_restart_required": false
-  },
-  "runtime_options": {
-    "mcp": {
-      "mcpServers": {}
+  "mcp_config": {
+    "mcpServers": {
+      "context7": {
+        "command": "uvx",
+        "args": ["context7-mcp"]
+      }
     }
   }
 }
 ```
 
-如果 update 已持久化但 recreate 失败，后端返回错误；前端应刷新 agent 状态并继续使用已有 `env_restart_required` badge 和 recreate action 作为重试入口。
-
-## 6. 前端 UI 设计
-
-### 6.1 页面位置
-
-在现有 Agent 创建和编辑路径中增加 OpenClaw MCP 区域：
+清除 MCP：
 
-- 创建 agent modal：`AgentProfileModal` 的 runtime section 下展示。
-- Agent 详情页：`AgentDetailPane` 的 runtime section 下展示。
-- 仅当 draft 的 `runtime_kind` 为 `openclaw_sandbox` 时展示。
-- 控件读写 `draft.runtime_options.mcp`，不引入 top-level `mcp_config` 状态。
-
-MCP 区域可以做成专用组件，但它必须作为 runtime options 的编辑器存在：
-
-```text
-MCPRuntimeOptionsPanel
+```json
+{
+  "mcp_config": null
+}
 ```
 
-### 6.2 区域结构
+兼容逻辑：
 
-区域内容：
+- create/update 收到旧 `runtime_options.mcp` 时，会迁移到 `MCPConfig`。
+- 迁移后保存的 runtime options 不再包含 `mcp`。
+- 如果同一次请求同时提交 `mcp_config` 和 `runtime_options.mcp`，以显式 `mcp_config` 为准。
 
-- 标题：`MCP Servers`
-- JSON 编辑器：textarea 或轻量 code editor，保存前做 JSON parse。
-- 操作按钮：填入示例、清除配置。
-- 保存动作复用创建/编辑表单已有保存按钮，不在 MCP 面板内新增独立保存流程。
+## 6. 保存与重建
 
-创建 agent 时：
+更新 `mcp_config` 的流程：
 
-- 展示空 JSON 编辑器。
-- 提供示例填充按钮。
-- 保存创建后直接生效，不显示“需要重建”。
+1. 解析请求并迁移 legacy `runtime_options.mcp`。
+2. 通过对应 runtime 的 `MCPConfigController.ValidateMCPConfig` 校验。
+3. 持久化新的 `Agent.MCPConfig`。
+4. 通过 `MCPConfigRestartRequired` 判断是否需要 recreate。
+5. 需要 recreate 时，设置 `env_restart_required = true`，再调用现有 `Recreate`。
+6. recreate 成功后，新 runtime provision 使用最新 `MCPConfig` 生成原生配置，并清除 `env_restart_required`。
+7. recreate 失败时，已保存的 `mcp_config` 保留，`env_restart_required` 继续为 true，用户可通过现有重建动作重试。
+8. 如果 runtime 支持无需重建的配置同步，则通过 `ReconcileMCPConfig` 完成。
 
-编辑已有 agent 时：
+当前 OpenClaw、PicoClaw 和 Codex 的 MCP 配置变更都按需要重建处理，Codex 同时实现了 `ReconcileMCPConfig` 用于重写隔离 Codex home 配置。
 
-- 默认把现有 `runtime_options.mcp` 填回编辑器。
-- 用户保存时，前端将编辑后的 MCP 合并回完整 `runtime_options` 后提交。
-- 用户选择“清除配置”后，提交合并后的 `runtime_options`，其中 `mcp` 为 `null` 或删除 `mcp` key。
-- 保存成功表示后端已完成自动 recreate 并刷新为新 runtime。
-- 保存失败时刷新 agent；如果 `env_restart_required` 为 true，使用现有 `profileRestartRequired` badge，并在详情页 runtime section 展示重建 CTA。
+## 7. 前端行为
 
-### 6.3 自动重建交互
+前端保留现有 MCP JSON 编辑器组件，但读写对象改为 `draft.mcp_config`。
 
-MCP 修改保存后，后端负责自动重建 runtime；前端不再提供专门的“保存并重建”主流程。
+展示位置：
 
-推荐交互：
+- 创建 agent modal 的 runtime section。
+- Agent 详情页 runtime section。
 
-1. 用户点击“保存”：
-   - 保存合并后的 `runtime_options`。
-   - 后端自动调用 recreate。
-   - update 成功返回 agent response。
-   - 刷新 agent 列表和详情。
-   - 不显示 `Recreate required` badge。
-2. update 返回错误：
-   - 展示错误。
-   - 刷新 agent 列表和详情。
-   - 如果刷新后的 agent 仍有 `env_restart_required`，显示现有重建 CTA。
-3. 用户点击已有 agent action 的“重建”：
-   - 复用现有 recreate action。
-   - 成功后 `env_restart_required` 清除。
+展示条件：
 
-如果 agent 正在运行，保存 MCP 配置会触发 runtime recreate。当前路径会重建该 agent 的 runtime 进程，不依赖 hot reload。
+- `openclaw_sandbox`
+- `picoclaw_sandbox`
+- `codex`
 
-## 7. 验证与测试
+保存行为：
 
-后端覆盖：
+- 创建 agent 时，非空 MCP JSON 写入 create payload 的 `mcp_config`。
+- 编辑 agent 时，MCP JSON 变化写入 update payload 的 `mcp_config`。
+- 清除配置时，update payload 写入 `mcp_config: null`。
+- `runtime_options` 和 `mcp_config` 独立比较、独立提交，避免 MCP 编辑覆盖其它 runtime option，例如 Codex 的 `local_workspace_dir`。
 
-- `runtime_options.mcp` 的缺失、`null`、空对象、空 `mcpServers`、非空 `mcpServers` 语义正确。
-- 非 object server entry 报错。
-- 缺少 `command` 和 `url` 的 server entry 报错。
-- 保存 MCP 时保留其它 runtime options。
-- MCP 配置变更后先标记 `env_restart_required`，随后自动调用 `Recreate`。
-- `Recreate` 后重新 provision，并把最新 MCP 传给 runtime adapter。
-- 自动 `Recreate` 成功后清除 `env_restart_required`。
-- 自动 `Recreate` 失败后保留已保存的 `runtime_options.mcp` 和 `env_restart_required = true`。
-- `openclawsandbox.renderConfig` 能把 `runtime_options.mcp.mcpServers` 渲染为 `mcp.servers`。
-- OpenClaw `null` 清除和空集合渲染行为正确。
-- 非 OpenClaw runtime 收到 `runtime_options.mcp` 时返回明确错误。
-- `syncGatewayHostConfig` 重写 OpenClaw host config 时不会丢失 MCP 配置。
+## 8. 验证
 
-前端覆盖：
+已覆盖的后端测试重点：
 
-- `AgentProfileModal` 能编辑 `runtime_options.mcp`。
-- `AgentDetailPane` 能显示和编辑 `runtime_options.mcp`。
-- 保存 MCP 时不覆盖其它 runtime options。
-- 替换 MCP 时提交合并后的 `runtime_options`。
-- 清除 MCP 时提交合并后的 `runtime_options`。
-- 保存已有 agent 的 MCP 配置时只调用 update；recreate 由后端自动完成。
-- update 失败后刷新 agent，并能展示现有 recreate required 状态。
+- `mcp_config` 缺失、空对象、空 `mcpServers`、非空 `mcpServers` 的语义。
+- legacy `runtime_options.mcp` 迁移。
+- OpenClaw/PicoClaw 接受 MCP 配置。
+- Codex 生成 `[mcp_servers."<name>"]` 配置块。
+- MCP 配置变更触发 recreate，失败时保留 restart required 状态。
 
-可手工验证：
+已覆盖的前端测试重点：
 
-1. 创建 agent，带一个 stdio MCP server。
-2. 对 OpenClaw agent，检查宿主机 `~/.csgclaw/agents/<agent-id>/.openclaw/openclaw.json` 包含 `mcp.servers`。
-3. 启动 agent 后确认 runtime 能看到 MCP tool。
-4. 修改 MCP 配置并保存，确认后端自动重建 runtime。
-5. 自动重建成功后确认新配置生效，`env_restart_required` 清除。
-6. 模拟 recreate 失败，确认已保存 MCP 配置保留，`env_restart_required` 为 true，现有重建 action 可恢复。
-7. MCP 配置生效后修改 profile，确认 host config sync 不会丢失 `mcp.servers`。
+- 模型层解析、保存和清除 `mcp_config`。
+- OpenClaw/PicoClaw/Codex runtime 都展示 MCP 配置入口。
+- Agent 创建/编辑 payload 使用顶层 `mcp_config`。
+- MCP 编辑不覆盖普通 `runtime_options`。
 
-本 PR 使用过的定向验证命令：
+本分支使用过的验证命令：
 
 ```bash
-go test ./internal/runtime/openclawsandbox ./internal/agent -run 'Test(RenderAgentOpenClawConfig.*MCP|UpdateOpenClawMCP|UpdateMCPRuntimeOptions|CreateMCPRuntimeOptions|Replace.*MCP|UpdateFieldMaskClearsRuntimeOptions)'
+go test ./internal/runtime/openclawsandbox ./internal/runtime/picoclawsandbox ./internal/runtime/codex ./internal/agent ./internal/api ./internal/apitypes
 pnpm exec vitest run tests/models/agents.test.ts tests/components/AgentProfileModal.test.tsx tests/components/AgentActions.test.tsx
+pnpm exec tsc --noEmit
 ```
-
-## 8. 已完成改动
-
-1. 增加 `runtime_options.mcp` parser/validator 和共享 helper。
-2. 扩展 provision request，把 `Agent.RuntimeOptions` 传到 runtime provision 边界。
-3. 增加 OpenClaw runtime config controller：`runtime_options.mcp` 变化后标记 `env_restart_required`，并自动调用现有 `Recreate`。
-4. 实现 OpenClaw adapter，把 `runtime_options.mcp.mcpServers` 渲染到 `openclaw.json` 的 `mcp.servers`。
-5. 让 `syncGatewayHostConfig` 重写 OpenClaw host config 时也传入并渲染当前 `Agent.RuntimeOptions`，避免 profile 热同步丢失 MCP。
-6. 拒绝非 OpenClaw runtime 的 `runtime_options.mcp`。
-7. 接入前端 Agent 创建/详情页 MCP runtime options UI。
-8. 补充 `docs/api.zh.md` 和 `docs/api.md` 的 MCP runtime options 示例。
diff --git a/internal/agent/model.go b/internal/agent/model.go
index 205ff00f..dda27307 100644
--- a/internal/agent/model.go
+++ b/internal/agent/model.go
@@ -2,6 +2,7 @@ package agent
 
 import (
 	"encoding/json"
+	"fmt"
 	"slices"
 	"strings"
 	"time"
@@ -29,6 +30,7 @@ type Agent struct {
 	Avatar           string                   `json:"avatar,omitempty"`
 	BoxID            string                   `json:"box_id,omitempty"`
 	RuntimeOptions   map[string]any           `json:"runtime_options,omitempty"`
+	MCPConfig        map[string]any           `json:"mcp_config,omitempty"`
 	Role             string                   `json:"role"`
 	Status           string                   `json:"status"`
 	CreatedAt        time.Time                `json:"created_at"`
@@ -81,6 +83,7 @@ func (a *Agent) UnmarshalJSON(data []byte) error {
 		Avatar           string                   `json:"avatar,omitempty"`
 		BoxID            string                   `json:"box_id,omitempty"`
 		RuntimeOptions   map[string]any           `json:"runtime_options,omitempty"`
+		MCPConfig        map[string]any           `json:"mcp_config,omitempty"`
 		Role             string                   `json:"role"`
 		Status           string                   `json:"status"`
 		CreatedAt        time.Time                `json:"created_at"`
@@ -107,6 +110,7 @@ func (a *Agent) UnmarshalJSON(data []byte) error {
 		Avatar:           decoded.Avatar,
 		BoxID:            decoded.BoxID,
 		RuntimeOptions:   utils.CloneAnyMap(decoded.RuntimeOptions),
+		MCPConfig:        utils.CloneAnyMap(decoded.MCPConfig),
 		Role:             decoded.Role,
 		Status:           decoded.Status,
 		CreatedAt:        decoded.CreatedAt,
@@ -148,6 +152,7 @@ func (a *Agent) UnmarshalJSON(data []byte) error {
 			out.SandboxEnabled = *decoded.Runtime.SandboxEnabled
 		}
 	}
+	out.RuntimeOptions, out.MCPConfig = splitLegacyRuntimeOptionsMCP(out.RuntimeOptions, out.MCPConfig)
 	out.SetRuntimeConfig(out.RuntimeConfig())
 	profilePayload := decoded.ModelConfig
 	if len(profilePayload) == 0 || string(profilePayload) == "null" {
@@ -187,6 +192,7 @@ type CreateAgentSpec struct {
 	UpdatedAt      time.Time      `json:"updated_at,omitempty"`
 	Profile        string         `json:"profile,omitempty"`
 	RuntimeOptions map[string]any `json:"runtime_options,omitempty"`
+	MCPConfig      map[string]any `json:"mcp_config,omitempty"`
 	AgentProfile   AgentProfile   `json:"agent_profile,omitempty"`
 }
 
@@ -228,6 +234,7 @@ func (s CreateAgentSpec) MarshalJSON() ([]byte, error) {
 		UpdatedAt      time.Time      `json:"updated_at,omitempty"`
 		Profile        string         `json:"profile,omitempty"`
 		RuntimeOptions map[string]any `json:"runtime_options,omitempty"`
+		MCPConfig      map[string]any `json:"mcp_config,omitempty"`
 		AgentProfile   AgentProfile   `json:"agent_profile,omitempty"`
 	}
 	runtimeName := strings.TrimSpace(s.RuntimeName)
@@ -270,6 +277,7 @@ func (s CreateAgentSpec) MarshalJSON() ([]byte, error) {
 		UpdatedAt:      s.UpdatedAt,
 		Profile:        s.Profile,
 		RuntimeOptions: utils.CloneAnyMap(s.RuntimeOptions),
+		MCPConfig:      utils.CloneAnyMap(s.MCPConfig),
 		AgentProfile:   cloneProfile(s.AgentProfile),
 	})
 }
@@ -293,6 +301,7 @@ func (s *CreateAgentSpec) UnmarshalJSON(data []byte) error {
 		ModelConfig    json.RawMessage `json:"model_config,omitempty"`
 		Profile        json.RawMessage `json:"profile,omitempty"`
 		RuntimeOptions map[string]any  `json:"runtime_options,omitempty"`
+		MCPConfig      map[string]any  `json:"mcp_config,omitempty"`
 		AgentProfile   AgentProfile    `json:"agent_profile,omitempty"`
 	}
 	var decoded createAgentSpecJSON
@@ -312,6 +321,7 @@ func (s *CreateAgentSpec) UnmarshalJSON(data []byte) error {
 		CreatedAt:      decoded.CreatedAt,
 		UpdatedAt:      decoded.UpdatedAt,
 		RuntimeOptions: utils.CloneAnyMap(decoded.RuntimeOptions),
+		MCPConfig:      utils.CloneAnyMap(decoded.MCPConfig),
 		AgentProfile:   cloneProfile(decoded.AgentProfile),
 	}
 	if decoded.SandboxEnabled != nil {
@@ -340,6 +350,7 @@ func (s *CreateAgentSpec) UnmarshalJSON(data []byte) error {
 			out.SandboxEnabled = *decoded.Runtime.SandboxEnabled
 		}
 	}
+	out.RuntimeOptions, out.MCPConfig = splitLegacyRuntimeOptionsMCP(out.RuntimeOptions, out.MCPConfig)
 	out.SetRuntimeConfig(out.RuntimeConfig())
 	profilePayload := decoded.ModelConfig
 	if len(profilePayload) == 0 || string(profilePayload) == "null" {
@@ -370,6 +381,8 @@ type UpdateRequest struct {
 	Avatar         *string         `json:"-"`
 	Profile        *string         `json:"profile,omitempty"`
 	RuntimeOptions *map[string]any `json:"runtime_options,omitempty"`
+	MCPConfig      *map[string]any `json:"mcp_config,omitempty"`
+	MCPConfigSet   bool            `json:"-"`
 	AgentProfile   *AgentProfile   `json:"agent_profile,omitempty"`
 	FieldMask      []string        `json:"field_mask,omitempty"`
 }
@@ -385,6 +398,7 @@ func (r *UpdateRequest) UnmarshalJSON(data []byte) error {
 		Profile        json.RawMessage `json:"profile,omitempty"`
 		Runtime        *RuntimeRecord  `json:"runtime,omitempty"`
 		RuntimeOptions *map[string]any `json:"runtime_options,omitempty"`
+		MCPConfig      *map[string]any `json:"mcp_config,omitempty"`
 		AgentProfile   *AgentProfile   `json:"agent_profile,omitempty"`
 		FieldMask      []string        `json:"field_mask,omitempty"`
 	}
@@ -398,9 +412,23 @@ func (r *UpdateRequest) UnmarshalJSON(data []byte) error {
 		Instructions:   decoded.Instructions,
 		Image:          decoded.Image,
 		RuntimeOptions: decoded.RuntimeOptions,
+		MCPConfig:      decoded.MCPConfig,
 		AgentProfile:   decoded.AgentProfile,
 		FieldMask:      append([]string(nil), decoded.FieldMask...),
 	}
+	var rawFields map[string]json.RawMessage
+	if err := json.Unmarshal(data, &rawFields); err == nil {
+		if raw, ok := rawFields["mcp_config"]; ok {
+			out.MCPConfigSet = true
+			if string(raw) != "null" {
+				var cfg map[string]any
+				if err := json.Unmarshal(raw, &cfg); err != nil {
+					return err
+				}
+				out.MCPConfig = &cfg
+			}
+		}
+	}
 	profileField := ""
 	profilePayload := decoded.ModelConfig
 	if len(profilePayload) == 0 || string(profilePayload) == "null" {
@@ -425,6 +453,23 @@ func (r *UpdateRequest) UnmarshalJSON(data []byte) error {
 		options := utils.CloneAnyMap(decoded.Runtime.Options)
 		out.RuntimeOptions = &options
 	}
+	if out.RuntimeOptions != nil {
+		var existingMCPConfig map[string]any
+		if out.MCPConfig != nil {
+			existingMCPConfig = *out.MCPConfig
+		}
+		options, mcpConfig, legacyMCPSet, err := splitLegacyRuntimeOptionsMCPStrictWithPresence(*out.RuntimeOptions, existingMCPConfig, out.MCPConfigSet)
+		if err != nil {
+			return err
+		}
+		out.RuntimeOptions = &options
+		if !out.MCPConfigSet && legacyMCPSet {
+			if mcpConfig != nil {
+				out.MCPConfig = &mcpConfig
+			}
+			out.MCPConfigSet = true
+		}
+	}
 	if len(out.FieldMask) > 0 {
 		out.FieldMask = normalizeCompactUpdateFieldMask(out.FieldMask, profileField, decoded.Runtime != nil)
 	}
@@ -537,5 +582,77 @@ func cloneAgent(src *Agent) *Agent {
 	dst.AgentProfile = cloneProfile(src.AgentProfile)
 	dst.DetectionResults = append([]ProfileDetectionResult(nil), src.DetectionResults...)
 	dst.RuntimeOptions = utils.CloneAnyMap(src.RuntimeOptions)
+	dst.MCPConfig = utils.CloneAnyMap(src.MCPConfig)
 	return &dst
 }
+
+func splitLegacyRuntimeOptionsMCP(runtimeOptions map[string]any, mcpConfig map[string]any) (map[string]any, map[string]any) {
+	options, currentMCP, _, _ := splitLegacyRuntimeOptionsMCPValue(runtimeOptions, mcpConfig, mcpConfig != nil, false)
+	return options, currentMCP
+}
+
+func splitLegacyRuntimeOptionsMCPStrict(runtimeOptions map[string]any, mcpConfig map[string]any, mcpConfigProvided bool) (map[string]any, map[string]any, error) {
+	options, currentMCP, _, err := splitLegacyRuntimeOptionsMCPValue(runtimeOptions, mcpConfig, mcpConfigProvided, true)
+	return options, currentMCP, err
+}
+
+func splitLegacyRuntimeOptionsMCPStrictWithPresence(runtimeOptions map[string]any, mcpConfig map[string]any, mcpConfigProvided bool) (map[string]any, map[string]any, bool, error) {
+	return splitLegacyRuntimeOptionsMCPValue(runtimeOptions, mcpConfig, mcpConfigProvided, true)
+}
+
+func splitLegacyRuntimeOptionsMCPValue(runtimeOptions map[string]any, mcpConfig map[string]any, mcpConfigProvided, strict bool) (map[string]any, map[string]any, bool, error) {
+	options := utils.CloneAnyMap(runtimeOptions)
+	currentMCP := cloneAnyMapPreserveEmpty(mcpConfig)
+	if options == nil {
+		return nil, currentMCP, false, nil
+	}
+	raw, ok := options[agentruntime.RuntimeOptionMCPKey]
+	if !ok {
+		if len(options) == 0 {
+			return nil, currentMCP, false, nil
+		}
+		return options, currentMCP, false, nil
+	}
+	delete(options, agentruntime.RuntimeOptionMCPKey)
+	if !mcpConfigProvided {
+		if raw == nil {
+			currentMCP = nil
+		} else {
+			rawMap, ok := raw.(map[string]any)
+			if !ok {
+				if strict {
+					return nil, nil, true, fmt.Errorf("runtime_options.%s must be an object or null", agentruntime.RuntimeOptionMCPKey)
+				}
+			} else if normalized, err := agentruntime.NormalizeMCPConfig(rawMap); err == nil {
+				currentMCP = normalized
+			} else if strict {
+				return nil, nil, true, legacyRuntimeOptionsMCPErrorPath(err)
+			} else {
+				currentMCP = cloneAnyMapPreserveEmpty(rawMap)
+			}
+		}
+	}
+	if len(options) == 0 {
+		options = nil
+	}
+	return options, currentMCP, true, nil
+}
+
+func legacyRuntimeOptionsMCPErrorPath(err error) error {
+	if err == nil {
+		return nil
+	}
+	message := strings.ReplaceAll(err.Error(), "mcp_config", "runtime_options."+agentruntime.RuntimeOptionMCPKey)
+	return fmt.Errorf("%s", message)
+}
+
+func cloneAnyMapPreserveEmpty(src map[string]any) map[string]any {
+	if src == nil {
+		return nil
+	}
+	out := make(map[string]any, len(src))
+	for key, value := range src {
+		out[key] = value
+	}
+	return out
+}
diff --git a/internal/agent/runtime_record.go b/internal/agent/runtime_record.go
index f8b29842..2d66c4af 100644
--- a/internal/agent/runtime_record.go
+++ b/internal/agent/runtime_record.go
@@ -181,13 +181,14 @@ func runtimeRecordForAgent(a Agent) RuntimeRecord {
 	if a.CreatedAt.IsZero() {
 		createdAt = time.Time{}
 	}
+	runtimeOptions, _ := splitLegacyRuntimeOptionsMCP(a.RuntimeOptions, a.MCPConfig)
 	return normalizeRuntimeRecord(RuntimeRecord{
 		ID:        normalizeRuntimeID(a.RuntimeID, a.ID),
 		Kind:      a.RuntimeConfig().LegacyKind(),
 		State:     agentruntime.State(strings.TrimSpace(a.Status)),
 		AgentIDs:  []string{strings.TrimSpace(a.ID)},
 		SandboxID: strings.TrimSpace(a.BoxID),
-		Options:   a.RuntimeOptions,
+		Options:   runtimeOptions,
 		CreatedAt: createdAt,
 	})
 }
diff --git a/internal/agent/service.go b/internal/agent/service.go
index 7b762681..18c21135 100644
--- a/internal/agent/service.go
+++ b/internal/agent/service.go
@@ -1153,11 +1153,24 @@ func (s *Service) validateReplaceWorkerSpecBeforeDelete(ctx context.Context, spe
 	if _, err := s.runtimeForKind(runtimeKind); err != nil {
 		return err
 	}
+	var err error
+	spec.RuntimeOptions, spec.MCPConfig, err = splitLegacyRuntimeOptionsMCPStrict(spec.RuntimeOptions, spec.MCPConfig, spec.MCPConfig != nil)
+	if err != nil {
+		return err
+	}
+	normalizedMCPConfig, err := normalizeMCPConfig(spec.MCPConfig)
+	if err != nil {
+		return err
+	}
+	spec.MCPConfig = normalizedMCPConfig
 	resolvedProfile, err := s.profileForCreateRequest(ctx, &spec)
 	if err != nil {
 		return err
 	}
-	return s.validateRuntimeConfig(ctx, runtimeKind, runtimeConfigSnapshotForAgent(s.hydrateProfileFromCatalog(resolvedProfile), spec.RuntimeOptions))
+	if err := s.validateRuntimeConfig(ctx, runtimeKind, runtimeConfigSnapshotForAgent(s.hydrateProfileFromCatalog(resolvedProfile), spec.RuntimeOptions)); err != nil {
+		return err
+	}
+	return s.validateMCPConfig(ctx, runtimeKind, mcpConfigSnapshotForAgent(spec.MCPConfig))
 }
 
 func (s *Service) managerImageOverrideForReplace(ctx context.Context, existing Agent, runtimeKind string) string {
@@ -1188,6 +1201,7 @@ func mergeReplaceSpec(existing Agent, next CreateAgentSpec, fieldMask []string)
 		UpdatedAt:      existing.UpdatedAt,
 		Profile:        existing.Profile,
 		RuntimeOptions: utils.CloneAnyMap(existing.RuntimeOptions),
+		MCPConfig:      utils.CloneAnyMap(existing.MCPConfig),
 		AgentProfile:   cloneProfile(existing.AgentProfile),
 	}
 	for _, field := range fieldMask {
@@ -1222,6 +1236,7 @@ func mergeReplaceSpec(existing Agent, next CreateAgentSpec, fieldMask []string)
 			merged.RuntimeName = next.RuntimeName
 			merged.SandboxEnabled = next.SandboxEnabled
 			merged.RuntimeOptions = utils.CloneAnyMap(next.RuntimeOptions)
+			merged.MCPConfig = utils.CloneAnyMap(next.MCPConfig)
 		case "role":
 			merged.Role = next.Role
 		case "status":
@@ -1239,6 +1254,8 @@ func mergeReplaceSpec(existing Agent, next CreateAgentSpec, fieldMask []string)
 			merged.AgentProfile = cloneProfile(next.AgentProfile)
 		case "runtime_options":
 			merged.RuntimeOptions = utils.CloneAnyMap(next.RuntimeOptions)
+		case "mcp_config":
+			merged.MCPConfig = utils.CloneAnyMap(next.MCPConfig)
 		default:
 			return CreateAgentSpec{}, fmt.Errorf("unsupported agent field mask path %q", field)
 		}
@@ -1410,6 +1427,9 @@ func (s *Service) Start(ctx context.Context, id string) (Agent, error) {
 	if err := s.validateRuntimeConfig(ctx, strings.TrimSpace(got.RuntimeKind), runtimeConfigSnapshotForAgent(startProfile, got.RuntimeOptions)); err != nil {
 		return Agent{}, err
 	}
+	if err := s.validateMCPConfig(ctx, strings.TrimSpace(got.RuntimeKind), mcpConfigSnapshotForAgent(got.MCPConfig)); err != nil {
+		return Agent{}, err
+	}
 
 	runtimeImpl, err := s.runtimeForKind(strings.TrimSpace(got.RuntimeKind))
 	if err != nil {
@@ -1664,6 +1684,10 @@ func (s *Service) recreateLegacyNamedGatewayAgentBox(ctx context.Context, got Ag
 		_ = s.closeBox(box)
 		return got, false, err
 	}
+	if err := s.validateMCPConfig(ctx, strings.TrimSpace(got.RuntimeKind), mcpConfigSnapshotForAgent(got.MCPConfig)); err != nil {
+		_ = s.closeBox(box)
+		return got, false, err
+	}
 	runtimeImpl, err := s.runtimeForKind(strings.TrimSpace(got.RuntimeKind))
 	if err != nil {
 		_ = s.closeBox(box)
@@ -1830,6 +1854,15 @@ func (s *Service) CreateWorker(ctx context.Context, spec CreateAgentSpec) (Agent
 		return Agent{}, err
 	}
 	spec.SetRuntimeConfig(runtimeCfg)
+	spec.RuntimeOptions, spec.MCPConfig, err = splitLegacyRuntimeOptionsMCPStrict(spec.RuntimeOptions, spec.MCPConfig, spec.MCPConfig != nil)
+	if err != nil {
+		return Agent{}, err
+	}
+	normalizedMCPConfig, err := normalizeMCPConfig(spec.MCPConfig)
+	if err != nil {
+		return Agent{}, err
+	}
+	spec.MCPConfig = normalizedMCPConfig
 	runtimeKind := spec.RuntimeKind
 	runtimeName := spec.RuntimeName
 	sandboxed := spec.SandboxEnabled
@@ -1898,9 +1931,6 @@ func (s *Service) CreateWorker(ctx context.Context, spec CreateAgentSpec) (Agent
 	if err != nil {
 		return Agent{}, err
 	}
-	if err := validateMCPRuntimeOptionSupport(runtimeKind, spec.RuntimeOptions); err != nil {
-		return Agent{}, err
-	}
 	resolvedProfile, err := s.profileForCreateRequest(ctx, &spec)
 	if err != nil {
 		return Agent{}, err
@@ -1909,6 +1939,9 @@ func (s *Service) CreateWorker(ctx context.Context, spec CreateAgentSpec) (Agent
 	if err := s.validateRuntimeConfig(ctx, runtimeKind, runtimeConfigSnapshotForAgent(runtimeResolvedProfile, spec.RuntimeOptions)); err != nil {
 		return Agent{}, err
 	}
+	if err := s.validateMCPConfig(ctx, runtimeKind, mcpConfigSnapshotForAgent(spec.MCPConfig)); err != nil {
+		return Agent{}, err
+	}
 	runtimeProfile := s.runtimeProfileForKind(runtimeKind, id, name, description, runtimeResolvedProfile)
 	if err := s.provisionRuntime(ctx, runtimeImpl, runtimeKind, agentruntime.ProvisionRequest{
 		RuntimeID:        runtimeIDForAgentID(id),
@@ -1917,6 +1950,7 @@ func (s *Service) CreateWorker(ctx context.Context, spec CreateAgentSpec) (Agent
 		AgentName:        name,
 		Profile:          runtimeProfile,
 		RuntimeOptions:   utils.CloneAnyMap(spec.RuntimeOptions),
+		MCPConfig:        utils.CloneAnyMap(spec.MCPConfig),
 		WorkspaceOverlay: strings.TrimSpace(spec.FromTemplate),
 	}); err != nil {
 		return Agent{}, fmt.Errorf("provision worker runtime: %w", err)
@@ -1940,14 +1974,14 @@ func (s *Service) CreateWorker(ctx context.Context, spec CreateAgentSpec) (Agent
 		defer func() {
 			_ = s.closeBox(box)
 		}()
-		return s.persistCreatedWorker(ctx, id, name, description, instructions, image, avatar, runtimeKind, runtimeName, sandboxed, resolvedProfile, spec.RuntimeOptions, agentruntime.Info{
+		return s.persistCreatedWorker(ctx, id, name, description, instructions, image, avatar, runtimeKind, runtimeName, sandboxed, resolvedProfile, spec.RuntimeOptions, spec.MCPConfig, agentruntime.Info{
 			HandleID:  strings.TrimSpace(info.ID),
 			State:     agentruntime.State(info.State),
 			CreatedAt: info.CreatedAt.UTC(),
 		})
 	}
 	if runtimeKind == RuntimeKindCodex {
-		if err := s.persistStartingWorker(ctx, id, name, description, instructions, image, avatar, runtimeKind, runtimeName, sandboxed, resolvedProfile, spec.RuntimeOptions); err != nil {
+		if err := s.persistStartingWorker(ctx, id, name, description, instructions, image, avatar, runtimeKind, runtimeName, sandboxed, resolvedProfile, spec.RuntimeOptions, spec.MCPConfig); err != nil {
 			return Agent{}, err
 		}
 		defer func() {
@@ -1972,10 +2006,10 @@ func (s *Service) CreateWorker(ctx context.Context, spec CreateAgentSpec) (Agent
 		CreatedAt: time.Now().UTC(),
 	}
 
-	return s.persistCreatedWorker(ctx, id, name, description, instructions, image, avatar, runtimeKind, runtimeName, sandboxed, resolvedProfile, spec.RuntimeOptions, info)
+	return s.persistCreatedWorker(ctx, id, name, description, instructions, image, avatar, runtimeKind, runtimeName, sandboxed, resolvedProfile, spec.RuntimeOptions, spec.MCPConfig, info)
 }
 
-func (s *Service) persistStartingWorker(ctx context.Context, id, name, description, instructions, image, avatar, runtimeKind, runtimeName string, sandboxEnabled bool, profile AgentProfile, runtimeOptions map[string]any) error {
+func (s *Service) persistStartingWorker(ctx context.Context, id, name, description, instructions, image, avatar, runtimeKind, runtimeName string, sandboxEnabled bool, profile AgentProfile, runtimeOptions map[string]any, mcpConfig map[string]any) error {
 	s.mu.Lock()
 
 	if _, _, ok := s.agentByIDLocked(id); ok {
@@ -1987,7 +2021,7 @@ func (s *Service) persistStartingWorker(ctx context.Context, id, name, descripti
 		return fmt.Errorf("agent name %q already exists", name)
 	}
 
-	worker := newWorkerAgent(id, name, description, instructions, image, avatar, runtimeKind, runtimeName, sandboxEnabled, profile, runtimeOptions, agentruntime.Info{
+	worker := newWorkerAgent(id, name, description, instructions, image, avatar, runtimeKind, runtimeName, sandboxEnabled, profile, runtimeOptions, mcpConfig, agentruntime.Info{
 		State:     agentruntime.StateCreated,
 		CreatedAt: time.Now().UTC(),
 	})
@@ -2014,7 +2048,7 @@ func (s *Service) removeStartingWorker(ctx context.Context, id string) error {
 	return err
 }
 
-func (s *Service) persistCreatedWorker(ctx context.Context, id, name, description, instructions, image, avatar, runtimeKind, runtimeName string, sandboxEnabled bool, profile AgentProfile, createRuntimeExt map[string]any, info agentruntime.Info) (Agent, error) {
+func (s *Service) persistCreatedWorker(ctx context.Context, id, name, description, instructions, image, avatar, runtimeKind, runtimeName string, sandboxEnabled bool, profile AgentProfile, createRuntimeExt map[string]any, mcpConfig map[string]any, info agentruntime.Info) (Agent, error) {
 	s.mu.Lock()
 
 	if existing, _, ok := s.agentByIDLocked(id); ok && !isStartingWorker(existing) {
@@ -2026,7 +2060,7 @@ func (s *Service) persistCreatedWorker(ctx context.Context, id, name, descriptio
 		return Agent{}, fmt.Errorf("agent name %q already exists", name)
 	}
 
-	worker := newWorkerAgent(id, name, description, instructions, image, avatar, runtimeKind, runtimeName, sandboxEnabled, profile, createRuntimeExt, info)
+	worker := newWorkerAgent(id, name, description, instructions, image, avatar, runtimeKind, runtimeName, sandboxEnabled, profile, createRuntimeExt, mcpConfig, info)
 	s.agents[worker.ID] = worker
 	s.syncRuntimeRecordLocked(worker)
 	if worker.AgentProfile.ProfileComplete {
@@ -2046,7 +2080,7 @@ func (s *Service) persistCreatedWorker(ctx context.Context, id, name, descriptio
 	return created, nil
 }
 
-func newWorkerAgent(id, name, description, instructions, image, avatar, runtimeKind, runtimeName string, sandboxEnabled bool, profile AgentProfile, runtimeOptions map[string]any, info agentruntime.Info) Agent {
+func newWorkerAgent(id, name, description, instructions, image, avatar, runtimeKind, runtimeName string, sandboxEnabled bool, profile AgentProfile, runtimeOptions map[string]any, mcpConfig map[string]any, info agentruntime.Info) Agent {
 	createdAt := info.CreatedAt.UTC()
 	if info.CreatedAt.IsZero() {
 		createdAt = time.Now().UTC()
@@ -2060,6 +2094,7 @@ func newWorkerAgent(id, name, description, instructions, image, avatar, runtimeK
 	if len(runtimeOptions) > 0 {
 		agentRX = utils.CloneAnyMap(runtimeOptions)
 	}
+	agentRX, mcpConfig = splitLegacyRuntimeOptionsMCP(agentRX, mcpConfig)
 	runtimeCfg, _ := agentruntime.RuntimeConfigFromSelection(runtimeKind, runtimeName, sandboxEnabled)
 	resolvedRuntimeKind := runtimeCfg.LegacyKind()
 	resolvedRuntimeName := runtimeCfg.Name
@@ -2079,6 +2114,7 @@ func newWorkerAgent(id, name, description, instructions, image, avatar, runtimeK
 		CreatedAt:       createdAt,
 		UpdatedAt:       createdAt,
 		RuntimeOptions:  agentRX,
+		MCPConfig:       utils.CloneAnyMap(mcpConfig),
 		Profile:         profileSelector(prof),
 		AgentProfile:    prof,
 		ProfileComplete: prof.ProfileComplete,
@@ -2138,6 +2174,7 @@ func (s *Service) provisionRuntimeForAgent(ctx context.Context, rt agentruntime.
 		AgentName:        strings.TrimSpace(got.Name),
 		Profile:          s.runtimeProfileForAgent(got),
 		RuntimeOptions:   utils.CloneAnyMap(got.RuntimeOptions),
+		MCPConfig:        utils.CloneAnyMap(got.MCPConfig),
 		WorkspaceOverlay: strings.TrimSpace(workspaceOverlay),
 	})
 }
diff --git a/internal/agent/service_profiles.go b/internal/agent/service_profiles.go
index b29ad499..84a5b3d2 100644
--- a/internal/agent/service_profiles.go
+++ b/internal/agent/service_profiles.go
@@ -11,6 +11,7 @@ import (
 	"csgclaw/internal/identity"
 	agentruntime "csgclaw/internal/runtime"
 	"csgclaw/internal/runtime/openclawsandbox"
+	"csgclaw/internal/runtime/picoclawsandbox"
 	"csgclaw/internal/sandbox"
 	"csgclaw/internal/utils"
 )
@@ -183,7 +184,11 @@ func (s *Service) syncGatewayHostConfig(got Agent, profile AgentProfile) error {
 	switch strings.TrimSpace(got.RuntimeKind) {
 	case RuntimeKindPicoClawSandbox:
 		feishuProvider := s.currentFeishuProviderForRuntime(RuntimeKindPicoClawSandbox)
-		if _, err := s.ensureAgentPicoClawConfigForParticipantWithResolver(got.Name, participantID, got.ID, s.server, modelCfg, resolveManagerBaseURL, feishuProvider); err != nil {
+		agentHome, err := s.agentHomeDir(got.ID)
+		if err != nil {
+			return err
+		}
+		if _, err := picoclawsandbox.EnsureConfigWithMCPConfig(agentHome, participantID, got.ID, s.server, modelCfg, got.MCPConfig, resolveManagerBaseURL, feishuProvider); err != nil {
 			return fmt.Errorf("sync gateway picoclaw config: %w", err)
 		}
 	case RuntimeKindOpenClawSandbox:
@@ -192,7 +197,7 @@ func (s *Service) syncGatewayHostConfig(got Agent, profile AgentProfile) error {
 			return err
 		}
 		feishuProvider := s.currentFeishuProviderForRuntime(RuntimeKindOpenClawSandbox)
-		if _, err := openclawsandbox.EnsureConfigWithRuntimeOptions(agentHome, participantID, got.ID, s.server, modelCfg, got.RuntimeOptions, resolveManagerBaseURL, feishuProvider); err != nil {
+		if _, err := openclawsandbox.EnsureConfigWithMCPConfig(agentHome, participantID, got.ID, s.server, modelCfg, got.MCPConfig, resolveManagerBaseURL, feishuProvider); err != nil {
 			return fmt.Errorf("sync gateway openclaw config: %w", err)
 		}
 	default:
@@ -258,6 +263,11 @@ func (s *Service) Update(ctx context.Context, id string, req UpdateRequest) (Age
 	}
 	instructionsUpdated := updateRequested("instructions", req.Instructions != nil)
 	runtimeOptionsUpdated := updateRequested("runtime_options", req.RuntimeOptions != nil)
+	mcpConfigUpdated := updateRequested("mcp_config", req.MCPConfigSet)
+	if mcpConfigUpdated && !req.MCPConfigSet {
+		s.mu.Unlock()
+		return Agent{}, fmt.Errorf("field_mask includes mcp_config but request is missing mcp_config")
+	}
 	if updateRequested("name", req.Name != nil) {
 		if req.Name == nil {
 			s.mu.Unlock()
@@ -320,7 +330,7 @@ func (s *Service) Update(ctx context.Context, id string, req UpdateRequest) (Age
 		current.Profile = strings.TrimSpace(*req.Profile)
 	}
 	agentProfileUpdated := updateRequested("agent_profile", req.AgentProfile != nil)
-	if !agentProfileUpdated && strings.TrimSpace(current.Profile) != "" {
+	if !hasFieldMask && !agentProfileUpdated && strings.TrimSpace(current.Profile) != "" {
 		if selected, ok := CatalogProviderModelConfig(s.llm, current.Profile); ok {
 			selected.Name = current.AgentProfile.Name
 			selected.Description = current.AgentProfile.Description
@@ -332,7 +342,7 @@ func (s *Service) Update(ctx context.Context, id string, req UpdateRequest) (Age
 			agentProfileUpdated = true
 		}
 	}
-	if agentProfileUpdated || runtimeOptionsUpdated {
+	if agentProfileUpdated || runtimeOptionsUpdated || mcpConfigUpdated {
 		profileUpdated = true
 		profile := current.AgentProfile
 		if agentProfileUpdated {
@@ -353,10 +363,20 @@ func (s *Service) Update(ctx context.Context, id string, req UpdateRequest) (Age
 				req.RuntimeOptions = &empty
 			}
 			patch = *req.RuntimeOptions
-			if err := validateMCPRuntimeOptionSupport(runtimeKind, patch); err != nil {
+			var legacyMCPConfig map[string]any
+			var legacyMCPSet bool
+			var err error
+			patch, legacyMCPConfig, legacyMCPSet, err = splitLegacyRuntimeOptionsMCPStrictWithPresence(patch, nil, false)
+			if err != nil {
 				s.mu.Unlock()
 				return Agent{}, err
 			}
+			if !mcpConfigUpdated && legacyMCPSet {
+				if legacyMCPConfig != nil {
+					req.MCPConfig = &legacyMCPConfig
+				}
+				mcpConfigUpdated = true
+			}
 		}
 		mergedFlat := runtimeOptionsAfterPatch(current.RuntimeKind, current.RuntimeOptions, nil)
 		if runtimeOptionsUpdated {
@@ -365,17 +385,41 @@ func (s *Service) Update(ctx context.Context, id string, req UpdateRequest) (Age
 		} else {
 			current.RuntimeOptions = nextAgentRuntimeOptions(current.RuntimeKind, current.RuntimeOptions, mergedFlat)
 		}
+		if mcpConfigUpdated {
+			if req.MCPConfig == nil {
+				current.MCPConfig = nil
+			} else {
+				normalizedMCPConfig, err := agentruntime.NormalizeMCPConfig(*req.MCPConfig)
+				if err != nil {
+					s.mu.Unlock()
+					return Agent{}, err
+				}
+				current.MCPConfig = normalizedMCPConfig
+			}
+		}
 		normalized := normalizeProfileForAgentRuntime(profile, current.RuntimeOptions, current.Name, current.Description, current.RuntimeKind, mergedFlat)
 		runtimePrevious := s.hydrateProfileFromCatalogLocked(previous.AgentProfile)
 		runtimeNormalized := s.hydrateProfileFromCatalogLocked(normalized)
 		change := runtimeConfigChangeForAgent(runtimePrevious, runtimeNormalized, previous.RuntimeOptions, current.RuntimeOptions)
+		mcpChange := mcpConfigChangeForAgent(previous.MCPConfig, current.MCPConfig)
+		runtimeConfigUpdated := agentProfileUpdated || runtimeOptionsUpdated
 		restartRequired = profileRestartRequired(previous, normalized)
-		controllerRestartRequired, err := s.runtimeConfigRestartRequired(runtimeKind, change)
-		if err != nil {
-			s.mu.Unlock()
-			return Agent{}, err
+		if runtimeConfigUpdated {
+			controllerRestartRequired, err := s.runtimeConfigRestartRequired(runtimeKind, change)
+			if err != nil {
+				s.mu.Unlock()
+				return Agent{}, err
+			}
+			restartRequired = restartRequired || controllerRestartRequired
+		}
+		if mcpConfigUpdated {
+			controllerMCPRestartRequired, err := s.mcpConfigRestartRequired(runtimeKind, mcpChange)
+			if err != nil {
+				s.mu.Unlock()
+				return Agent{}, err
+			}
+			restartRequired = restartRequired || controllerMCPRestartRequired
 		}
-		restartRequired = restartRequired || controllerRestartRequired
 		normalized.EnvRestartRequired = restartRequired
 		current.AgentProfile = normalized
 		current.ProfileComplete = normalized.ProfileComplete
@@ -384,10 +428,17 @@ func (s *Service) Update(ctx context.Context, id string, req UpdateRequest) (Age
 		if current.ProfileComplete && strings.EqualFold(strings.TrimSpace(current.Status), "profile_incomplete") {
 			current.Status = string(sandbox.StateStopped)
 		}
-		if runtimeNormalized.ProfileComplete {
+		if (runtimeConfigUpdated && runtimeNormalized.ProfileComplete) || mcpConfigUpdated {
 			s.mu.Unlock()
-			if err := s.validateRuntimeConfig(ctx, runtimeKind, change.Current); err != nil {
-				return Agent{}, err
+			if runtimeConfigUpdated && runtimeNormalized.ProfileComplete {
+				if err := s.validateRuntimeConfig(ctx, runtimeKind, change.Current); err != nil {
+					return Agent{}, err
+				}
+			}
+			if mcpConfigUpdated {
+				if err := s.validateMCPConfig(ctx, runtimeKind, mcpChange.Current); err != nil {
+					return Agent{}, err
+				}
 			}
 			s.mu.Lock()
 			if _, key, ok = s.agentByIDLocked(id); !ok {
@@ -413,6 +464,11 @@ func (s *Service) Update(ctx context.Context, id string, req UpdateRequest) (Age
 			return Agent{}, err
 		}
 	}
+	if mcpConfigUpdated {
+		if err := s.reconcileMCPConfig(ctx, previous, current); err != nil {
+			return Agent{}, err
+		}
+	}
 	if restartRequired && runtimeRunning && !isGatewayRuntimeKind(runtimeKind) {
 		s.stopLifecycleAgent(id)
 	}
@@ -482,15 +538,15 @@ func runtimeConfigSnapshotForAgent(profile AgentProfile, options map[string]any)
 	}
 }
 
-func validateMCPRuntimeOptionSupport(runtimeKind string, options map[string]any) error {
-	_, ok := options[agentruntime.RuntimeOptionMCPKey]
-	if !ok {
-		return nil
-	}
-	if strings.TrimSpace(runtimeKind) == RuntimeKindOpenClawSandbox {
-		return nil
+func mcpConfigChangeForAgent(previousConfig, currentConfig map[string]any) agentruntime.MCPConfigChange {
+	return agentruntime.MCPConfigChange{
+		Previous: mcpConfigSnapshotForAgent(previousConfig),
+		Current:  mcpConfigSnapshotForAgent(currentConfig),
 	}
-	return fmt.Errorf("runtime_options.%s is only supported for runtime_kind %q", agentruntime.RuntimeOptionMCPKey, RuntimeKindOpenClawSandbox)
+}
+
+func mcpConfigSnapshotForAgent(config map[string]any) agentruntime.MCPConfigSnapshot {
+	return agentruntime.MCPConfigSnapshot{Config: utils.CloneAnyMap(config)}
 }
 
 func (s *Service) hydrateProfileFromCatalog(profile AgentProfile) AgentProfile {
@@ -562,9 +618,6 @@ func (s *Service) validateRuntimeConfig(ctx context.Context, runtimeKind string,
 	if runtimeKind == "" {
 		return nil
 	}
-	if err := validateMCPRuntimeOptionSupport(runtimeKind, current.Options); err != nil {
-		return err
-	}
 	rt, err := s.runtimeForKind(runtimeKind)
 	if err != nil {
 		return err
@@ -595,6 +648,50 @@ func (s *Service) runtimeConfigRestartRequired(runtimeKind string, change agentr
 	return controller.RestartRequired(change)
 }
 
+func (s *Service) validateMCPConfig(ctx context.Context, runtimeKind string, current agentruntime.MCPConfigSnapshot) error {
+	if s == nil {
+		return fmt.Errorf("agent service is required")
+	}
+	if current.Config == nil {
+		return nil
+	}
+	runtimeKind = strings.TrimSpace(runtimeKind)
+	if runtimeKind == "" {
+		return nil
+	}
+	rt, err := s.runtimeForKind(runtimeKind)
+	if err != nil {
+		return err
+	}
+	controller, ok := rt.(agentruntime.MCPConfigController)
+	if !ok {
+		return fmt.Errorf("mcp_config is not supported for runtime_kind %q", runtimeKind)
+	}
+	return controller.ValidateMCPConfig(ctx, current)
+}
+
+func (s *Service) mcpConfigRestartRequired(runtimeKind string, change agentruntime.MCPConfigChange) (bool, error) {
+	if s == nil {
+		return false, fmt.Errorf("agent service is required")
+	}
+	if change.Previous.Config == nil && change.Current.Config == nil {
+		return false, nil
+	}
+	runtimeKind = strings.TrimSpace(runtimeKind)
+	if runtimeKind == "" {
+		return false, nil
+	}
+	rt, err := s.runtimeForKind(runtimeKind)
+	if err != nil {
+		return false, err
+	}
+	controller, ok := rt.(agentruntime.MCPConfigController)
+	if !ok {
+		return false, fmt.Errorf("mcp_config is not supported for runtime_kind %q", runtimeKind)
+	}
+	return controller.MCPConfigRestartRequired(change)
+}
+
 func (s *Service) reconcileRuntimeConfig(ctx context.Context, previous, current Agent) error {
 	if s == nil {
 		return fmt.Errorf("agent service is required")
@@ -616,6 +713,35 @@ func (s *Service) reconcileRuntimeConfig(ctx context.Context, previous, current
 	return controller.ReconcileConfig(ctx, runtimeHandleForAgent(current), runtimeConfigChangeForAgent(previous.AgentProfile, current.AgentProfile, previous.RuntimeOptions, current.RuntimeOptions))
 }
 
+func (s *Service) reconcileMCPConfig(ctx context.Context, previous, current Agent) error {
+	if s == nil {
+		return fmt.Errorf("agent service is required")
+	}
+	runtimeKind := strings.TrimSpace(current.RuntimeKind)
+	if runtimeKind == "" {
+		return nil
+	}
+	rt, err := s.runtimeForKind(runtimeKind)
+	if err != nil {
+		return err
+	}
+	controller, ok := rt.(agentruntime.MCPConfigController)
+	if !ok {
+		if current.MCPConfig == nil {
+			return nil
+		}
+		return fmt.Errorf("mcp_config is not supported for runtime_kind %q", runtimeKind)
+	}
+	return controller.ReconcileMCPConfig(ctx, runtimeHandleForAgent(current), mcpConfigChangeForAgent(previous.MCPConfig, current.MCPConfig))
+}
+
+func normalizeMCPConfig(config map[string]any) (map[string]any, error) {
+	if config == nil {
+		return nil, nil
+	}
+	return agentruntime.NormalizeMCPConfig(config)
+}
+
 func (s *Service) storedAPIKeyForModelRequest(req ProfileModelRequest, profile AgentProfile) string {
 	agentID := strings.TrimSpace(req.AgentID)
 	if s == nil || agentID == "" || profile.Provider != ProviderAPI {
@@ -702,6 +828,9 @@ func (s *Service) recreate(ctx context.Context, id string, imageFor func(context
 	if err := s.validateRuntimeConfig(ctx, strings.TrimSpace(got.RuntimeKind), runtimeConfigSnapshotForAgent(profile, got.RuntimeOptions)); err != nil {
 		return Agent{}, err
 	}
+	if err := s.validateMCPConfig(ctx, strings.TrimSpace(got.RuntimeKind), mcpConfigSnapshotForAgent(got.MCPConfig)); err != nil {
+		return Agent{}, err
+	}
 
 	runtimeImpl, err := s.runtimeForKind(strings.TrimSpace(got.RuntimeKind))
 	if err != nil {
@@ -779,6 +908,7 @@ func (s *Service) recreate(ctx context.Context, id string, imageFor func(context
 		AgentName:      createSpec.AgentName,
 		Profile:        runtimeProfile,
 		RuntimeOptions: utils.CloneAnyMap(got.RuntimeOptions),
+		MCPConfig:      utils.CloneAnyMap(got.MCPConfig),
 	}); err != nil {
 		return Agent{}, fmt.Errorf("provision agent runtime: %w", err)
 	}
diff --git a/internal/agent/service_test.go b/internal/agent/service_test.go
index d9c993b7..f1029a6e 100644
--- a/internal/agent/service_test.go
+++ b/internal/agent/service_test.go
@@ -114,21 +114,24 @@ func (f *fakeInstance) Close() error {
 }
 
 type fakeAgentRuntime struct {
-	kind       string
-	workspace  func(string) string
-	skills     func(string) string
-	hostLogs   func(string) []string
-	validate   func(context.Context, agentruntime.RuntimeConfigSnapshot) error
-	restart    func(agentruntime.RuntimeConfigChange) (bool, error)
-	reconcile  func(context.Context, agentruntime.Handle, agentruntime.RuntimeConfigChange) error
-	provision  func(context.Context, agentruntime.ProvisionRequest) error
-	new        func(context.Context, agentruntime.Spec) (agentruntime.Handle, error)
-	start      func(context.Context, agentruntime.Handle) (agentruntime.State, error)
-	stop       func(context.Context, agentruntime.Handle) (agentruntime.State, error)
-	del        func(context.Context, agentruntime.Handle) error
-	state      func(context.Context, agentruntime.Handle) (agentruntime.State, error)
-	info       func(context.Context, agentruntime.Handle) (agentruntime.Info, error)
-	streamLogs func(context.Context, agentruntime.Handle, agentruntime.LogOptions) error
+	kind         string
+	workspace    func(string) string
+	skills       func(string) string
+	hostLogs     func(string) []string
+	validate     func(context.Context, agentruntime.RuntimeConfigSnapshot) error
+	restart      func(agentruntime.RuntimeConfigChange) (bool, error)
+	reconcile    func(context.Context, agentruntime.Handle, agentruntime.RuntimeConfigChange) error
+	mcpValidate  func(context.Context, agentruntime.MCPConfigSnapshot) error
+	mcpRestart   func(agentruntime.MCPConfigChange) (bool, error)
+	mcpReconcile func(context.Context, agentruntime.Handle, agentruntime.MCPConfigChange) error
+	provision    func(context.Context, agentruntime.ProvisionRequest) error
+	new          func(context.Context, agentruntime.Spec) (agentruntime.Handle, error)
+	start        func(context.Context, agentruntime.Handle) (agentruntime.State, error)
+	stop         func(context.Context, agentruntime.Handle) (agentruntime.State, error)
+	del          func(context.Context, agentruntime.Handle) error
+	state        func(context.Context, agentruntime.Handle) (agentruntime.State, error)
+	info         func(context.Context, agentruntime.Handle) (agentruntime.Info, error)
+	streamLogs   func(context.Context, agentruntime.Handle, agentruntime.LogOptions) error
 }
 
 type fakeBareAgentRuntime struct {
@@ -247,6 +250,27 @@ func (f fakeAgentRuntime) ReconcileConfig(ctx context.Context, h agentruntime.Ha
 	return nil
 }
 
+func (f fakeAgentRuntime) ValidateMCPConfig(ctx context.Context, current agentruntime.MCPConfigSnapshot) error {
+	if f.mcpValidate != nil {
+		return f.mcpValidate(ctx, current)
+	}
+	return agentruntime.ValidateMCPConfig(current.Config)
+}
+
+func (f fakeAgentRuntime) MCPConfigRestartRequired(change agentruntime.MCPConfigChange) (bool, error) {
+	if f.mcpRestart != nil {
+		return f.mcpRestart(change)
+	}
+	return agentruntime.MCPConfigNeedsRestart(change.Previous.Config, change.Current.Config)
+}
+
+func (f fakeAgentRuntime) ReconcileMCPConfig(ctx context.Context, h agentruntime.Handle, change agentruntime.MCPConfigChange) error {
+	if f.mcpReconcile != nil {
+		return f.mcpReconcile(ctx, h, change)
+	}
+	return nil
+}
+
 func (f fakeAgentRuntime) Start(ctx context.Context, h agentruntime.Handle) (agentruntime.State, error) {
 	if f.start != nil {
 		return f.start(ctx, h)
@@ -1513,11 +1537,11 @@ func TestUpdateCodexLocalWorkspaceDirMarksRunningRuntimeForRestart(t *testing.T)
 	}
 }
 
-func TestUpdateOpenClawMCPRuntimeOptionsRecreatesAndProvisionsLatestOptions(t *testing.T) {
+func TestUpdateMCPConfigRecreatesOpenClawAndProvisionsLatestConfig(t *testing.T) {
 	t.Setenv("HOME", t.TempDir())
 
 	var provisionCalls []agentruntime.ProvisionRequest
-	reconcileCalls := 0
+	mcpReconcileCalls := 0
 	svc, err := NewService(
 		testModelConfig(),
 		config.ServerConfig{
@@ -1529,11 +1553,11 @@ func TestUpdateOpenClawMCPRuntimeOptionsRecreatesAndProvisionsLatestOptions(t *t
 		"",
 		WithRuntime(fakeAgentRuntime{
 			kind: RuntimeKindOpenClawSandbox,
-			restart: func(change agentruntime.RuntimeConfigChange) (bool, error) {
-				return !reflect.DeepEqual(change.Previous.Options["mcp"], change.Current.Options["mcp"]), nil
+			mcpRestart: func(change agentruntime.MCPConfigChange) (bool, error) {
+				return !reflect.DeepEqual(change.Previous.Config, change.Current.Config), nil
 			},
-			reconcile: func(context.Context, agentruntime.Handle, agentruntime.RuntimeConfigChange) error {
-				reconcileCalls++
+			mcpReconcile: func(context.Context, agentruntime.Handle, agentruntime.MCPConfigChange) error {
+				mcpReconcileCalls++
 				return nil
 			},
 			provision: func(_ context.Context, req agentruntime.ProvisionRequest) error {
@@ -1580,23 +1604,20 @@ func TestUpdateOpenClawMCPRuntimeOptionsRecreatesAndProvisionsLatestOptions(t *t
 		CreatedAt:       time.Date(2026, 5, 18, 9, 0, 0, 0, time.UTC),
 	}
 
-	nextRuntimeOptions := map[string]any{
-		"local_workspace_dir": "/tmp/keep",
-		"mcp": map[string]any{
-			"mcpServers": map[string]any{
-				"context7": map[string]any{
-					"command": "uvx",
-					"args":    []any{"context7-mcp"},
-				},
+	nextMCPConfig := map[string]any{
+		"mcpServers": map[string]any{
+			"context7": map[string]any{
+				"command": "uvx",
+				"args":    []any{"context7-mcp"},
 			},
 		},
 	}
-	updated, err := svc.Update(context.Background(), "u-alice", UpdateRequest{RuntimeOptions: &nextRuntimeOptions})
+	updated, err := svc.Update(context.Background(), "u-alice", UpdateRequest{MCPConfig: &nextMCPConfig, MCPConfigSet: true})
 	if err != nil {
 		t.Fatalf("Update() error = %v", err)
 	}
-	if reconcileCalls != 1 {
-		t.Fatalf("ReconcileConfig() calls = %d, want 1", reconcileCalls)
+	if mcpReconcileCalls != 1 {
+		t.Fatalf("ReconcileMCPConfig() calls = %d, want 1", mcpReconcileCalls)
 	}
 	if len(provisionCalls) != 1 {
 		t.Fatalf("Provision() calls = %d, want 1", len(provisionCalls))
@@ -1604,13 +1625,13 @@ func TestUpdateOpenClawMCPRuntimeOptionsRecreatesAndProvisionsLatestOptions(t *t
 	if got, want := provisionCalls[0].RuntimeOptions["local_workspace_dir"], "/tmp/keep"; got != want {
 		t.Fatalf("Provision().RuntimeOptions local_workspace_dir = %#v, want %q", got, want)
 	}
-	mcpRoot, ok := provisionCalls[0].RuntimeOptions["mcp"].(map[string]any)
-	if !ok {
-		t.Fatalf("Provision().RuntimeOptions[mcp] = %#v, want object", provisionCalls[0].RuntimeOptions["mcp"])
+	mcpRoot := provisionCalls[0].MCPConfig
+	if mcpRoot == nil {
+		t.Fatalf("Provision().MCPConfig = %#v, want object", provisionCalls[0].MCPConfig)
 	}
 	servers := mcpRoot["mcpServers"].(map[string]any)
 	if _, ok := servers["context7"]; !ok {
-		t.Fatalf("Provision().RuntimeOptions mcpServers = %#v, want context7", servers)
+		t.Fatalf("Provision().MCPConfig mcpServers = %#v, want context7", servers)
 	}
 	if updated.AgentProfile.EnvRestartRequired {
 		t.Fatal("Update().AgentProfile.EnvRestartRequired = true, want false after successful recreate")
@@ -1620,7 +1641,7 @@ func TestUpdateOpenClawMCPRuntimeOptionsRecreatesAndProvisionsLatestOptions(t *t
 	}
 }
 
-func TestUpdateOpenClawMCPRuntimeOptionsRecreateFailureKeepsRestartRequired(t *testing.T) {
+func TestUpdateMCPConfigRecreateFailureKeepsRestartRequired(t *testing.T) {
 	t.Setenv("HOME", t.TempDir())
 
 	svc, err := NewService(
@@ -1634,8 +1655,8 @@ func TestUpdateOpenClawMCPRuntimeOptionsRecreateFailureKeepsRestartRequired(t *t
 		"",
 		WithRuntime(fakeAgentRuntime{
 			kind: RuntimeKindOpenClawSandbox,
-			restart: func(change agentruntime.RuntimeConfigChange) (bool, error) {
-				return !reflect.DeepEqual(change.Previous.Options["mcp"], change.Current.Options["mcp"]), nil
+			mcpRestart: func(change agentruntime.MCPConfigChange) (bool, error) {
+				return !reflect.DeepEqual(change.Previous.Config, change.Current.Config), nil
 			},
 			provision: func(context.Context, agentruntime.ProvisionRequest) error {
 				return fmt.Errorf("provision failed")
@@ -1667,14 +1688,12 @@ func TestUpdateOpenClawMCPRuntimeOptionsRecreateFailureKeepsRestartRequired(t *t
 		CreatedAt:       time.Date(2026, 5, 18, 9, 0, 0, 0, time.UTC),
 	}
 
-	nextRuntimeOptions := map[string]any{
-		"mcp": map[string]any{
-			"mcpServers": map[string]any{
-				"context7": map[string]any{"command": "uvx"},
-			},
+	nextMCPConfig := map[string]any{
+		"mcpServers": map[string]any{
+			"context7": map[string]any{"command": "uvx"},
 		},
 	}
-	_, err = svc.Update(context.Background(), "u-alice", UpdateRequest{RuntimeOptions: &nextRuntimeOptions})
+	_, err = svc.Update(context.Background(), "u-alice", UpdateRequest{MCPConfig: &nextMCPConfig, MCPConfigSet: true})
 	if err == nil || !strings.Contains(err.Error(), "provision failed") {
 		t.Fatalf("Update() error = %v, want provision failed", err)
 	}
@@ -1685,15 +1704,15 @@ func TestUpdateOpenClawMCPRuntimeOptionsRecreateFailureKeepsRestartRequired(t *t
 	if !got.AgentProfile.EnvRestartRequired {
 		t.Fatal("Agent().AgentProfile.EnvRestartRequired = false, want true after failed recreate")
 	}
-	if _, ok := got.RuntimeOptions["mcp"].(map[string]any); !ok {
-		t.Fatalf("Agent().RuntimeOptions = %#v, want saved mcp config", got.RuntimeOptions)
+	if _, ok := got.MCPConfig["mcpServers"].(map[string]any); !ok {
+		t.Fatalf("Agent().MCPConfig = %#v, want saved mcp config", got.MCPConfig)
 	}
 	if got.BoxID != "openclaw-box-old" {
 		t.Fatalf("Agent().BoxID = %q, want old box id after failed recreate", got.BoxID)
 	}
 }
 
-func TestUpdateMCPRuntimeOptionsRejectsNonOpenClawRuntime(t *testing.T) {
+func TestUpdatePicoClawMCPConfigIsAccepted(t *testing.T) {
 	svc, err := NewService(
 		testModelConfig(),
 		config.ServerConfig{},
@@ -1720,13 +1739,83 @@ func TestUpdateMCPRuntimeOptionsRejectsNonOpenClawRuntime(t *testing.T) {
 	nextRuntimeOptions := map[string]any{
 		"mcp": map[string]any{"mcpServers": map[string]any{}},
 	}
-	_, err = svc.Update(context.Background(), "u-dev", UpdateRequest{RuntimeOptions: &nextRuntimeOptions})
-	if err == nil || !strings.Contains(err.Error(), `runtime_options.mcp is only supported`) {
-		t.Fatalf("Update() error = %v, want unsupported mcp runtime", err)
+	updated, err := svc.Update(context.Background(), "u-dev", UpdateRequest{RuntimeOptions: &nextRuntimeOptions})
+	if err != nil {
+		t.Fatalf("Update() error = %v", err)
+	}
+	if _, ok := updated.MCPConfig["mcpServers"].(map[string]any); !ok {
+		t.Fatalf("Update().MCPConfig = %#v, want managed empty config", updated.MCPConfig)
+	}
+}
+
+func TestUpdateRequestLegacyMCPRuntimeOptionsNullMarksMCPConfigClear(t *testing.T) {
+	var req UpdateRequest
+	if err := json.Unmarshal([]byte(`{"runtime_options":{"local_workspace_dir":"/tmp/project","mcp":null}}`), &req); err != nil {
+		t.Fatalf("json.Unmarshal(UpdateRequest) error = %v", err)
+	}
+	if !req.MCPConfigSet {
+		t.Fatal("UpdateRequest.MCPConfigSet = false, want true for legacy runtime_options.mcp null")
+	}
+	if req.MCPConfig != nil {
+		t.Fatalf("UpdateRequest.MCPConfig = %#v, want nil clear", *req.MCPConfig)
+	}
+	if req.RuntimeOptions == nil {
+		t.Fatal("UpdateRequest.RuntimeOptions = nil, want legacy mcp stripped options")
+	}
+	if _, ok := (*req.RuntimeOptions)[agentruntime.RuntimeOptionMCPKey]; ok {
+		t.Fatalf("UpdateRequest.RuntimeOptions still contains legacy mcp: %#v", *req.RuntimeOptions)
+	}
+}
+
+func TestUpdateLegacyMCPRuntimeOptionsNullClearsMCPConfig(t *testing.T) {
+	svc, err := NewService(
+		testModelConfig(),
+		config.ServerConfig{},
+		"manager-image:test",
+		"",
+		WithRuntime(fakeAgentRuntime{kind: RuntimeKindPicoClawSandbox}),
+	)
+	if err != nil {
+		t.Fatalf("NewService() error = %v", err)
+	}
+	svc.agents["u-dev"] = Agent{
+		ID:          "u-dev",
+		Name:        "dev",
+		RuntimeID:   "rt-u-dev",
+		RuntimeKind: RuntimeKindPicoClawSandbox,
+		Image:       "picoclaw-image:test",
+		Role:        RoleWorker,
+		Status:      "profile_incomplete",
+		RuntimeOptions: map[string]any{
+			"local_workspace_dir": "/tmp/project",
+		},
+		MCPConfig: map[string]any{
+			"mcpServers": map[string]any{
+				"context7": map[string]any{"command": "uvx"},
+			},
+		},
+		AgentProfile:    AgentProfile{Name: "dev"},
+		ProfileComplete: false,
+		CreatedAt:       time.Date(2026, 5, 18, 9, 0, 0, 0, time.UTC),
+	}
+
+	nextRuntimeOptions := map[string]any{
+		"local_workspace_dir": "/tmp/project",
+		"mcp":                 nil,
+	}
+	updated, err := svc.Update(context.Background(), "u-dev", UpdateRequest{RuntimeOptions: &nextRuntimeOptions})
+	if err != nil {
+		t.Fatalf("Update() error = %v", err)
+	}
+	if updated.MCPConfig != nil {
+		t.Fatalf("Update().MCPConfig = %#v, want nil after legacy mcp null", updated.MCPConfig)
+	}
+	if _, ok := updated.RuntimeOptions[agentruntime.RuntimeOptionMCPKey]; ok {
+		t.Fatalf("Update().RuntimeOptions still contains legacy mcp: %#v", updated.RuntimeOptions)
 	}
 }
 
-func TestCreateMCPRuntimeOptionsRejectsNonOpenClawRuntime(t *testing.T) {
+func TestUpdateLegacyMCPRuntimeOptionsRejectsInvalidRoot(t *testing.T) {
 	svc, err := NewService(
 		testModelConfig(),
 		config.ServerConfig{},
@@ -1737,8 +1826,39 @@ func TestCreateMCPRuntimeOptionsRejectsNonOpenClawRuntime(t *testing.T) {
 	if err != nil {
 		t.Fatalf("NewService() error = %v", err)
 	}
+	svc.agents["u-dev"] = Agent{
+		ID:              "u-dev",
+		Name:            "dev",
+		RuntimeID:       "rt-u-dev",
+		RuntimeKind:     RuntimeKindPicoClawSandbox,
+		Image:           "picoclaw-image:test",
+		Role:            RoleWorker,
+		Status:          "profile_incomplete",
+		AgentProfile:    AgentProfile{Name: "dev"},
+		ProfileComplete: false,
+		CreatedAt:       time.Date(2026, 5, 18, 9, 0, 0, 0, time.UTC),
+	}
 
-	_, err = svc.Create(context.Background(), CreateRequest{Spec: CreateAgentSpec{
+	runtimeOptions := map[string]any{"mcp": "invalid"}
+	_, err = svc.Update(context.Background(), "u-dev", UpdateRequest{RuntimeOptions: &runtimeOptions})
+	if err == nil || !strings.Contains(err.Error(), "runtime_options.mcp must be an object or null") {
+		t.Fatalf("Update() error = %v, want legacy mcp object error", err)
+	}
+}
+
+func TestCreatePicoClawMCPConfigIsAccepted(t *testing.T) {
+	svc, err := NewService(
+		testModelConfig(),
+		config.ServerConfig{},
+		"manager-image:test",
+		"",
+		WithRuntime(fakeAgentRuntime{kind: RuntimeKindPicoClawSandbox}),
+	)
+	if err != nil {
+		t.Fatalf("NewService() error = %v", err)
+	}
+
+	created, err := svc.Create(context.Background(), CreateRequest{Spec: CreateAgentSpec{
 		Name:        "dev",
 		Role:        RoleWorker,
 		RuntimeKind: RuntimeKindPicoClawSandbox,
@@ -1747,12 +1867,15 @@ func TestCreateMCPRuntimeOptionsRejectsNonOpenClawRuntime(t *testing.T) {
 			"mcp": map[string]any{"mcpServers": map[string]any{}},
 		},
 	}})
-	if err == nil || !strings.Contains(err.Error(), `runtime_options.mcp is only supported`) {
-		t.Fatalf("Create() error = %v, want unsupported mcp runtime", err)
+	if err != nil {
+		t.Fatalf("Create() error = %v", err)
+	}
+	if _, ok := created.MCPConfig["mcpServers"].(map[string]any); !ok {
+		t.Fatalf("Create().MCPConfig = %#v, want managed empty config", created.MCPConfig)
 	}
 }
 
-func TestReplaceRejectsInheritedMCPBeforeDeletingExistingAgent(t *testing.T) {
+func TestReplacePreservesInheritedMCPBeforeDeletingExistingAgent(t *testing.T) {
 	svc, err := NewService(
 		testModelConfig(),
 		config.ServerConfig{},
@@ -1770,10 +1893,11 @@ func TestReplaceRejectsInheritedMCPBeforeDeletingExistingAgent(t *testing.T) {
 		RuntimeID:   "rt-u-dev",
 		RuntimeKind: RuntimeKindOpenClawSandbox,
 		Image:       "openclaw-image:test",
+		BoxID:       "openclaw-box-old",
 		Role:        RoleWorker,
 		Status:      string(agentruntime.StateStopped),
-		RuntimeOptions: map[string]any{
-			"mcp": map[string]any{"mcpServers": map[string]any{"context7": map[string]any{"command": "uvx"}}},
+		MCPConfig: map[string]any{
+			"mcpServers": map[string]any{"context7": map[string]any{"command": "uvx"}},
 		},
 		AgentProfile: AgentProfile{
 			Name:            "dev",
@@ -1787,7 +1911,7 @@ func TestReplaceRejectsInheritedMCPBeforeDeletingExistingAgent(t *testing.T) {
 		CreatedAt:       time.Date(2026, 5, 18, 9, 0, 0, 0, time.UTC),
 	}
 
-	_, err = svc.Create(context.Background(), CreateRequest{
+	replaced, err := svc.Create(context.Background(), CreateRequest{
 		Replace:   true,
 		FieldMask: []string{"runtime_kind", "image"},
 		Spec: CreateAgentSpec{
@@ -1796,18 +1920,15 @@ func TestReplaceRejectsInheritedMCPBeforeDeletingExistingAgent(t *testing.T) {
 			Image:       "picoclaw-image:test",
 		},
 	})
-	if err == nil || !strings.Contains(err.Error(), `runtime_options.mcp is only supported`) {
-		t.Fatalf("Create(replace) error = %v, want unsupported mcp runtime", err)
-	}
-	got, ok := svc.Agent("u-dev")
-	if !ok {
-		t.Fatal("Agent(u-dev) ok = false, want existing agent preserved after failed replace")
+	if err != nil {
+		t.Fatalf("Create(replace) error = %v", err)
 	}
-	if got.RuntimeKind != RuntimeKindOpenClawSandbox {
-		t.Fatalf("Agent().RuntimeKind = %q, want original %q", got.RuntimeKind, RuntimeKindOpenClawSandbox)
+	if replaced.RuntimeKind != RuntimeKindPicoClawSandbox {
+		t.Fatalf("Create(replace).RuntimeKind = %q, want %q", replaced.RuntimeKind, RuntimeKindPicoClawSandbox)
 	}
-	if _, ok := got.RuntimeOptions["mcp"].(map[string]any); !ok {
-		t.Fatalf("Agent().RuntimeOptions = %#v, want original mcp preserved", got.RuntimeOptions)
+	servers, _ := replaced.MCPConfig["mcpServers"].(map[string]any)
+	if _, ok := servers["context7"]; !ok {
+		t.Fatalf("Create(replace).MCPConfig = %#v, want inherited context7", replaced.MCPConfig)
 	}
 }
 
@@ -1844,19 +1965,17 @@ func TestReplaceRejectsInvalidOpenClawMCPBeforeDeletingExistingAgent(t *testing.
 
 	_, err = svc.Create(context.Background(), CreateRequest{
 		Replace:   true,
-		FieldMask: []string{"runtime_options"},
+		FieldMask: []string{"mcp_config"},
 		Spec: CreateAgentSpec{
 			ID: "u-dev",
-			RuntimeOptions: map[string]any{
-				"mcp": map[string]any{
-					"servers": map[string]any{
-						"context7": map[string]any{"command": "uvx"},
-					},
+			MCPConfig: map[string]any{
+				"servers": map[string]any{
+					"context7": map[string]any{"command": "uvx"},
 				},
 			},
 		},
 	})
-	if err == nil || !strings.Contains(err.Error(), `runtime_options.mcp contains unsupported field`) {
+	if err == nil || !strings.Contains(err.Error(), `mcp_config contains unsupported field`) {
 		t.Fatalf("Create(replace) error = %v, want unsupported mcp field", err)
 	}
 	svc.mu.RLock()
diff --git a/internal/agent/store.go b/internal/agent/store.go
index 0e4de23c..dbcc5f6a 100644
--- a/internal/agent/store.go
+++ b/internal/agent/store.go
@@ -77,6 +77,7 @@ type persistedAgent struct {
 	BoxID            string                   `json:"box_id,omitempty"`
 	Runtime          *RuntimeRecord           `json:"runtime,omitempty"`
 	RuntimeOptions   map[string]any           `json:"-"`
+	MCPConfig        map[string]any           `json:"-"`
 	Role             string                   `json:"role"`
 	Status           string                   `json:"status,omitempty"`
 	CreatedAt        time.Time                `json:"created_at"`
@@ -132,6 +133,9 @@ func (a persistedAgent) MarshalJSON() ([]byte, error) {
 	if !profileEmpty(profile) {
 		out["model_config"] = profile
 	}
+	if len(a.MCPConfig) > 0 {
+		out["mcp_config"] = a.MCPConfig
+	}
 	if len(a.DetectionResults) > 0 {
 		out["detection_results"] = a.DetectionResults
 	}
@@ -145,6 +149,7 @@ func (a *persistedAgent) UnmarshalJSON(data []byte) error {
 		ModelConfig    json.RawMessage `json:"model_config"`
 		Profile        json.RawMessage `json:"profile"`
 		RuntimeOptions map[string]any  `json:"runtime_options"`
+		MCPConfig      map[string]any  `json:"mcp_config"`
 	}
 	var decoded persistedAgentJSON
 	if err := json.Unmarshal(data, &decoded); err != nil {
@@ -152,6 +157,7 @@ func (a *persistedAgent) UnmarshalJSON(data []byte) error {
 	}
 	*a = persistedAgent(decoded.persistedAgentAlias)
 	a.RuntimeOptions = utils.CloneAnyMap(decoded.RuntimeOptions)
+	a.MCPConfig = utils.CloneAnyMap(decoded.MCPConfig)
 	profilePayload := decoded.ModelConfig
 	if len(profilePayload) == 0 || string(profilePayload) == "null" {
 		profilePayload = decoded.Profile
@@ -172,6 +178,7 @@ func (a *persistedAgent) UnmarshalJSON(data []byte) error {
 	if a.Runtime != nil && len(a.Runtime.Options) > 0 && len(a.RuntimeOptions) == 0 {
 		a.RuntimeOptions = utils.CloneAnyMap(a.Runtime.Options)
 	}
+	a.RuntimeOptions, a.MCPConfig = splitLegacyRuntimeOptionsMCP(a.RuntimeOptions, a.MCPConfig)
 	return nil
 }
 
@@ -198,6 +205,7 @@ func newPersistedAgent(a Agent) persistedAgent {
 	if len(a.RuntimeOptions) > 0 {
 		topRX = utils.CloneAnyMap(a.RuntimeOptions)
 	}
+	topRX, mcpConfig := splitLegacyRuntimeOptionsMCP(topRX, a.MCPConfig)
 	ap.BaseURL, ap.ModelID = pol.StripProfileLLMFields(a.RuntimeKind, ap.BaseURL, ap.ModelID)
 	ap = compactPersistedProfile(ap)
 	updatedAt := a.UpdatedAt.UTC()
@@ -212,6 +220,7 @@ func newPersistedAgent(a Agent) persistedAgent {
 		Image:            a.Image,
 		Runtime:          compactPersistedRuntime(runtimeRecordForAgent(a), topRX),
 		RuntimeOptions:   topRX,
+		MCPConfig:        mcpConfig,
 		Role:             a.Role,
 		CreatedAt:        a.CreatedAt,
 		UpdatedAt:        updatedAt,
@@ -226,6 +235,7 @@ func (a persistedAgent) toAgent() Agent {
 		ap = cloneProfile(a.AgentProfile)
 	}
 	rx := utils.CloneAnyMap(a.RuntimeOptions)
+	mcpConfig := utils.CloneAnyMap(a.MCPConfig)
 	if strings.TrimSpace(ap.Name) == "" {
 		ap.Name = a.Name
 	}
@@ -269,6 +279,7 @@ func (a persistedAgent) toAgent() Agent {
 			rx = utils.CloneAnyMap(rt.Options)
 		}
 	}
+	rx, mcpConfig = splitLegacyRuntimeOptionsMCP(rx, mcpConfig)
 	runtimeCfg := agentruntime.RuntimeConfigForKind(runtimeKind)
 	ag := Agent{
 		ID:               a.ID,
@@ -283,6 +294,7 @@ func (a persistedAgent) toAgent() Agent {
 		Avatar:           a.Avatar,
 		BoxID:            boxID,
 		RuntimeOptions:   rx,
+		MCPConfig:        mcpConfig,
 		Role:             a.Role,
 		Status:           status,
 		CreatedAt:        a.CreatedAt,
diff --git a/internal/api/handler.go b/internal/api/handler.go
index 0ad97bde..344c2afe 100644
--- a/internal/api/handler.go
+++ b/internal/api/handler.go
@@ -151,6 +151,7 @@ type agentResponse struct {
 	Profile              string                             `json:"-"`
 	ProfileConfig        apitypes.AgentProfile              `json:"model_config,omitempty"`
 	RuntimeOptions       map[string]any                     `json:"-"`
+	MCPConfig            map[string]any                     `json:"mcp_config,omitempty"`
 	RuntimeOptionSchemas []agentruntime.RuntimeOptionSchema `json:"-"`
 	AgentProfile         agent.AgentProfileView             `json:"-"`
 	ProfileComplete      bool                               `json:"-"`
@@ -185,6 +186,7 @@ func (r *agentResponse) UnmarshalJSON(data []byte) error {
 		Profile:          apiAgent.Profile,
 		ProfileConfig:    apiAgent.ProfileConfig,
 		RuntimeOptions:   apiAgent.Runtime.Options,
+		MCPConfig:        utils.CloneAnyMap(apiAgent.MCPConfig),
 		AgentProfile:     agentProfileViewFromAPI(apiAgent.ProfileConfig),
 		UserID:           apiAgent.UserID,
 		UserName:         apiAgent.UserName,
@@ -210,6 +212,7 @@ func (r *agentResponse) UnmarshalJSON(data []byte) error {
 		BoxID                string                             `json:"box_id"`
 		Status               string                             `json:"status"`
 		RuntimeOptions       map[string]any                     `json:"runtime_options"`
+		MCPConfig            map[string]any                     `json:"mcp_config"`
 		RuntimeOptionSchemas []agentruntime.RuntimeOptionSchema `json:"runtime_option_schemas"`
 		AgentProfile         agent.AgentProfileView             `json:"agent_profile"`
 		ProfileComplete      bool                               `json:"profile_complete"`
@@ -242,6 +245,9 @@ func (r *agentResponse) UnmarshalJSON(data []byte) error {
 	if len(legacy.RuntimeOptions) > 0 {
 		r.RuntimeOptions = legacy.RuntimeOptions
 	}
+	if len(legacy.MCPConfig) > 0 {
+		r.MCPConfig = legacy.MCPConfig
+	}
 	if len(legacy.RuntimeOptionSchemas) > 0 {
 		r.RuntimeOptionSchemas = legacy.RuntimeOptionSchemas
 	}
@@ -1263,6 +1269,7 @@ func agentCreateRequestFromAPI(req apitypes.CreateAgentRequest) agent.CreateRequ
 			UpdatedAt:      req.CreatedAt,
 			Profile:        req.Profile,
 			RuntimeOptions: runtimeOptions,
+			MCPConfig:      utils.CloneAnyMapShallowNestedStringMaps(req.MCPConfig),
 			AgentProfile:   prof,
 		},
 		Replace:   req.Replace,
@@ -2712,6 +2719,7 @@ func presentAgent(item agent.Agent) agentResponse {
 		UpdatedAt:        item.UpdatedAt,
 		Profile:          item.Profile,
 		RuntimeOptions:   runtimeOptions,
+		MCPConfig:        utils.CloneAnyMap(item.MCPConfig),
 		ProfileConfig:    profile,
 		AgentProfile:     av,
 		ProfileComplete:  item.ProfileComplete,
diff --git a/internal/api/handler_test.go b/internal/api/handler_test.go
index aeee409a..e768fb74 100644
--- a/internal/api/handler_test.go
+++ b/internal/api/handler_test.go
@@ -170,6 +170,45 @@ func (f fakeConversationRuntime) NewConversation(ctx context.Context, handle age
 	}, nil
 }
 
+type apiFakeCodexBinaryProvider struct{}
+
+func (apiFakeCodexBinaryProvider) Ensure(context.Context) (string, error) {
+	return "/tmp/codex", nil
+}
+
+type apiFakeCodexManager struct{}
+
+func (apiFakeCodexManager) Start(_ context.Context, spec codexruntime.SessionSpec) (*codexruntime.Session, error) {
+	now := time.Now().UTC()
+	return &codexruntime.Session{
+		RuntimeID:    spec.RuntimeID,
+		AgentID:      spec.AgentID,
+		AgentName:    spec.AgentName,
+		SessionID:    "session-" + spec.AgentID,
+		BinaryPath:   spec.BinaryPath,
+		RuntimeDir:   spec.RuntimeDir,
+		WorkspaceDir: spec.WorkspaceDir,
+		HomeDir:      spec.HomeDir,
+		CodexHomeDir: spec.CodexHomeDir,
+		StderrPath:   spec.StderrPath,
+		ProcessID:    os.Getpid(),
+		CreatedAt:    now,
+		StartedAt:    now,
+	}, nil
+}
+
+func (apiFakeCodexManager) Stop(context.Context, codexruntime.SessionHandle) error {
+	return nil
+}
+
+func (apiFakeCodexManager) Session(codexruntime.SessionHandle) (*codexruntime.Session, error) {
+	return nil, os.ErrNotExist
+}
+
+func (apiFakeCodexManager) Prompt(context.Context, codexruntime.SessionHandle, codexruntime.PromptRequest) (codexruntime.PromptResponse, error) {
+	return codexruntime.PromptResponse{}, os.ErrNotExist
+}
+
 type fakeCodexBridgeController struct {
 	ensureCalls []agent.Agent
 	stopCalls   []string
@@ -2004,6 +2043,420 @@ func TestHandleAgentsCreateCodexWorkerEnsuresCodexBridge(t *testing.T) {
 	}
 }
 
+func TestHandleAgentsMCPConfigClosedLoopForSupportedRuntimes(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Cleanup(agent.TestOnlySetSandboxProvider(sandboxtest.NewProvider()))
+
+	codexRoot := t.TempDir()
+	codexHomes := map[string]string{}
+	statePath := filepath.Join(t.TempDir(), "agents.json")
+	codexRT := codexruntime.New(codexruntime.Dependencies{
+		BinaryProvider: apiFakeCodexBinaryProvider{},
+		AgentHome: func(agentID string) (string, error) {
+			home := filepath.Join(codexRoot, agentID)
+			codexHomes[agentID] = home
+			return home, nil
+		},
+		ResolveAgent: func(h agentruntime.Handle) (codexruntime.AgentRef, error) {
+			return codexAgentRefFromStateFile(statePath, h.RuntimeID, agentruntime.Profile{
+				Provider: agent.ProviderAPI,
+				BaseURL:  "https://llm.example/v1",
+				APIKey:   "sk-test",
+				ModelID:  "model-1",
+			})
+		},
+		Manager: apiFakeCodexManager{},
+	})
+
+	svc, err := agent.NewService(
+		config.ModelConfig{
+			Provider: config.ProviderLLMAPI,
+			BaseURL:  "https://llm.example/v1",
+			APIKey:   "sk-default",
+			ModelID:  "model-default",
+		},
+		config.ServerConfig{
+			ListenAddr:       "127.0.0.1:18080",
+			AdvertiseBaseURL: "http://127.0.0.1:18080",
+			AccessToken:      "shared-token",
+		},
+		"manager-image:test",
+		statePath,
+		agent.WithRuntime(codexRT),
+	)
+	if err != nil {
+		t.Fatalf("NewService() error = %v", err)
+	}
+	srv := &Handler{svc: svc, im: im.NewService()}
+
+	mcpConfig := map[string]any{
+		"mcpServers": map[string]any{
+			"context7": map[string]any{
+				"command": "uvx",
+				"args":    []any{"context7-mcp"},
+				"env": map[string]any{
+					"CONTEXT7_API_KEY": "secret",
+				},
+			},
+			"remote": map[string]any{
+				"url":                  "https://mcp.example.com/mcp",
+				"bearer_token_env_var": "MCP_TOKEN",
+			},
+		},
+	}
+
+	tests := []struct {
+		name        string
+		id          string
+		agentName   string
+		runtimeKind string
+		image       string
+		assertFile  func(t *testing.T, created agentResponse)
+	}{
+		{
+			name:        "openclaw",
+			id:          "u-openclawmcp",
+			agentName:   "openclawmcp",
+			runtimeKind: agent.RuntimeKindOpenClawSandbox,
+			image:       "openclaw-image:test",
+			assertFile: func(t *testing.T, created agentResponse) {
+				t.Helper()
+				home := testAgentHomeFromStatePath(statePath, created.ID)
+				cfg := readJSONMap(t, filepath.Join(openclawsandbox.Root(home), openclawsandbox.HostConfig))
+				mcpRoot, ok := cfg["mcp"].(map[string]any)
+				if !ok {
+					t.Fatalf("openclaw config missing mcp object: %+v", cfg["mcp"])
+				}
+				assertMCPServers(t, mcpRoot["servers"])
+			},
+		},
+		{
+			name:        "picoclaw",
+			id:          "u-picoclawmcp",
+			agentName:   "picoclawmcp",
+			runtimeKind: agent.RuntimeKindPicoClawSandbox,
+			image:       "picoclaw-image:test",
+			assertFile: func(t *testing.T, created agentResponse) {
+				t.Helper()
+				home := testAgentHomeFromStatePath(statePath, created.ID)
+				cfg := readJSONMap(t, filepath.Join(picoclawsandbox.Root(home), picoclawsandbox.HostConfig))
+				tools, ok := cfg["tools"].(map[string]any)
+				if !ok {
+					t.Fatalf("picoclaw config missing tools object: %+v", cfg["tools"])
+				}
+				mcpRoot, ok := tools["mcp"].(map[string]any)
+				if !ok {
+					t.Fatalf("picoclaw config missing tools.mcp object: %+v", tools["mcp"])
+				}
+				if enabled, _ := mcpRoot["enabled"].(bool); !enabled {
+					t.Fatalf("picoclaw tools.mcp.enabled = %v, want true", mcpRoot["enabled"])
+				}
+				assertMCPServers(t, mcpRoot["servers"])
+			},
+		},
+		{
+			name:        "codex",
+			id:          "u-codexmcp",
+			agentName:   "codexmcp",
+			runtimeKind: agent.RuntimeKindCodex,
+			assertFile: func(t *testing.T, created agentResponse) {
+				t.Helper()
+				home := codexHomes[agent.CanonicalID(created.ID)]
+				if strings.TrimSpace(home) == "" {
+					t.Fatalf("codex agent home for %s was not resolved", created.ID)
+				}
+				configPath := filepath.Join(home, ".codex", "home", "config.toml")
+				raw, err := os.ReadFile(configPath)
+				if err != nil {
+					t.Fatalf("read codex config %s: %v", configPath, err)
+				}
+				configText := string(raw)
+				for _, want := range []string{
+					`# BEGIN csgclaw-managed mcp`,
+					`[mcp_servers."context7"]`,
+					`command = "uvx"`,
+					`args = ["context7-mcp"]`,
+					`env = { "CONTEXT7_API_KEY" = "secret" }`,
+					`[mcp_servers."remote"]`,
+					`url = "https://mcp.example.com/mcp"`,
+					`bearer_token_env_var = "MCP_TOKEN"`,
+					`# END csgclaw-managed mcp`,
+				} {
+					if !strings.Contains(configText, want) {
+						t.Fatalf("codex config missing %q:\n%s", want, configText)
+					}
+				}
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			createBody := map[string]any{
+				"id":           tt.id,
+				"name":         tt.agentName,
+				"role":         agent.RoleWorker,
+				"runtime_kind": tt.runtimeKind,
+				"agent_profile": map[string]any{
+					"model_provider_id": "e2e-api",
+					"base_url":          "https://llm.example/v1",
+					"api_key":           "sk-test",
+					"model_id":          "model-1",
+				},
+			}
+			if tt.image != "" {
+				createBody["image"] = tt.image
+			}
+			created := doAgentJSON(t, srv, http.MethodPost, "/api/v1/agents", createBody, http.StatusCreated)
+			wantRuntime := agentruntime.RuntimeConfigForKind(tt.runtimeKind)
+			if created.RuntimeName != wantRuntime.Name || created.SandboxEnabled != wantRuntime.Sandboxed {
+				t.Fatalf("created runtime = %q/%t, want %q/%t", created.RuntimeName, created.SandboxEnabled, wantRuntime.Name, wantRuntime.Sandboxed)
+			}
+
+			updated := doAgentJSON(t, srv, http.MethodPatch, "/api/v1/agents/"+created.ID, map[string]any{
+				"field_mask": []string{"mcp_config"},
+				"mcp_config": mcpConfig,
+			}, http.StatusOK)
+			assertMCPConfigResponse(t, updated.MCPConfig)
+			if _, ok := updated.RuntimeOptions[agentruntime.RuntimeOptionMCPKey]; ok {
+				t.Fatalf("runtime_options contains legacy %q after mcp_config patch: %+v", agentruntime.RuntimeOptionMCPKey, updated.RuntimeOptions)
+			}
+			tt.assertFile(t, updated)
+		})
+	}
+}
+
+func doAgentJSON(t *testing.T, srv *Handler, method, path string, body any, wantStatus int) agentResponse {
+	t.Helper()
+	raw, err := json.Marshal(body)
+	if err != nil {
+		t.Fatalf("marshal request body: %v", err)
+	}
+	req := httptest.NewRequest(method, path, bytes.NewReader(raw))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+
+	srv.Routes().ServeHTTP(rec, req)
+
+	if rec.Code != wantStatus {
+		t.Fatalf("%s %s status = %d, want %d; body=%s", method, path, rec.Code, wantStatus, rec.Body.String())
+	}
+	var got agentResponse
+	if err := json.NewDecoder(rec.Body).Decode(&got); err != nil {
+		t.Fatalf("decode response: %v; body=%s", err, rec.Body.String())
+	}
+	return got
+}
+
+func testAgentHomeFromStatePath(statePath, agentID string) string {
+	return filepath.Join(filepath.Dir(statePath), "agents", agent.CanonicalID(agentID))
+}
+
+func codexAgentRefFromStateFile(path, runtimeID string, fallback agentruntime.Profile) (codexruntime.AgentRef, error) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return codexruntime.AgentRef{}, err
+	}
+	var state struct {
+		Agents []struct {
+			ID             string               `json:"id"`
+			Name           string               `json:"name"`
+			Instructions   string               `json:"instructions,omitempty"`
+			RuntimeID      string               `json:"runtime_id,omitempty"`
+			RuntimeKind    string               `json:"runtime_kind,omitempty"`
+			BoxID          string               `json:"box_id,omitempty"`
+			Runtime        *agent.RuntimeRecord `json:"runtime,omitempty"`
+			RuntimeOptions map[string]any       `json:"runtime_options,omitempty"`
+			MCPConfig      map[string]any       `json:"mcp_config,omitempty"`
+			ModelConfig    agent.AgentProfile   `json:"model_config,omitempty"`
+			AgentProfile   agent.AgentProfile   `json:"agent_profile,omitempty"`
+		} `json:"agents"`
+		Items []struct {
+			ID             string               `json:"id"`
+			Name           string               `json:"name"`
+			Instructions   string               `json:"instructions,omitempty"`
+			RuntimeID      string               `json:"runtime_id,omitempty"`
+			RuntimeKind    string               `json:"runtime_kind,omitempty"`
+			BoxID          string               `json:"box_id,omitempty"`
+			Runtime        *agent.RuntimeRecord `json:"runtime,omitempty"`
+			RuntimeOptions map[string]any       `json:"runtime_options,omitempty"`
+			MCPConfig      map[string]any       `json:"mcp_config,omitempty"`
+			ModelConfig    agent.AgentProfile   `json:"model_config,omitempty"`
+			AgentProfile   agent.AgentProfile   `json:"agent_profile,omitempty"`
+		} `json:"items"`
+	}
+	if err := json.Unmarshal(raw, &state); err != nil {
+		return codexruntime.AgentRef{}, err
+	}
+	type stateAgent struct {
+		ID             string
+		Name           string
+		Instructions   string
+		RuntimeID      string
+		RuntimeKind    string
+		BoxID          string
+		Runtime        *agent.RuntimeRecord
+		RuntimeOptions map[string]any
+		MCPConfig      map[string]any
+		ModelConfig    agent.AgentProfile
+		AgentProfile   agent.AgentProfile
+	}
+	items := make([]stateAgent, 0, len(state.Agents)+len(state.Items))
+	for _, item := range state.Agents {
+		items = append(items, stateAgent{
+			ID:             item.ID,
+			Name:           item.Name,
+			Instructions:   item.Instructions,
+			RuntimeID:      item.RuntimeID,
+			RuntimeKind:    item.RuntimeKind,
+			BoxID:          item.BoxID,
+			Runtime:        item.Runtime,
+			RuntimeOptions: item.RuntimeOptions,
+			MCPConfig:      item.MCPConfig,
+			ModelConfig:    item.ModelConfig,
+			AgentProfile:   item.AgentProfile,
+		})
+	}
+	for _, item := range state.Items {
+		items = append(items, stateAgent{
+			ID:             item.ID,
+			Name:           item.Name,
+			Instructions:   item.Instructions,
+			RuntimeID:      item.RuntimeID,
+			RuntimeKind:    item.RuntimeKind,
+			BoxID:          item.BoxID,
+			Runtime:        item.Runtime,
+			RuntimeOptions: item.RuntimeOptions,
+			MCPConfig:      item.MCPConfig,
+			ModelConfig:    item.ModelConfig,
+			AgentProfile:   item.AgentProfile,
+		})
+	}
+	for _, item := range items {
+		rtID := strings.TrimSpace(item.RuntimeID)
+		options := item.RuntimeOptions
+		boxID := strings.TrimSpace(item.BoxID)
+		if item.Runtime != nil {
+			if strings.TrimSpace(item.Runtime.ID) != "" {
+				rtID = strings.TrimSpace(item.Runtime.ID)
+			}
+			if len(options) == 0 && len(item.Runtime.Options) > 0 {
+				options = item.Runtime.Options
+			}
+			if boxID == "" {
+				boxID = strings.TrimSpace(item.Runtime.SandboxID)
+			}
+		}
+		if rtID == "" && strings.TrimSpace(item.ID) != "" {
+			rtID = "rt-" + strings.TrimSpace(item.ID)
+		}
+		if rtID != strings.TrimSpace(runtimeID) {
+			continue
+		}
+		profile := fallback.Normalized()
+		rawProfile := item.ModelConfig
+		if profileEmptyForTest(rawProfile) {
+			rawProfile = item.AgentProfile
+		}
+		if providerID := strings.TrimSpace(rawProfile.ModelProviderID); providerID != "" {
+			profile.Provider = agent.ProfileProviderForModelProviderID(providerID)
+		}
+		if provider := strings.TrimSpace(rawProfile.Provider); provider != "" {
+			profile.Provider = provider
+		}
+		if baseURL := strings.TrimRight(strings.TrimSpace(rawProfile.BaseURL), "/"); baseURL != "" {
+			profile.BaseURL = baseURL
+		}
+		if apiKey := strings.TrimSpace(rawProfile.APIKey); apiKey != "" {
+			profile.APIKey = apiKey
+		}
+		if modelID := strings.TrimSpace(rawProfile.ModelID); modelID != "" {
+			profile.ModelID = modelID
+		}
+		if reasoning := strings.TrimSpace(rawProfile.ReasoningEffort); reasoning != "" {
+			profile.ReasoningEffort = reasoning
+		}
+		if len(rawProfile.Env) > 0 {
+			profile.Env = rawProfile.Env
+		}
+		return codexruntime.AgentRef{
+			ID:             item.ID,
+			Name:           item.Name,
+			RuntimeID:      rtID,
+			HandleID:       boxID,
+			Instructions:   item.Instructions,
+			RuntimeOptions: options,
+			MCPConfig:      item.MCPConfig,
+			Profile:        profile,
+		}, nil
+	}
+	return codexruntime.AgentRef{}, os.ErrNotExist
+}
+
+func profileEmptyForTest(profile agent.AgentProfile) bool {
+	return strings.TrimSpace(profile.Provider) == "" &&
+		strings.TrimSpace(profile.ModelProviderID) == "" &&
+		strings.TrimSpace(profile.BaseURL) == "" &&
+		strings.TrimSpace(profile.APIKey) == "" &&
+		strings.TrimSpace(profile.ModelID) == "" &&
+		strings.TrimSpace(profile.ReasoningEffort) == "" &&
+		len(profile.Env) == 0
+}
+
+func readJSONMap(t *testing.T, path string) map[string]any {
+	t.Helper()
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read %s: %v", path, err)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(raw, &got); err != nil {
+		t.Fatalf("decode %s: %v\n%s", path, err, string(raw))
+	}
+	return got
+}
+
+func assertMCPConfigResponse(t *testing.T, cfg map[string]any) {
+	t.Helper()
+	if len(cfg) == 0 {
+		t.Fatal("response missing mcp_config")
+	}
+	assertMCPServers(t, cfg[agentruntime.MCPConfigServersKey])
+}
+
+func assertMCPServers(t *testing.T, raw any) {
+	t.Helper()
+	servers, ok := raw.(map[string]any)
+	if !ok {
+		t.Fatalf("MCP servers = %#v, want object", raw)
+	}
+	context7, ok := servers["context7"].(map[string]any)
+	if !ok {
+		t.Fatalf("MCP servers missing context7: %+v", servers)
+	}
+	if command, _ := context7["command"].(string); command != "uvx" {
+		t.Fatalf("context7.command = %q, want uvx", command)
+	}
+	args, ok := context7["args"].([]any)
+	if !ok || len(args) != 1 || args[0] != "context7-mcp" {
+		t.Fatalf("context7.args = %#v, want [context7-mcp]", context7["args"])
+	}
+	env, ok := context7["env"].(map[string]any)
+	if !ok || env["CONTEXT7_API_KEY"] != "secret" {
+		t.Fatalf("context7.env = %#v, want CONTEXT7_API_KEY", context7["env"])
+	}
+	remote, ok := servers["remote"].(map[string]any)
+	if !ok {
+		t.Fatalf("MCP servers missing remote: %+v", servers)
+	}
+	if url, _ := remote["url"].(string); url != "https://mcp.example.com/mcp" {
+		t.Fatalf("remote.url = %q, want https://mcp.example.com/mcp", url)
+	}
+	if envVar, _ := remote["bearer_token_env_var"].(string); envVar != "MCP_TOKEN" {
+		t.Fatalf("remote.bearer_token_env_var = %q, want MCP_TOKEN", envVar)
+	}
+}
+
 func TestHandleAgentsCreateManagerUsesBootstrapManager(t *testing.T) {
 	t.Setenv("HOME", t.TempDir())
 	t.Cleanup(agent.TestOnlySetSandboxProvider(sandboxtest.NewProvider()))
diff --git a/internal/apitypes/agent.go b/internal/apitypes/agent.go
index 4984a81c..81019d87 100644
--- a/internal/apitypes/agent.go
+++ b/internal/apitypes/agent.go
@@ -72,29 +72,30 @@ type ProfileDetectionResult struct {
 }
 
 type Agent struct {
-	ID               string        `json:"id"`
-	Name             string        `json:"name"`
-	Description      string        `json:"description,omitempty"`
-	Instructions     string        `json:"instructions,omitempty"`
-	Runtime          AgentRuntime  `json:"runtime,omitempty"`
-	RuntimeID        string        `json:"-"`
-	RuntimeKind      string        `json:"-"`
-	RuntimeName      string        `json:"runtime_name,omitempty"`
-	SandboxEnabled   bool          `json:"sandbox_enabled,omitempty"`
-	Image            string        `json:"image,omitempty"`
-	Avatar           string        `json:"-"`
-	BoxID            string        `json:"-"`
-	Role             string        `json:"role"`
-	Status           string        `json:"-"`
-	CreatedAt        time.Time     `json:"created_at"`
-	UpdatedAt        time.Time     `json:"updated_at,omitempty"`
-	Profile          string        `json:"-"`
-	ProfileConfig    AgentProfile  `json:"model_config,omitempty"`
-	UserID           string        `json:"user_id,omitempty"`
-	UserName         string        `json:"user_name,omitempty"`
-	ParticipantIDs   []string      `json:"participant_ids,omitempty"`
-	ParticipantNames []string      `json:"participant_names,omitempty"`
-	Participants     []Participant `json:"participants,omitempty"`
+	ID               string         `json:"id"`
+	Name             string         `json:"name"`
+	Description      string         `json:"description,omitempty"`
+	Instructions     string         `json:"instructions,omitempty"`
+	Runtime          AgentRuntime   `json:"runtime,omitempty"`
+	RuntimeID        string         `json:"-"`
+	RuntimeKind      string         `json:"-"`
+	RuntimeName      string         `json:"runtime_name,omitempty"`
+	SandboxEnabled   bool           `json:"sandbox_enabled,omitempty"`
+	MCPConfig        map[string]any `json:"mcp_config,omitempty"`
+	Image            string         `json:"image,omitempty"`
+	Avatar           string         `json:"-"`
+	BoxID            string         `json:"-"`
+	Role             string         `json:"role"`
+	Status           string         `json:"-"`
+	CreatedAt        time.Time      `json:"created_at"`
+	UpdatedAt        time.Time      `json:"updated_at,omitempty"`
+	Profile          string         `json:"-"`
+	ProfileConfig    AgentProfile   `json:"model_config,omitempty"`
+	UserID           string         `json:"user_id,omitempty"`
+	UserName         string         `json:"user_name,omitempty"`
+	ParticipantIDs   []string       `json:"participant_ids,omitempty"`
+	ParticipantNames []string       `json:"participant_names,omitempty"`
+	Participants     []Participant  `json:"participants,omitempty"`
 }
 
 func (a *Agent) UnmarshalJSON(data []byte) error {
@@ -139,6 +140,7 @@ func (a *Agent) UnmarshalJSON(data []byte) error {
 		Status         string         `json:"status"`
 		BoxID          string         `json:"box_id"`
 		RuntimeOptions map[string]any `json:"runtime_options"`
+		MCPConfig      map[string]any `json:"mcp_config"`
 	}
 	if err := json.Unmarshal(data, &legacy); err != nil {
 		return err
@@ -173,6 +175,9 @@ func (a *Agent) UnmarshalJSON(data []byte) error {
 	if len(a.Runtime.Options) == 0 && len(legacy.RuntimeOptions) > 0 {
 		a.Runtime.Options = legacy.RuntimeOptions
 	}
+	if len(a.MCPConfig) == 0 && len(legacy.MCPConfig) > 0 {
+		a.MCPConfig = legacy.MCPConfig
+	}
 	if strings.TrimSpace(a.RuntimeName) == "" {
 		a.RuntimeName = strings.TrimSpace(a.Runtime.Name)
 	}
@@ -229,6 +234,7 @@ type CreateAgentRequest struct {
 	CreatedAt      time.Time           `json:"created_at,omitempty"`
 	Runtime        AgentRuntime        `json:"runtime,omitempty"`
 	RuntimeOptions map[string]any      `json:"runtime_options,omitempty"`
+	MCPConfig      map[string]any      `json:"mcp_config,omitempty"`
 	Profile        string              `json:"-"`
 	ProfileConfig  *CreateAgentProfile `json:"model_config,omitempty"`
 	AgentProfile   *CreateAgentProfile `json:"agent_profile,omitempty"`
@@ -251,6 +257,7 @@ func (r CreateAgentRequest) MarshalJSON() ([]byte, error) {
 		CreatedAt      time.Time           `json:"created_at,omitempty"`
 		Runtime        AgentRuntime        `json:"runtime,omitempty"`
 		RuntimeOptions map[string]any      `json:"runtime_options,omitempty"`
+		MCPConfig      map[string]any      `json:"mcp_config,omitempty"`
 		ModelConfig    *CreateAgentProfile `json:"model_config,omitempty"`
 		Profile        string              `json:"profile,omitempty"`
 		AgentProfile   *CreateAgentProfile `json:"agent_profile,omitempty"`
@@ -288,6 +295,7 @@ func (r CreateAgentRequest) MarshalJSON() ([]byte, error) {
 		CreatedAt:      r.CreatedAt,
 		Runtime:        runtime,
 		RuntimeOptions: r.RuntimeOptions,
+		MCPConfig:      r.MCPConfig,
 		ModelConfig:    r.ProfileConfig,
 		Profile:        profile,
 		AgentProfile:   r.AgentProfile,
@@ -303,6 +311,7 @@ func (r *CreateAgentRequest) UnmarshalJSON(data []byte) error {
 		RuntimeName    string              `json:"runtime_name,omitempty"`
 		SandboxEnabled *bool               `json:"sandbox_enabled,omitempty"`
 		RuntimeOptions map[string]any      `json:"runtime_options,omitempty"`
+		MCPConfig      map[string]any      `json:"mcp_config,omitempty"`
 		ModelConfig    *CreateAgentProfile `json:"model_config,omitempty"`
 		AgentProfile   *CreateAgentProfile `json:"agent_profile,omitempty"`
 		Runtime        struct {
@@ -321,6 +330,7 @@ func (r *CreateAgentRequest) UnmarshalJSON(data []byte) error {
 	r.RuntimeKind = strings.TrimSpace(decoded.RuntimeKind)
 	r.RuntimeName = strings.TrimSpace(decoded.RuntimeName)
 	r.RuntimeOptions = decoded.RuntimeOptions
+	r.MCPConfig = decoded.MCPConfig
 	r.ProfileConfig = decoded.ModelConfig
 	r.AgentProfile = decoded.AgentProfile
 	r.Runtime.Kind = strings.TrimSpace(decoded.Runtime.Kind)
diff --git a/internal/apitypes/types.go b/internal/apitypes/types.go
index eae41c28..9f99a319 100644
--- a/internal/apitypes/types.go
+++ b/internal/apitypes/types.go
@@ -16,6 +16,7 @@ type LegacyBot struct {
 	UserID               string         `json:"user_id"`
 	Available            bool           `json:"available"`
 	RuntimeOptions       map[string]any `json:"runtime_options,omitempty"`
+	MCPConfig            map[string]any `json:"mcp_config,omitempty"`
 	RuntimeKind          string         `json:"runtime_kind,omitempty"`
 	Image                string         `json:"image,omitempty"`
 	Avatar               string         `json:"avatar,omitempty"`
diff --git a/internal/app/runtimewiring/codex.go b/internal/app/runtimewiring/codex.go
index 0b674629..bc84643c 100644
--- a/internal/app/runtimewiring/codex.go
+++ b/internal/app/runtimewiring/codex.go
@@ -37,6 +37,7 @@ func WithCodexRuntime() agent.ServiceOption {
 					HandleID:       strings.TrimSpace(got.BoxID),
 					Instructions:   got.Instructions,
 					RuntimeOptions: got.RuntimeOptions,
+					MCPConfig:      got.MCPConfig,
 					Profile:        profile,
 				}, nil
 			},
diff --git a/internal/participant/store.go b/internal/participant/store.go
index 96e30e43..5be523bd 100644
--- a/internal/participant/store.go
+++ b/internal/participant/store.go
@@ -721,6 +721,9 @@ func isLegacyCSGClawManagerBot(b apitypes.LegacyBot, typ, channel, agentID strin
 
 func legacyBotMetadata(b apitypes.LegacyBot) map[string]any {
 	metadata := cloneAnyMap(b.RuntimeOptions)
+	if len(b.MCPConfig) > 0 {
+		metadata["mcp_config"] = cloneAnyMap(b.MCPConfig)
+	}
 	putMetadataString(metadata, "description", b.Description)
 	putMetadataString(metadata, "legacy_bot_type", b.Type)
 	putMetadataString(metadata, "legacy_role", b.Role)
diff --git a/internal/runtime/codex/config_controller.go b/internal/runtime/codex/config_controller.go
index 0e9d50e4..4213c49d 100644
--- a/internal/runtime/codex/config_controller.go
+++ b/internal/runtime/codex/config_controller.go
@@ -62,6 +62,26 @@ func (r *Runtime) ReconcileConfig(ctx context.Context, h agentruntime.Handle, ch
 	return r.RefreshCodexHomeAgentsFile(ctx, h)
 }
 
+func (r *Runtime) ValidateMCPConfig(_ context.Context, current agentruntime.MCPConfigSnapshot) error {
+	return agentruntime.ValidateMCPConfig(current.Config)
+}
+
+func (r *Runtime) MCPConfigRestartRequired(change agentruntime.MCPConfigChange) (bool, error) {
+	return agentruntime.MCPConfigNeedsRestart(change.Previous.Config, change.Current.Config)
+}
+
+func (r *Runtime) ReconcileMCPConfig(_ context.Context, h agentruntime.Handle, _ agentruntime.MCPConfigChange) error {
+	agentRef, err := r.resolveAgent(h)
+	if err != nil {
+		return err
+	}
+	codexHomeDir, err := r.resolveCodexHomeDir(agentRef.ID)
+	if err != nil {
+		return err
+	}
+	return r.seedCodexHomeConfig(codexHomeDir, agentRef.Profile.Normalized(), agentRef.MCPConfig)
+}
+
 type responsesProbeTargetConfig struct {
 	provider string
 	baseURL  string
diff --git a/internal/runtime/codex/runtime.go b/internal/runtime/codex/runtime.go
index 74cec0bf..5619e88c 100644
--- a/internal/runtime/codex/runtime.go
+++ b/internal/runtime/codex/runtime.go
@@ -41,6 +41,7 @@ type AgentRef struct {
 	HandleID       string
 	Instructions   string
 	RuntimeOptions map[string]any
+	MCPConfig      map[string]any
 	Profile        agentruntime.Profile
 }
 
@@ -136,6 +137,7 @@ var (
 	_ agentruntime.ConversationStarter         = (*Runtime)(nil)
 	_ agentruntime.RuntimeOptionSchemaProvider = (*Runtime)(nil)
 	_ agentruntime.RuntimeConfigController     = (*Runtime)(nil)
+	_ agentruntime.MCPConfigController         = (*Runtime)(nil)
 )
 
 func New(deps Dependencies) *Runtime {
@@ -410,7 +412,7 @@ func (r *Runtime) ensureSession(ctx context.Context, spec SessionSpec) (*Session
 	if err := r.seedCodexHomeAuth(spec.CodexHomeDir); err != nil {
 		return nil, err
 	}
-	if err := r.seedCodexHomeConfig(spec.CodexHomeDir, spec.Profile); err != nil {
+	if err := r.seedCodexHomeConfig(spec.CodexHomeDir, spec.Profile, agentRef.MCPConfig); err != nil {
 		return nil, err
 	}
 	if err := r.seedCodexHomeSkills(spec.CodexHomeDir); err != nil {
@@ -494,7 +496,7 @@ func (r *Runtime) hydratePersistedSession(ctx context.Context, manager *appServe
 	if err := r.seedCodexHomeAuth(spec.CodexHomeDir); err != nil {
 		return nil, err
 	}
-	if err := r.seedCodexHomeConfig(spec.CodexHomeDir, spec.Profile); err != nil {
+	if err := r.seedCodexHomeConfig(spec.CodexHomeDir, spec.Profile, agentRef.MCPConfig); err != nil {
 		return nil, err
 	}
 	if err := r.seedCodexHomeSkills(spec.CodexHomeDir); err != nil {
@@ -562,11 +564,14 @@ func (r *Runtime) seedCodexHomeAuth(runtimeCodexHome string) error {
 	return nil
 }
 
-func (r *Runtime) seedCodexHomeConfig(runtimeCodexHome string, profile agentruntime.Profile) error {
+func (r *Runtime) seedCodexHomeConfig(runtimeCodexHome string, profile agentruntime.Profile, mcpConfig map[string]any) error {
 	runtimeCodexHome = strings.TrimSpace(runtimeCodexHome)
 	if runtimeCodexHome == "" {
 		return fmt.Errorf("codex home dir is required")
 	}
+	if err := agentruntime.ValidateMCPConfig(mcpConfig); err != nil {
+		return err
+	}
 	configPath := filepath.Join(runtimeCodexHome, configFileName)
 	profile = profile.Normalized()
 	configRaw, err := r.readFile(configPath)
@@ -588,7 +593,7 @@ func (r *Runtime) seedCodexHomeConfig(runtimeCodexHome string, profile agentrunt
 		}
 	}
 
-	rendered := configureCodexHomeConfig(string(configRaw), profile)
+	rendered := configureCodexHomeConfig(string(configRaw), profile, mcpConfig)
 	if err := r.writeFile(configPath, []byte(rendered), 0o600); err != nil {
 		return fmt.Errorf("write runtime codex config %s: %w", configPath, err)
 	}
diff --git a/internal/runtime/codex/runtime_config.go b/internal/runtime/codex/runtime_config.go
index 407f41de..4fe62b9d 100644
--- a/internal/runtime/codex/runtime_config.go
+++ b/internal/runtime/codex/runtime_config.go
@@ -5,6 +5,7 @@ import (
 	"os"
 	"path/filepath"
 	"regexp"
+	"sort"
 	"strconv"
 	"strings"
 
@@ -22,6 +23,8 @@ const (
 	csgclawMemoryFeatureEndMarker   = "# END csgclaw-managed memory-feature"
 	csgclawMemoryConfigBeginMarker  = "# BEGIN csgclaw-managed memory-config (do not edit; regenerated by runtime)"
 	csgclawMemoryConfigEndMarker    = "# END csgclaw-managed memory-config"
+	csgclawMCPBeginMarker           = "# BEGIN csgclaw-managed mcp (do not edit; regenerated by runtime)"
+	csgclawMCPEndMarker             = "# END csgclaw-managed mcp"
 )
 
 var (
@@ -127,7 +130,60 @@ func buildMemoryConfigBlock(inMemoriesTable bool) string {
 	return b.String()
 }
 
-func configureCodexHomeConfig(existing string, profile agentruntime.Profile) string {
+func buildMCPConfigBlock(mcpConfig map[string]any) (string, error) {
+	servers, err := agentruntime.MCPConfigServers(mcpConfig)
+	if err != nil {
+		return "", err
+	}
+	if servers == nil {
+		return "", nil
+	}
+
+	names := make([]string, 0, len(servers))
+	for name := range servers {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	var b strings.Builder
+	b.WriteString(csgclawMCPBeginMarker)
+	b.WriteString("\n")
+	for idx, name := range names {
+		entry, ok := servers[name].(map[string]any)
+		if !ok {
+			return "", fmt.Errorf("mcp_config.%s.%s must be an object", agentruntime.MCPConfigServersKey, name)
+		}
+		if idx > 0 {
+			b.WriteString("\n")
+		}
+		fmt.Fprintf(&b, "[mcp_servers.%s]\n", tomlQuotedKey(name))
+		if url := mcpTrimmedString(entry["url"]); url != "" {
+			fmt.Fprintf(&b, "url = %s\n", strconv.Quote(url))
+			for _, key := range []string{"bearer_token_env_var", "oauth_client_id", "oauth_resource"} {
+				if value := mcpTrimmedString(entry[key]); value != "" {
+					fmt.Fprintf(&b, "%s = %s\n", key, strconv.Quote(value))
+				}
+			}
+			continue
+		}
+		command := mcpTrimmedString(entry["command"])
+		if command == "" {
+			return "", fmt.Errorf("mcp_config.%s.%s must declare command or url", agentruntime.MCPConfigServersKey, name)
+		}
+		fmt.Fprintf(&b, "command = %s\n", strconv.Quote(command))
+		if args := mcpStringSlice(entry["args"]); len(args) > 0 {
+			fmt.Fprintf(&b, "args = %s\n", tomlStringArray(args))
+		}
+		if env := mcpStringMap(entry["env"]); len(env) > 0 {
+			fmt.Fprintf(&b, "env = %s\n", tomlInlineStringMap(env))
+		}
+	}
+	b.WriteString(csgclawMCPEndMarker)
+	b.WriteString("\n")
+	return b.String(), nil
+}
+
+func configureCodexHomeConfig(existing string, profile agentruntime.Profile, mcpConfig map[string]any) string {
 	content := sanitizeCopiedCodexConfigContent(existing)
 	content = strings.TrimLeft(content, "\n")
 
@@ -136,6 +192,7 @@ func configureCodexHomeConfig(existing string, profile agentruntime.Profile) str
 	content = stripManagedBlock(content, csgclawMultiAgentBeginMarker, csgclawMultiAgentEndMarker)
 	content = stripManagedBlock(content, csgclawMemoryFeatureBeginMarker, csgclawMemoryFeatureEndMarker)
 	content = stripManagedBlock(content, csgclawMemoryConfigBeginMarker, csgclawMemoryConfigEndMarker)
+	content = stripManagedBlock(content, csgclawMCPBeginMarker, csgclawMCPEndMarker)
 
 	content = stripLegacySandboxDirectives(content)
 	content = stripUserMultiAgentDirectives(content)
@@ -166,6 +223,9 @@ func configureCodexHomeConfig(existing string, profile agentruntime.Profile) str
 	if block := buildProviderConfigBlock(profile); block != "" {
 		content = hoistManagedBlock(content, block)
 	}
+	if block, err := buildMCPConfigBlock(mcpConfig); err == nil && block != "" {
+		content = hoistManagedBlock(content, block)
+	}
 
 	content = strings.TrimLeft(content, "\n")
 	if strings.TrimSpace(content) == "" {
@@ -174,6 +234,68 @@ func configureCodexHomeConfig(existing string, profile agentruntime.Profile) str
 	return strings.TrimRight(content, "\n") + "\n"
 }
 
+func mcpTrimmedString(value any) string {
+	text, _ := value.(string)
+	return strings.TrimSpace(text)
+}
+
+func mcpStringSlice(value any) []string {
+	raw, ok := value.([]any)
+	if !ok {
+		return nil
+	}
+	out := make([]string, 0, len(raw))
+	for _, item := range raw {
+		text, ok := item.(string)
+		if !ok {
+			return nil
+		}
+		out = append(out, text)
+	}
+	return out
+}
+
+func mcpStringMap(value any) map[string]string {
+	raw, ok := value.(map[string]any)
+	if !ok {
+		return nil
+	}
+	out := make(map[string]string, len(raw))
+	for key, item := range raw {
+		text, ok := item.(string)
+		if !ok {
+			return nil
+		}
+		out[key] = text
+	}
+	return out
+}
+
+func tomlQuotedKey(key string) string {
+	return strconv.Quote(strings.TrimSpace(key))
+}
+
+func tomlStringArray(values []string) string {
+	quoted := make([]string, 0, len(values))
+	for _, value := range values {
+		quoted = append(quoted, strconv.Quote(value))
+	}
+	return "[" + strings.Join(quoted, ", ") + "]"
+}
+
+func tomlInlineStringMap(values map[string]string) string {
+	keys := make([]string, 0, len(values))
+	for key := range values {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	items := make([]string, 0, len(keys))
+	for _, key := range keys {
+		items = append(items, strconv.Quote(key)+" = "+strconv.Quote(values[key]))
+	}
+	return "{ " + strings.Join(items, ", ") + " }"
+}
+
 func sanitizeCopiedCodexConfigContent(content string) string {
 	if !strings.Contains(content, "[[skills.config]]") {
 		return content
diff --git a/internal/runtime/codex/runtime_test.go b/internal/runtime/codex/runtime_test.go
index d28420e0..8bbb6b96 100644
--- a/internal/runtime/codex/runtime_test.go
+++ b/internal/runtime/codex/runtime_test.go
@@ -1400,8 +1400,8 @@ func TestConfigureCodexHomeConfigReplacesManagedBlocksIdempotently(t *testing.T)
 		BaseURL: "https://runtime.example/v1",
 		APIKey:  "runtime-key",
 	}
-	first := configureCodexHomeConfig(initial, profile)
-	second := configureCodexHomeConfig(first, profile)
+	first := configureCodexHomeConfig(initial, profile, nil)
+	second := configureCodexHomeConfig(first, profile, nil)
 	if first != second {
 		t.Fatalf("configureCodexHomeConfig should be idempotent\nfirst:\n%s\nsecond:\n%s", first, second)
 	}
@@ -1439,7 +1439,7 @@ func TestConfigureCodexHomeConfigReplacesManagedBlocksIdempotently(t *testing.T)
 func TestConfigureCodexHomeConfigIncompleteProfileSkipsProvider(t *testing.T) {
 	config := configureCodexHomeConfig("approval_policy = \"manual\"\n", agentruntime.Profile{
 		BaseURL: "https://runtime.example/v1",
-	})
+	}, nil)
 	if strings.Contains(config, csgclawProviderBeginMarker) {
 		t.Fatalf("config should skip provider block for incomplete profile:\n%s", config)
 	}
@@ -1456,6 +1456,41 @@ func TestConfigureCodexHomeConfigIncompleteProfileSkipsProvider(t *testing.T) {
 	}
 }
 
+func TestConfigureCodexHomeConfigRendersMCPServers(t *testing.T) {
+	config := configureCodexHomeConfig("approval_policy = \"manual\"\n", agentruntime.Profile{}, map[string]any{
+		"mcpServers": map[string]any{
+			"context7": map[string]any{
+				"command": "uvx",
+				"args":    []any{"context7-mcp"},
+				"env": map[string]any{
+					"CONTEXT7_API_KEY": "secret",
+				},
+			},
+			"remote": map[string]any{
+				"url":                  "https://mcp.example.com/mcp",
+				"bearer_token_env_var": "MCP_TOKEN",
+			},
+		},
+	})
+
+	for _, want := range []string{
+		csgclawMCPBeginMarker,
+		`[mcp_servers."context7"]`,
+		`command = "uvx"`,
+		`args = ["context7-mcp"]`,
+		`env = { "CONTEXT7_API_KEY" = "secret" }`,
+		`[mcp_servers."remote"]`,
+		`url = "https://mcp.example.com/mcp"`,
+		`bearer_token_env_var = "MCP_TOKEN"`,
+		csgclawMCPEndMarker,
+		`approval_policy = "manual"`,
+	} {
+		if !strings.Contains(config, want) {
+			t.Fatalf("config missing %q:\n%s", want, config)
+		}
+	}
+}
+
 func TestRuntimeCreateAlwaysWritesResponsesConfig(t *testing.T) {
 	root := t.TempDir()
 	rt := New(Dependencies{
diff --git a/internal/runtime/mcp_config.go b/internal/runtime/mcp_config.go
new file mode 100644
index 00000000..3000c614
--- /dev/null
+++ b/internal/runtime/mcp_config.go
@@ -0,0 +1,307 @@
+package runtime
+
+import (
+	"context"
+	"fmt"
+	"reflect"
+	"sort"
+	"strings"
+)
+
+const MCPConfigServersKey = "mcpServers"
+
+type MCPConfigSnapshot struct {
+	Config map[string]any
+}
+
+type MCPConfigChange struct {
+	Previous MCPConfigSnapshot
+	Current  MCPConfigSnapshot
+}
+
+type MCPConfigController interface {
+	ValidateMCPConfig(ctx context.Context, current MCPConfigSnapshot) error
+	MCPConfigRestartRequired(change MCPConfigChange) (bool, error)
+	ReconcileMCPConfig(ctx context.Context, h Handle, change MCPConfigChange) error
+}
+
+type MCPConfigMode int
+
+const (
+	MCPConfigAbsent MCPConfigMode = iota
+	MCPConfigManaged
+)
+
+type MCPConfig struct {
+	Mode    MCPConfigMode
+	Servers map[string]any
+}
+
+func NormalizeMCPConfig(raw map[string]any) (map[string]any, error) {
+	parsed, err := DecodeMCPConfig(raw, "mcp_config")
+	if err != nil {
+		return nil, err
+	}
+	if parsed.Mode == MCPConfigAbsent {
+		return nil, nil
+	}
+	servers := parsed.Servers
+	if servers == nil {
+		servers = map[string]any{}
+	}
+	return map[string]any{MCPConfigServersKey: servers}, nil
+}
+
+func ValidateMCPConfig(raw map[string]any) error {
+	_, err := DecodeMCPConfig(raw, "mcp_config")
+	return err
+}
+
+func MCPConfigServers(raw map[string]any) (map[string]any, error) {
+	parsed, err := DecodeMCPConfig(raw, "mcp_config")
+	if err != nil {
+		return nil, err
+	}
+	if parsed.Mode != MCPConfigManaged {
+		return nil, nil
+	}
+	if parsed.Servers == nil {
+		return map[string]any{}, nil
+	}
+	return parsed.Servers, nil
+}
+
+func MCPConfigNeedsRestart(previous, current map[string]any) (bool, error) {
+	prev, prevErr := DecodeMCPConfig(previous, "mcp_config")
+	next, err := DecodeMCPConfig(current, "mcp_config")
+	if err != nil {
+		return false, err
+	}
+	if prevErr != nil {
+		return true, nil
+	}
+	return !reflect.DeepEqual(MCPConfigEffectiveServers(prev), MCPConfigEffectiveServers(next)), nil
+}
+
+func MCPConfigEffectiveServers(config MCPConfig) map[string]any {
+	if config.Mode != MCPConfigManaged {
+		return nil
+	}
+	if config.Servers == nil {
+		return map[string]any{}
+	}
+	return config.Servers
+}
+
+func UpdateJSONMCPServers(cfg map[string]any, raw map[string]any) error {
+	servers, err := MCPConfigServers(raw)
+	if err != nil {
+		return err
+	}
+	if servers == nil {
+		mcpRoot, ok := cfg["mcp"].(map[string]any)
+		if !ok {
+			return nil
+		}
+		delete(mcpRoot, "servers")
+		if len(mcpRoot) == 0 {
+			delete(cfg, "mcp")
+		}
+		return nil
+	}
+	mcpRoot, _ := cfg["mcp"].(map[string]any)
+	if mcpRoot == nil {
+		mcpRoot = map[string]any{}
+		cfg["mcp"] = mcpRoot
+	}
+	mcpRoot["servers"] = servers
+	return nil
+}
+
+func DecodeMCPConfig(raw map[string]any, path string) (MCPConfig, error) {
+	path = strings.TrimSpace(path)
+	if path == "" {
+		path = "mcp_config"
+	}
+	if raw == nil {
+		return MCPConfig{Mode: MCPConfigAbsent}, nil
+	}
+	if unsupported := unsupportedMCPRootKeys(raw); len(unsupported) > 0 {
+		return MCPConfig{}, fmt.Errorf("%s contains unsupported field(s) %q; only %s is supported", path, strings.Join(unsupported, ", "), MCPConfigServersKey)
+	}
+	if len(raw) == 0 {
+		return MCPConfig{Mode: MCPConfigManaged, Servers: map[string]any{}}, nil
+	}
+	rawServers, ok := raw[MCPConfigServersKey]
+	if !ok {
+		return MCPConfig{Mode: MCPConfigManaged, Servers: map[string]any{}}, nil
+	}
+	serverMap, ok := rawServers.(map[string]any)
+	if !ok {
+		return MCPConfig{}, fmt.Errorf("%s.%s must be an object", path, MCPConfigServersKey)
+	}
+	servers := make(map[string]any, len(serverMap))
+	for rawName, rawEntry := range serverMap {
+		name := strings.TrimSpace(rawName)
+		if name == "" {
+			return MCPConfig{}, fmt.Errorf("%s.%s contains an empty server name", path, MCPConfigServersKey)
+		}
+		if _, exists := servers[name]; exists {
+			return MCPConfig{}, fmt.Errorf("%s.%s contains duplicate server name %q", path, MCPConfigServersKey, name)
+		}
+		entry, ok := rawEntry.(map[string]any)
+		if !ok {
+			return MCPConfig{}, fmt.Errorf("%s.%s.%s must be an object", path, MCPConfigServersKey, name)
+		}
+		normalized, err := normalizeMCPServerEntry(path, name, entry)
+		if err != nil {
+			return MCPConfig{}, err
+		}
+		servers[name] = normalized
+	}
+	return MCPConfig{Mode: MCPConfigManaged, Servers: servers}, nil
+}
+
+func unsupportedMCPRootKeys(root map[string]any) []string {
+	out := make([]string, 0)
+	for key := range root {
+		if key != MCPConfigServersKey {
+			out = append(out, key)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+func normalizeMCPServerEntry(path, name string, entry map[string]any) (map[string]any, error) {
+	normalized, ok := cloneMCPJSONObject(entry).(map[string]any)
+	if !ok {
+		return nil, fmt.Errorf("%s.%s.%s must be an object", path, MCPConfigServersKey, name)
+	}
+	command, hasCommand, err := mcpStringField(normalized, "command")
+	if err != nil {
+		return nil, fmt.Errorf("%s.%s.%s.command %s", path, MCPConfigServersKey, name, err)
+	}
+	url, hasURL, err := mcpStringField(normalized, "url")
+	if err != nil {
+		return nil, fmt.Errorf("%s.%s.%s.url %s", path, MCPConfigServersKey, name, err)
+	}
+	if !hasCommand && !hasURL {
+		return nil, fmt.Errorf("%s.%s.%s must declare command or url", path, MCPConfigServersKey, name)
+	}
+	if hasCommand {
+		normalized["command"] = command
+	} else {
+		delete(normalized, "command")
+	}
+	if hasURL {
+		normalized["url"] = url
+	} else {
+		delete(normalized, "url")
+	}
+	if err := validateMCPStringSliceField(normalized, "args"); err != nil {
+		return nil, fmt.Errorf("%s.%s.%s.args must be an array of strings", path, MCPConfigServersKey, name)
+	}
+	if err := validateMCPStringMapField(normalized, "env"); err != nil {
+		return nil, fmt.Errorf("%s.%s.%s.env must be an object with string values", path, MCPConfigServersKey, name)
+	}
+	if err := validateMCPStringMapField(normalized, "headers"); err != nil {
+		return nil, fmt.Errorf("%s.%s.%s.headers must be an object with string values", path, MCPConfigServersKey, name)
+	}
+	if err := validateMCPStringField(normalized, "transport"); err != nil {
+		return nil, fmt.Errorf("%s.%s.%s.transport must be a string", path, MCPConfigServersKey, name)
+	}
+	return normalized, nil
+}
+
+func mcpStringField(values map[string]any, key string) (string, bool, error) {
+	raw, ok := values[key]
+	if !ok || raw == nil {
+		return "", false, nil
+	}
+	text, ok := raw.(string)
+	if !ok {
+		return "", false, fmt.Errorf("must be a string")
+	}
+	text = strings.TrimSpace(text)
+	if text == "" {
+		return "", false, fmt.Errorf("must not be blank")
+	}
+	return text, true, nil
+}
+
+func validateMCPStringField(values map[string]any, key string) error {
+	raw, ok := values[key]
+	if !ok || raw == nil {
+		return nil
+	}
+	if _, ok := raw.(string); !ok {
+		return fmt.Errorf("not a string")
+	}
+	return nil
+}
+
+func validateMCPStringSliceField(values map[string]any, key string) error {
+	raw, ok := values[key]
+	if !ok || raw == nil {
+		return nil
+	}
+	items, ok := raw.([]any)
+	if !ok {
+		return fmt.Errorf("not an array")
+	}
+	for _, item := range items {
+		if _, ok := item.(string); !ok {
+			return fmt.Errorf("contains non-string value")
+		}
+	}
+	return nil
+}
+
+func validateMCPStringMapField(values map[string]any, key string) error {
+	raw, ok := values[key]
+	if !ok || raw == nil {
+		return nil
+	}
+	items, ok := raw.(map[string]any)
+	if !ok {
+		return fmt.Errorf("not an object")
+	}
+	for _, value := range items {
+		if _, ok := value.(string); !ok {
+			return fmt.Errorf("contains non-string value")
+		}
+	}
+	return nil
+}
+
+func cloneMCPJSONObject(value any) any {
+	switch typed := value.(type) {
+	case map[string]any:
+		out := make(map[string]any, len(typed))
+		for key, item := range typed {
+			out[key] = cloneMCPJSONObject(item)
+		}
+		return out
+	case map[string]string:
+		out := make(map[string]any, len(typed))
+		for key, item := range typed {
+			out[key] = item
+		}
+		return out
+	case []any:
+		out := make([]any, len(typed))
+		for idx, item := range typed {
+			out[idx] = cloneMCPJSONObject(item)
+		}
+		return out
+	case []string:
+		out := make([]any, len(typed))
+		for idx, item := range typed {
+			out[idx] = item
+		}
+		return out
+	default:
+		return value
+	}
+}
diff --git a/internal/runtime/openclawsandbox/config.go b/internal/runtime/openclawsandbox/config.go
index f55b8515..50dcc813 100644
--- a/internal/runtime/openclawsandbox/config.go
+++ b/internal/runtime/openclawsandbox/config.go
@@ -12,6 +12,7 @@ import (
 	"csgclaw/internal/channel/feishu"
 	"csgclaw/internal/config"
 	"csgclaw/internal/modelcap"
+	agentruntime "csgclaw/internal/runtime"
 )
 
 //go:embed defaults/openclaw-gateway.json
@@ -49,15 +50,23 @@ func HostGatewayLogPath(agentHome string) string {
 }
 
 func EnsureConfig(agentHome, participantID, agentID string, server config.ServerConfig, model config.ModelConfig, resolveBaseURL BaseURLResolver, feishuProvider feishu.AgentCredentialProvider) (string, error) {
-	return EnsureConfigWithRuntimeOptions(agentHome, participantID, agentID, server, model, nil, resolveBaseURL, feishuProvider)
+	return EnsureConfigWithMCPConfig(agentHome, participantID, agentID, server, model, nil, resolveBaseURL, feishuProvider)
 }
 
 func EnsureConfigWithRuntimeOptions(agentHome, participantID, agentID string, server config.ServerConfig, model config.ModelConfig, runtimeOptions map[string]any, resolveBaseURL BaseURLResolver, feishuProvider feishu.AgentCredentialProvider) (string, error) {
+	mcpConfig, err := mcpConfigFromLegacyRuntimeOptions(runtimeOptions)
+	if err != nil {
+		return "", err
+	}
+	return EnsureConfigWithMCPConfig(agentHome, participantID, agentID, server, model, mcpConfig, resolveBaseURL, feishuProvider)
+}
+
+func EnsureConfigWithMCPConfig(agentHome, participantID, agentID string, server config.ServerConfig, model config.ModelConfig, mcpConfig map[string]any, resolveBaseURL BaseURLResolver, feishuProvider feishu.AgentCredentialProvider) (string, error) {
 	hostRoot := Root(agentHome)
 	if err := os.MkdirAll(hostRoot, 0o755); err != nil {
 		return "", fmt.Errorf("create openclaw config dir: %w", err)
 	}
-	data, err := renderConfigWithRuntimeOptions(participantID, agentID, server, model, runtimeOptions, resolveBaseURL, feishuProvider)
+	data, err := renderConfigWithMCPConfig(participantID, agentID, server, model, mcpConfig, resolveBaseURL, feishuProvider)
 	if err != nil {
 		return "", err
 	}
@@ -147,10 +156,18 @@ func updateOpenClawWorkspaceDefault(cfg map[string]any, workspace string) {
 	defaults["workspace"] = workspace
 }
 func renderConfig(participantID, agentID string, server config.ServerConfig, model config.ModelConfig, resolveBaseURL BaseURLResolver, feishuProvider feishu.AgentCredentialProvider) ([]byte, error) {
-	return renderConfigWithRuntimeOptions(participantID, agentID, server, model, nil, resolveBaseURL, feishuProvider)
+	return renderConfigWithMCPConfig(participantID, agentID, server, model, nil, resolveBaseURL, feishuProvider)
 }
 
 func renderConfigWithRuntimeOptions(participantID, agentID string, server config.ServerConfig, model config.ModelConfig, runtimeOptions map[string]any, resolveBaseURL BaseURLResolver, feishuProvider feishu.AgentCredentialProvider) ([]byte, error) {
+	mcpConfig, err := mcpConfigFromLegacyRuntimeOptions(runtimeOptions)
+	if err != nil {
+		return nil, err
+	}
+	return renderConfigWithMCPConfig(participantID, agentID, server, model, mcpConfig, resolveBaseURL, feishuProvider)
+}
+
+func renderConfigWithMCPConfig(participantID, agentID string, server config.ServerConfig, model config.ModelConfig, mcpConfig map[string]any, resolveBaseURL BaseURLResolver, feishuProvider feishu.AgentCredentialProvider) ([]byte, error) {
 	participantID = strings.TrimSpace(participantID)
 	agentID = strings.TrimSpace(agentID)
 	if participantID == "" {
@@ -176,7 +193,7 @@ func renderConfigWithRuntimeOptions(participantID, agentID string, server config
 		return nil, err
 	}
 	updateOpenClawWorkspaceDefault(cfg, workspaceGuestPathForGOOS(goruntime.GOOS))
-	if err := updateOpenClawMCP(cfg, runtimeOptions); err != nil {
+	if err := updateOpenClawMCP(cfg, mcpConfig); err != nil {
 		return nil, err
 	}
 	data, err := json.MarshalIndent(cfg, "", "  ")
@@ -186,6 +203,30 @@ func renderConfigWithRuntimeOptions(participantID, agentID string, server config
 	return data, nil
 }
 
+func mcpConfigFromLegacyRuntimeOptions(runtimeOptions map[string]any) (map[string]any, error) {
+	raw, ok := runtimeOptions[agentruntime.RuntimeOptionMCPKey]
+	if !ok || raw == nil {
+		return nil, nil
+	}
+	mcpConfig, ok := raw.(map[string]any)
+	if !ok {
+		return nil, fmt.Errorf("runtime_options.%s must be an object or null", agentruntime.RuntimeOptionMCPKey)
+	}
+	normalized, err := agentruntime.NormalizeMCPConfig(mcpConfig)
+	if err != nil {
+		return nil, legacyMCPConfigErrorPath(err)
+	}
+	return normalized, nil
+}
+
+func legacyMCPConfigErrorPath(err error) error {
+	if err == nil {
+		return nil
+	}
+	message := strings.ReplaceAll(err.Error(), "mcp_config", "runtime_options."+agentruntime.RuntimeOptionMCPKey)
+	return fmt.Errorf("%s", message)
+}
+
 func updateOpenClawModelProvider(cfg map[string]any, botID string, server config.ServerConfig, modelCfg config.ModelConfig, resolveBaseURL BaseURLResolver) error {
 	modelCfg = modelCfg.Resolved()
 	modelsRoot, ok := cfg["models"].(map[string]any)
diff --git a/internal/runtime/openclawsandbox/config_controller.go b/internal/runtime/openclawsandbox/config_controller.go
index d7760784..82e25ec4 100644
--- a/internal/runtime/openclawsandbox/config_controller.go
+++ b/internal/runtime/openclawsandbox/config_controller.go
@@ -7,15 +7,28 @@ import (
 )
 
 var _ agentruntime.RuntimeConfigController = (*Runtime)(nil)
+var _ agentruntime.MCPConfigController = (*Runtime)(nil)
 
 func (r *Runtime) ValidateConfig(_ context.Context, current agentruntime.RuntimeConfigSnapshot) error {
-	return validateOpenClawMCPRuntimeOptions(current.Options)
+	return nil
 }
 
 func (r *Runtime) RestartRequired(change agentruntime.RuntimeConfigChange) (bool, error) {
-	return openClawMCPRestartRequired(change.Previous.Options, change.Current.Options)
+	return false, nil
 }
 
 func (r *Runtime) ReconcileConfig(context.Context, agentruntime.Handle, agentruntime.RuntimeConfigChange) error {
 	return nil
 }
+
+func (r *Runtime) ValidateMCPConfig(_ context.Context, current agentruntime.MCPConfigSnapshot) error {
+	return validateOpenClawMCPConfig(current.Config)
+}
+
+func (r *Runtime) MCPConfigRestartRequired(change agentruntime.MCPConfigChange) (bool, error) {
+	return openClawMCPRestartRequired(change.Previous.Config, change.Current.Config)
+}
+
+func (r *Runtime) ReconcileMCPConfig(context.Context, agentruntime.Handle, agentruntime.MCPConfigChange) error {
+	return nil
+}
diff --git a/internal/runtime/openclawsandbox/mcp.go b/internal/runtime/openclawsandbox/mcp.go
index 93909d26..d05a33c1 100644
--- a/internal/runtime/openclawsandbox/mcp.go
+++ b/internal/runtime/openclawsandbox/mcp.go
@@ -1,277 +1,17 @@
 package openclawsandbox
 
 import (
-	"fmt"
-	"reflect"
-	"sort"
-	"strings"
-
 	agentruntime "csgclaw/internal/runtime"
 )
 
-type openClawMCPMode int
-
-const (
-	openClawMCPAbsent openClawMCPMode = iota
-	openClawMCPCleared
-	openClawMCPManaged
-)
-
-type openClawMCPConfig struct {
-	mode    openClawMCPMode
-	servers map[string]any
-}
-
-func validateOpenClawMCPRuntimeOptions(runtimeOptions map[string]any) error {
-	_, err := openClawMCPConfigFromRuntimeOptions(runtimeOptions)
-	return err
+func validateOpenClawMCPConfig(config map[string]any) error {
+	return agentruntime.ValidateMCPConfig(config)
 }
 
 func openClawMCPRestartRequired(previous, current map[string]any) (bool, error) {
-	prev, prevErr := openClawMCPConfigFromRuntimeOptions(previous)
-	currentConfig, err := openClawMCPConfigFromRuntimeOptions(current)
-	if err != nil {
-		return false, err
-	}
-	if prevErr != nil {
-		return true, nil
-	}
-	return !reflect.DeepEqual(openClawMCPEffectiveServers(prev), openClawMCPEffectiveServers(currentConfig)), nil
-}
-
-func updateOpenClawMCP(cfg map[string]any, runtimeOptions map[string]any) error {
-	mcpConfig, err := openClawMCPConfigFromRuntimeOptions(runtimeOptions)
-	if err != nil {
-		return err
-	}
-	switch mcpConfig.mode {
-	case openClawMCPAbsent:
-		return nil
-	case openClawMCPCleared:
-		mcpRoot, ok := cfg["mcp"].(map[string]any)
-		if !ok {
-			return nil
-		}
-		delete(mcpRoot, "servers")
-		if len(mcpRoot) == 0 {
-			delete(cfg, "mcp")
-		}
-		return nil
-	case openClawMCPManaged:
-		mcpRoot, _ := cfg["mcp"].(map[string]any)
-		if mcpRoot == nil {
-			mcpRoot = map[string]any{}
-			cfg["mcp"] = mcpRoot
-		}
-		if mcpConfig.servers == nil {
-			mcpConfig.servers = map[string]any{}
-		}
-		mcpRoot["servers"] = mcpConfig.servers
-		return nil
-	default:
-		return nil
-	}
-}
-
-func openClawMCPEffectiveServers(config openClawMCPConfig) map[string]any {
-	if config.mode != openClawMCPManaged {
-		return nil
-	}
-	if config.servers == nil {
-		return map[string]any{}
-	}
-	return config.servers
-}
-
-func openClawMCPConfigFromRuntimeOptions(runtimeOptions map[string]any) (openClawMCPConfig, error) {
-	raw, ok := runtimeOptions[agentruntime.RuntimeOptionMCPKey]
-	if !ok {
-		return openClawMCPConfig{mode: openClawMCPAbsent}, nil
-	}
-	if raw == nil {
-		return openClawMCPConfig{mode: openClawMCPCleared}, nil
-	}
-	mcpRoot, ok := raw.(map[string]any)
-	if !ok {
-		return openClawMCPConfig{}, fmt.Errorf("runtime_options.%s must be an object or null", agentruntime.RuntimeOptionMCPKey)
-	}
-	if unsupported := unsupportedOpenClawMCPRootKeys(mcpRoot); len(unsupported) > 0 {
-		return openClawMCPConfig{}, fmt.Errorf("runtime_options.%s contains unsupported field(s) %q; only mcpServers is supported", agentruntime.RuntimeOptionMCPKey, strings.Join(unsupported, ", "))
-	}
-	if len(mcpRoot) == 0 {
-		return openClawMCPConfig{mode: openClawMCPManaged, servers: map[string]any{}}, nil
-	}
-	rawServers, ok := mcpRoot["mcpServers"]
-	if !ok {
-		return openClawMCPConfig{mode: openClawMCPManaged, servers: map[string]any{}}, nil
-	}
-	serverMap, ok := rawServers.(map[string]any)
-	if !ok {
-		return openClawMCPConfig{}, fmt.Errorf("runtime_options.%s.mcpServers must be an object", agentruntime.RuntimeOptionMCPKey)
-	}
-	servers := make(map[string]any, len(serverMap))
-	for rawName, rawEntry := range serverMap {
-		name := strings.TrimSpace(rawName)
-		if name == "" {
-			return openClawMCPConfig{}, fmt.Errorf("runtime_options.%s.mcpServers contains an empty server name", agentruntime.RuntimeOptionMCPKey)
-		}
-		if _, exists := servers[name]; exists {
-			return openClawMCPConfig{}, fmt.Errorf("runtime_options.%s.mcpServers contains duplicate server name %q", agentruntime.RuntimeOptionMCPKey, name)
-		}
-		entry, ok := rawEntry.(map[string]any)
-		if !ok {
-			return openClawMCPConfig{}, fmt.Errorf("runtime_options.%s.mcpServers.%s must be an object", agentruntime.RuntimeOptionMCPKey, name)
-		}
-		normalized, err := normalizeOpenClawMCPServerEntry(name, entry)
-		if err != nil {
-			return openClawMCPConfig{}, err
-		}
-		servers[name] = normalized
-	}
-	return openClawMCPConfig{mode: openClawMCPManaged, servers: servers}, nil
-}
-
-func unsupportedOpenClawMCPRootKeys(root map[string]any) []string {
-	out := make([]string, 0)
-	for key := range root {
-		if key != "mcpServers" {
-			out = append(out, key)
-		}
-	}
-	sort.Strings(out)
-	return out
-}
-
-func normalizeOpenClawMCPServerEntry(name string, entry map[string]any) (map[string]any, error) {
-	normalized, ok := cloneMCPJSONObject(entry).(map[string]any)
-	if !ok {
-		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s must be an object", agentruntime.RuntimeOptionMCPKey, name)
-	}
-	command, hasCommand, err := mcpStringField(normalized, "command")
-	if err != nil {
-		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s.command %s", agentruntime.RuntimeOptionMCPKey, name, err)
-	}
-	url, hasURL, err := mcpStringField(normalized, "url")
-	if err != nil {
-		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s.url %s", agentruntime.RuntimeOptionMCPKey, name, err)
-	}
-	if !hasCommand && !hasURL {
-		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s must declare command or url", agentruntime.RuntimeOptionMCPKey, name)
-	}
-	if hasCommand {
-		normalized["command"] = command
-	} else {
-		delete(normalized, "command")
-	}
-	if hasURL {
-		normalized["url"] = url
-	} else {
-		delete(normalized, "url")
-	}
-	if err := validateMCPStringSliceField(normalized, "args"); err != nil {
-		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s.args must be an array of strings", agentruntime.RuntimeOptionMCPKey, name)
-	}
-	if err := validateMCPStringMapField(normalized, "env"); err != nil {
-		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s.env must be an object with string values", agentruntime.RuntimeOptionMCPKey, name)
-	}
-	if err := validateMCPStringMapField(normalized, "headers"); err != nil {
-		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s.headers must be an object with string values", agentruntime.RuntimeOptionMCPKey, name)
-	}
-	if err := validateMCPStringField(normalized, "transport"); err != nil {
-		return nil, fmt.Errorf("runtime_options.%s.mcpServers.%s.transport must be a string", agentruntime.RuntimeOptionMCPKey, name)
-	}
-	return normalized, nil
-}
-
-func mcpStringField(values map[string]any, key string) (string, bool, error) {
-	raw, ok := values[key]
-	if !ok || raw == nil {
-		return "", false, nil
-	}
-	text, ok := raw.(string)
-	if !ok {
-		return "", false, fmt.Errorf("must be a string")
-	}
-	text = strings.TrimSpace(text)
-	if text == "" {
-		return "", false, fmt.Errorf("must not be blank")
-	}
-	return text, true, nil
-}
-
-func validateMCPStringField(values map[string]any, key string) error {
-	raw, ok := values[key]
-	if !ok || raw == nil {
-		return nil
-	}
-	_, ok = raw.(string)
-	if !ok {
-		return fmt.Errorf("not a string")
-	}
-	return nil
-}
-
-func validateMCPStringSliceField(values map[string]any, key string) error {
-	raw, ok := values[key]
-	if !ok || raw == nil {
-		return nil
-	}
-	items, ok := raw.([]any)
-	if !ok {
-		return fmt.Errorf("not an array")
-	}
-	for _, item := range items {
-		if _, ok := item.(string); !ok {
-			return fmt.Errorf("contains non-string value")
-		}
-	}
-	return nil
-}
-
-func validateMCPStringMapField(values map[string]any, key string) error {
-	raw, ok := values[key]
-	if !ok || raw == nil {
-		return nil
-	}
-	items, ok := raw.(map[string]any)
-	if !ok {
-		return fmt.Errorf("not an object")
-	}
-	for _, value := range items {
-		if _, ok := value.(string); !ok {
-			return fmt.Errorf("contains non-string value")
-		}
-	}
-	return nil
+	return agentruntime.MCPConfigNeedsRestart(previous, current)
 }
 
-func cloneMCPJSONObject(value any) any {
-	switch typed := value.(type) {
-	case map[string]any:
-		out := make(map[string]any, len(typed))
-		for key, item := range typed {
-			out[key] = cloneMCPJSONObject(item)
-		}
-		return out
-	case map[string]string:
-		out := make(map[string]any, len(typed))
-		for key, item := range typed {
-			out[key] = item
-		}
-		return out
-	case []any:
-		out := make([]any, len(typed))
-		for idx, item := range typed {
-			out[idx] = cloneMCPJSONObject(item)
-		}
-		return out
-	case []string:
-		out := make([]any, len(typed))
-		for idx, item := range typed {
-			out[idx] = item
-		}
-		return out
-	default:
-		return value
-	}
+func updateOpenClawMCP(cfg map[string]any, mcpConfig map[string]any) error {
+	return agentruntime.UpdateJSONMCPServers(cfg, mcpConfig)
 }
diff --git a/internal/runtime/openclawsandbox/provision_test.go b/internal/runtime/openclawsandbox/provision_test.go
index dba83bd6..fbe169b0 100644
--- a/internal/runtime/openclawsandbox/provision_test.go
+++ b/internal/runtime/openclawsandbox/provision_test.go
@@ -29,11 +29,9 @@ func TestProvisionPreparesGatewayAssets(t *testing.T) {
 		AgentID:   "u-alice",
 		AgentName: "alice",
 		Profile:   agentruntime.Profile{},
-		RuntimeOptions: map[string]any{
-			"mcp": map[string]any{
-				"mcpServers": map[string]any{
-					"context7": map[string]any{"command": "uvx", "args": []any{"context7-mcp"}},
-				},
+		MCPConfig: map[string]any{
+			"mcpServers": map[string]any{
+				"context7": map[string]any{"command": "uvx", "args": []any{"context7-mcp"}},
 			},
 		},
 		WorkspaceOverlay: overlayRoot,
diff --git a/internal/runtime/openclawsandbox/runtime.go b/internal/runtime/openclawsandbox/runtime.go
index 0874da86..264ab5aa 100644
--- a/internal/runtime/openclawsandbox/runtime.go
+++ b/internal/runtime/openclawsandbox/runtime.go
@@ -83,7 +83,7 @@ func (r *Runtime) Provision(_ context.Context, req agentruntime.ProvisionRequest
 	if participantID == "" {
 		participantID = strings.TrimSpace(req.AgentID)
 	}
-	if _, err := EnsureConfigWithRuntimeOptions(agentHome, participantID, req.AgentID, gateway.Server, configModelFromProfile(profile), req.RuntimeOptions, fixedBaseURL(gateway.ManagerBaseURL), r.CurrentFeishuProvider()); err != nil {
+	if _, err := EnsureConfigWithMCPConfig(agentHome, participantID, req.AgentID, gateway.Server, configModelFromProfile(profile), req.MCPConfig, fixedBaseURL(gateway.ManagerBaseURL), r.CurrentFeishuProvider()); err != nil {
 		return err
 	}
 	workspaceRoot := r.Layout(agentHome).WorkspaceRoot
diff --git a/internal/runtime/picoclawsandbox/config.go b/internal/runtime/picoclawsandbox/config.go
index 46e70bcd..e256b528 100644
--- a/internal/runtime/picoclawsandbox/config.go
+++ b/internal/runtime/picoclawsandbox/config.go
@@ -10,6 +10,7 @@ import (
 
 	"csgclaw/internal/channel/feishu"
 	"csgclaw/internal/config"
+	agentruntime "csgclaw/internal/runtime"
 )
 
 //go:embed defaults/picoclaw-config.json
@@ -49,12 +50,16 @@ func WorkspaceConfigRoot(agentHome string) string {
 }
 
 func EnsureConfig(agentHome, participantID, agentID string, server config.ServerConfig, model config.ModelConfig, resolveBaseURL BaseURLResolver, feishuProviders ...feishu.AgentCredentialProvider) (string, error) {
+	return EnsureConfigWithMCPConfig(agentHome, participantID, agentID, server, model, nil, resolveBaseURL, feishuProviders...)
+}
+
+func EnsureConfigWithMCPConfig(agentHome, participantID, agentID string, server config.ServerConfig, model config.ModelConfig, mcpConfig map[string]any, resolveBaseURL BaseURLResolver, feishuProviders ...feishu.AgentCredentialProvider) (string, error) {
 	hostRoot := Root(agentHome)
 	if err := os.MkdirAll(hostRoot, 0o755); err != nil {
 		return "", fmt.Errorf("create picoclaw config dir: %w", err)
 	}
 
-	data, err := RenderConfig(participantID, agentID, server, model, resolveBaseURL, feishuProviders...)
+	data, err := RenderConfigWithMCPConfig(participantID, agentID, server, model, mcpConfig, resolveBaseURL, feishuProviders...)
 	if err != nil {
 		return "", err
 	}
@@ -71,6 +76,10 @@ func EnsureConfig(agentHome, participantID, agentID string, server config.Server
 }
 
 func RenderConfig(participantID, agentID string, server config.ServerConfig, model config.ModelConfig, resolveBaseURL BaseURLResolver, feishuProviders ...feishu.AgentCredentialProvider) ([]byte, error) {
+	return RenderConfigWithMCPConfig(participantID, agentID, server, model, nil, resolveBaseURL, feishuProviders...)
+}
+
+func RenderConfigWithMCPConfig(participantID, agentID string, server config.ServerConfig, model config.ModelConfig, mcpConfig map[string]any, resolveBaseURL BaseURLResolver, feishuProviders ...feishu.AgentCredentialProvider) ([]byte, error) {
 	participantID = strings.TrimSpace(participantID)
 	agentID = strings.TrimSpace(agentID)
 	if participantID == "" {
@@ -93,6 +102,9 @@ func RenderConfig(participantID, agentID string, server config.ServerConfig, mod
 	if err := updateFeishuChannel(cfg, agentID, firstFeishuProvider(feishuProviders)); err != nil {
 		return nil, err
 	}
+	if err := updatePicoClawMCP(cfg, mcpConfig); err != nil {
+		return nil, err
+	}
 
 	data, err := json.MarshalIndent(cfg, "", "  ")
 	if err != nil {
@@ -101,6 +113,30 @@ func RenderConfig(participantID, agentID string, server config.ServerConfig, mod
 	return data, nil
 }
 
+func updatePicoClawMCP(cfg map[string]any, mcpConfig map[string]any) error {
+	servers, err := agentruntime.MCPConfigServers(mcpConfig)
+	if err != nil {
+		return err
+	}
+	tools, ok := cfg["tools"].(map[string]any)
+	if !ok {
+		return fmt.Errorf("embedded manager picoclaw config is missing tools")
+	}
+	mcpRoot, _ := tools["mcp"].(map[string]any)
+	if mcpRoot == nil {
+		mcpRoot = map[string]any{}
+		tools["mcp"] = mcpRoot
+	}
+	if servers == nil {
+		mcpRoot["enabled"] = false
+		delete(mcpRoot, "servers")
+		return nil
+	}
+	mcpRoot["enabled"] = true
+	mcpRoot["servers"] = servers
+	return nil
+}
+
 func updateFeishuChannel(cfg map[string]any, agentID string, provider feishu.AgentCredentialProvider) error {
 	agentID = strings.TrimSpace(agentID)
 	if agentID == "" || provider == nil {
diff --git a/internal/runtime/picoclawsandbox/config_controller.go b/internal/runtime/picoclawsandbox/config_controller.go
new file mode 100644
index 00000000..ef5adf4d
--- /dev/null
+++ b/internal/runtime/picoclawsandbox/config_controller.go
@@ -0,0 +1,21 @@
+package picoclawsandbox
+
+import (
+	"context"
+
+	agentruntime "csgclaw/internal/runtime"
+)
+
+var _ agentruntime.MCPConfigController = (*Runtime)(nil)
+
+func (r *Runtime) ValidateMCPConfig(_ context.Context, current agentruntime.MCPConfigSnapshot) error {
+	return agentruntime.ValidateMCPConfig(current.Config)
+}
+
+func (r *Runtime) MCPConfigRestartRequired(change agentruntime.MCPConfigChange) (bool, error) {
+	return agentruntime.MCPConfigNeedsRestart(change.Previous.Config, change.Current.Config)
+}
+
+func (r *Runtime) ReconcileMCPConfig(context.Context, agentruntime.Handle, agentruntime.MCPConfigChange) error {
+	return nil
+}
diff --git a/internal/runtime/picoclawsandbox/config_test.go b/internal/runtime/picoclawsandbox/config_test.go
index 6ad86a63..10bd8df5 100644
--- a/internal/runtime/picoclawsandbox/config_test.go
+++ b/internal/runtime/picoclawsandbox/config_test.go
@@ -2,6 +2,7 @@ package picoclawsandbox
 
 import (
 	"encoding/json"
+	"strings"
 	"testing"
 
 	"csgclaw/internal/channel/feishu"
@@ -39,6 +40,95 @@ func TestRenderConfigDisablesUnconfiguredFeishuChannel(t *testing.T) {
 	}
 }
 
+func TestRenderConfigWithMCPConfigWritesPicoClawToolsMCP(t *testing.T) {
+	baseServer := config.ServerConfig{AccessToken: "shared-token"}
+	baseModel := config.ModelConfig{ModelID: "gpt-5.5"}
+	resolver := fixedBaseURL("http://127.0.0.1:18080")
+
+	t.Run("absent disables mcp", func(t *testing.T) {
+		data, err := RenderConfigWithMCPConfig("manager", "u-manager", baseServer, baseModel, nil, resolver)
+		if err != nil {
+			t.Fatalf("RenderConfigWithMCPConfig() error = %v", err)
+		}
+		mcpRoot := renderedToolsMCP(t, data)
+		if got, want := mcpRoot["enabled"], false; got != want {
+			t.Fatalf("tools.mcp.enabled = %v, want %v in:\n%s", got, want, data)
+		}
+		if _, ok := mcpRoot["servers"]; ok {
+			t.Fatalf("tools.mcp.servers should be absent for unmanaged config: %#v", mcpRoot["servers"])
+		}
+	})
+
+	t.Run("empty managed config enables empty servers", func(t *testing.T) {
+		data, err := RenderConfigWithMCPConfig("manager", "u-manager", baseServer, baseModel, map[string]any{}, resolver)
+		if err != nil {
+			t.Fatalf("RenderConfigWithMCPConfig() error = %v", err)
+		}
+		mcpRoot := renderedToolsMCP(t, data)
+		if got, want := mcpRoot["enabled"], true; got != want {
+			t.Fatalf("tools.mcp.enabled = %v, want %v in:\n%s", got, want, data)
+		}
+		servers, ok := mcpRoot["servers"].(map[string]any)
+		if !ok {
+			t.Fatalf("tools.mcp.servers = %#v, want object", mcpRoot["servers"])
+		}
+		if len(servers) != 0 {
+			t.Fatalf("tools.mcp.servers = %#v, want empty", servers)
+		}
+	})
+
+	t.Run("server config is preserved", func(t *testing.T) {
+		data, err := RenderConfigWithMCPConfig("manager", "u-manager", baseServer, baseModel, map[string]any{
+			"mcpServers": map[string]any{
+				"context7": map[string]any{
+					"command": "uvx",
+					"args":    []any{"context7-mcp"},
+				},
+			},
+		}, resolver)
+		if err != nil {
+			t.Fatalf("RenderConfigWithMCPConfig() error = %v", err)
+		}
+		mcpRoot := renderedToolsMCP(t, data)
+		if got, want := mcpRoot["enabled"], true; got != want {
+			t.Fatalf("tools.mcp.enabled = %v, want %v in:\n%s", got, want, data)
+		}
+		servers := mcpRoot["servers"].(map[string]any)
+		context7 := servers["context7"].(map[string]any)
+		if got, want := context7["command"], "uvx"; got != want {
+			t.Fatalf("context7.command = %#v, want %q", got, want)
+		}
+		args := context7["args"].([]any)
+		if got, want := args[0], "context7-mcp"; got != want {
+			t.Fatalf("context7.args[0] = %#v, want %q", got, want)
+		}
+	})
+}
+
+func TestRenderConfigWithMCPConfigRejectsInvalidPicoClawMCP(t *testing.T) {
+	_, err := RenderConfigWithMCPConfig("manager", "u-manager", config.ServerConfig{}, config.ModelConfig{ModelID: "gpt-5.5"}, map[string]any{
+		"mcpServers": []any{},
+	}, fixedBaseURL("http://127.0.0.1:18080"))
+	if err == nil || !strings.Contains(err.Error(), "mcp_config.mcpServers must be an object") {
+		t.Fatalf("RenderConfigWithMCPConfig() error = %v, want mcpServers object error", err)
+	}
+}
+
+func renderedToolsMCP(t *testing.T, data []byte) map[string]any {
+	t.Helper()
+	var rendered struct {
+		Tools map[string]any `json:"tools"`
+	}
+	if err := json.Unmarshal(data, &rendered); err != nil {
+		t.Fatalf("RenderConfigWithMCPConfig() produced invalid JSON: %v", err)
+	}
+	mcpRoot, ok := rendered.Tools["mcp"].(map[string]any)
+	if !ok {
+		t.Fatalf("RenderConfigWithMCPConfig() missing tools.mcp in:\n%s", data)
+	}
+	return mcpRoot
+}
+
 func TestRenderConfigEnablesFeishuChannelWhenParticipantConfigured(t *testing.T) {
 	data, err := RenderConfig("manager", "u-manager", config.ServerConfig{
 		AccessToken: "shared-token",
diff --git a/internal/runtime/picoclawsandbox/runtime.go b/internal/runtime/picoclawsandbox/runtime.go
index cb4ca840..a563cbdf 100644
--- a/internal/runtime/picoclawsandbox/runtime.go
+++ b/internal/runtime/picoclawsandbox/runtime.go
@@ -85,7 +85,7 @@ func (r *Runtime) Provision(_ context.Context, req agentruntime.ProvisionRequest
 	if participantID == "" {
 		participantID = strings.TrimSpace(req.AgentID)
 	}
-	if _, err := EnsureConfig(agentHome, participantID, req.AgentID, gateway.Server, configModelFromProfile(profile), fixedBaseURL(gateway.ManagerBaseURL), r.CurrentFeishuProvider()); err != nil {
+	if _, err := EnsureConfigWithMCPConfig(agentHome, participantID, req.AgentID, gateway.Server, configModelFromProfile(profile), req.MCPConfig, fixedBaseURL(gateway.ManagerBaseURL), r.CurrentFeishuProvider()); err != nil {
 		return err
 	}
 	workspaceRoot := r.Layout(agentHome).WorkspaceRoot
diff --git a/internal/runtime/provision.go b/internal/runtime/provision.go
index 3f8979e9..93608458 100644
--- a/internal/runtime/provision.go
+++ b/internal/runtime/provision.go
@@ -30,6 +30,7 @@ type ProvisionRequest struct {
 	AgentName        string
 	Profile          Profile
 	RuntimeOptions   map[string]any
+	MCPConfig        map[string]any
 	WorkspaceOverlay string
 	Gateway          *GatewayProvision
 }
diff --git a/web/app/src/api/agents.ts b/web/app/src/api/agents.ts
index b1c6f8f0..3126fb84 100644
--- a/web/app/src/api/agents.ts
+++ b/web/app/src/api/agents.ts
@@ -46,6 +46,7 @@ export type AgentUpdatePayload = {
   instructions?: string;
   image?: string;
   model_config?: JSONRecord;
+  mcp_config?: JSONRecord | null;
   name?: string;
   profile?: JSONRecord | string;
   runtime?: { name?: RuntimeName; sandbox_enabled?: boolean; options?: JSONRecord };
@@ -287,6 +288,7 @@ export async function createBotRequest(payload: CreateBotPayload): Promise<Agent
         },
         runtime_name: runtimeSelection.runtime_name,
         sandbox_enabled: runtimeSelection.sandbox_enabled,
+        mcp_config: payload.mcp_config,
         from_template: payload.from_template,
         model_config: payload.agent_profile,
       },
diff --git a/web/app/src/components/business/ProfileControls/MCPRuntimeOptionsPanel.tsx b/web/app/src/components/business/ProfileControls/MCPConfigPanel.tsx
similarity index 71%
rename from web/app/src/components/business/ProfileControls/MCPRuntimeOptionsPanel.tsx
rename to web/app/src/components/business/ProfileControls/MCPConfigPanel.tsx
index b497cb2f..fcc30737 100644
--- a/web/app/src/components/business/ProfileControls/MCPRuntimeOptionsPanel.tsx
+++ b/web/app/src/components/business/ProfileControls/MCPConfigPanel.tsx
@@ -1,16 +1,16 @@
 import { useEffect, useId, useState } from "react";
 import {
-  MCP_RUNTIME_OPTIONS_EXAMPLE,
-  mcpRuntimeOptionsText,
-  parseMCPRuntimeOptionsText,
-  setMCPRuntimeOptions,
+  MCP_CONFIG_EXAMPLE,
+  mcpConfigText,
+  parseMCPConfigText,
+  setMCPConfig,
   type AgentDraft,
   type JSONRecord,
 } from "@/models/agents";
 import type { TranslateFn } from "@/models/conversations";
 import { Button } from "@/components/ui/Button/Button";
 
-export type MCPRuntimeOptionsPanelProps = {
+export type MCPConfigPanelProps = {
   draft: AgentDraft;
   onDraftChange: (draft: AgentDraft) => void;
   onInvalidChange?: (invalid: boolean) => void;
@@ -18,16 +18,16 @@ export type MCPRuntimeOptionsPanelProps = {
 };
 
 function cloneMCPExample(): JSONRecord {
-  return JSON.parse(JSON.stringify(MCP_RUNTIME_OPTIONS_EXAMPLE)) as JSONRecord;
+  return JSON.parse(JSON.stringify(MCP_CONFIG_EXAMPLE)) as JSONRecord;
 }
 
 function errorMessageForKey(key: "invalid_json" | "object_required", t: TranslateFn): string {
   return key === "invalid_json" ? t("profileMCPServersInvalidJSON") : t("profileMCPServersObjectRequired");
 }
 
-export function MCPRuntimeOptionsPanel({ draft, onDraftChange, onInvalidChange, t }: MCPRuntimeOptionsPanelProps) {
+export function MCPConfigPanel({ draft, onDraftChange, onInvalidChange, t }: MCPConfigPanelProps) {
   const textareaId = useId();
-  const draftText = mcpRuntimeOptionsText(draft.runtime_options);
+  const draftText = mcpConfigText(draft.mcp_config);
   const [text, setText] = useState(draftText);
   const [error, setError] = useState("");
 
@@ -39,7 +39,7 @@ export function MCPRuntimeOptionsPanel({ draft, onDraftChange, onInvalidChange,
 
   function commitText(nextText: string) {
     setText(nextText);
-    const parsed = parseMCPRuntimeOptionsText(nextText);
+    const parsed = parseMCPConfigText(nextText);
     if (!parsed.ok) {
       setError(errorMessageForKey(parsed.error, t));
       onInvalidChange?.(true);
@@ -49,7 +49,7 @@ export function MCPRuntimeOptionsPanel({ draft, onDraftChange, onInvalidChange,
     onInvalidChange?.(false);
     onDraftChange({
       ...draft,
-      runtime_options: setMCPRuntimeOptions(draft.runtime_options, parsed.value),
+      mcp_config: setMCPConfig(parsed.value),
     });
   }
 
@@ -60,7 +60,7 @@ export function MCPRuntimeOptionsPanel({ draft, onDraftChange, onInvalidChange,
     setText(JSON.stringify(example, null, 2));
     onDraftChange({
       ...draft,
-      runtime_options: setMCPRuntimeOptions(draft.runtime_options, example),
+      mcp_config: setMCPConfig(example),
     });
   }
 
@@ -70,15 +70,15 @@ export function MCPRuntimeOptionsPanel({ draft, onDraftChange, onInvalidChange,
     setText("");
     onDraftChange({
       ...draft,
-      runtime_options: setMCPRuntimeOptions(draft.runtime_options, null),
+      mcp_config: setMCPConfig(null),
     });
   }
 
   return (
-    <div className="field span-2 mcp-runtime-options-panel">
-      <div className="mcp-runtime-options-header">
+    <div className="field span-2 mcp-config-panel">
+      <div className="mcp-config-header">
         <label htmlFor={textareaId}>{t("profileMCPServers")}</label>
-        <div className="mcp-runtime-options-actions">
+        <div className="mcp-config-actions">
           <Button variant="secondaryGray" size="sm" onClick={fillExample}>
             {t("profileMCPServersUseExample")}
           </Button>
@@ -89,7 +89,7 @@ export function MCPRuntimeOptionsPanel({ draft, onDraftChange, onInvalidChange,
       </div>
       <textarea
         id={textareaId}
-        className="compact-textarea mcp-runtime-options-textarea"
+        className="compact-textarea mcp-config-textarea"
         value={text}
         aria-invalid={error ? "true" : undefined}
         aria-describedby={`${textareaId}-hint`}
diff --git a/web/app/src/components/business/ProfileControls/ProfileControls.css b/web/app/src/components/business/ProfileControls/ProfileControls.css
index c730d07d..8d71a25f 100644
--- a/web/app/src/components/business/ProfileControls/ProfileControls.css
+++ b/web/app/src/components/business/ProfileControls/ProfileControls.css
@@ -70,11 +70,11 @@
   background: var(--danger);
 }
 
-.mcp-runtime-options-panel {
+.mcp-config-panel {
   min-width: 0;
 }
 
-.mcp-runtime-options-header {
+.mcp-config-header {
   display: flex;
   align-items: center;
   justify-content: space-between;
@@ -82,7 +82,7 @@
   min-width: 0;
 }
 
-.mcp-runtime-options-header > label {
+.mcp-config-header > label {
   min-width: 0;
   color: var(--text);
   font-size: var(--text-sm-size);
@@ -90,14 +90,14 @@
   line-height: var(--text-sm-line-height);
 }
 
-.mcp-runtime-options-actions {
+.mcp-config-actions {
   display: inline-flex;
   flex: 0 0 auto;
   align-items: center;
   gap: 8px;
 }
 
-.mcp-runtime-options-textarea {
+.mcp-config-textarea {
   min-height: 168px;
   font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
   font-size: 12px;
@@ -106,16 +106,16 @@
 }
 
 @media (max-width: 680px) {
-  .mcp-runtime-options-header {
+  .mcp-config-header {
     align-items: stretch;
     flex-direction: column;
   }
 
-  .mcp-runtime-options-actions {
+  .mcp-config-actions {
     width: 100%;
   }
 
-  .mcp-runtime-options-actions .btn {
+  .mcp-config-actions .btn {
     flex: 1 1 0;
     min-width: 0;
   }
diff --git a/web/app/src/components/business/ProfileControls/index.ts b/web/app/src/components/business/ProfileControls/index.ts
index 76ce18a6..d6b67531 100644
--- a/web/app/src/components/business/ProfileControls/index.ts
+++ b/web/app/src/components/business/ProfileControls/index.ts
@@ -6,7 +6,7 @@ export * from "./CLIProxyAuthControl";
 export * from "./ClipboardCopyButton";
 export * from "./EnvKeyValueEditor";
 export * from "./FieldHelpTooltip";
-export * from "./MCPRuntimeOptionsPanel";
+export * from "./MCPConfigPanel";
 export * from "./ModelProviderModelList";
 export * from "./ModelOptionLabel";
 export * from "./NotifierControls";
diff --git a/web/app/src/hooks/workspace/useAgentController.ts b/web/app/src/hooks/workspace/useAgentController.ts
index 1029cf3b..e778431b 100644
--- a/web/app/src/hooks/workspace/useAgentController.ts
+++ b/web/app/src/hooks/workspace/useAgentController.ts
@@ -58,6 +58,7 @@ import {
   composeLegacyRuntimeKind,
   defaultManagerRebuildImageForRuntime,
   defaultWorkerImageForRuntime,
+  draftMCPConfigForSave,
   draftRuntimeOptionsForSave,
   draftToProfileComparePayload,
   draftToProfile,
@@ -542,16 +543,15 @@ export function useAgentController({
       name: selectedAgentForPage.name || "",
       description: selectedAgentForPage.description || "",
       instructions: selectedAgentForPage.instructions || "",
-      profile: modelProviderID ? profileSelectorFromDraft({ model_provider_id: modelProviderID, model_id: modelID }) : "",
-      profile_complete:
-        selectedAgentForPage.profile_complete ?? profile?.profile_complete ?? null,
+      profile: modelProviderID
+        ? profileSelectorFromDraft({ model_provider_id: modelProviderID, model_id: modelID })
+        : "",
+      profile_complete: selectedAgentForPage.profile_complete ?? profile?.profile_complete ?? null,
       provider: selectedAgentForPage.provider || profile?.provider || "",
       model_provider_id: modelProviderID,
       model_id: modelID,
-      reasoning_effort:
-        selectedAgentForPage.reasoning_effort || profile?.reasoning_effort || "",
-      enable_fast_mode:
-        selectedAgentForPage.enable_fast_mode ?? profile?.enable_fast_mode ?? false,
+      reasoning_effort: selectedAgentForPage.reasoning_effort || profile?.reasoning_effort || "",
+      enable_fast_mode: selectedAgentForPage.enable_fast_mode ?? profile?.enable_fast_mode ?? false,
     });
   }, [selectedAgentForPage]);
   const selectedFeishuPendingRegistration = useMemo(() => {
@@ -1267,6 +1267,14 @@ export function useAgentController({
     return JSON.stringify(runtimeOptions || {});
   }
 
+  function mcpConfigPayloadForCompare(draft: AgentDraft | null | undefined): string {
+    const normalized = normalizeDraftForCompare(draft);
+    if (!normalized) {
+      return "";
+    }
+    return JSON.stringify(draftMCPConfigForSave(normalized));
+  }
+
   function hasObjectValues(value: unknown): value is Record<string, unknown> {
     return Boolean(value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length > 0);
   }
@@ -1302,8 +1310,11 @@ export function useAgentController({
     saved: AgentLike | null | undefined,
     profileChanged: boolean,
     runtimeOptionsChanged: boolean,
+    mcpConfigChanged: boolean,
   ): boolean {
-    return Boolean(saved?.id && saved.id !== MANAGER_AGENT_ID && profileChanged && !runtimeOptionsChanged);
+    return Boolean(
+      saved?.id && saved.id !== MANAGER_AGENT_ID && profileChanged && !runtimeOptionsChanged && !mcpConfigChanged,
+    );
   }
 
   async function saveAgentPage(): Promise<void> {
@@ -1345,10 +1356,14 @@ export function useAgentController({
       const runtimeOptions = draftRuntimeOptionsForSave(draft, {
         mergeNotifier: false,
       });
+      const mcpConfig = draftMCPConfigForSave(draft);
       const profileChanged = profilePayloadForCompare(draftToSave) !== profilePayloadForCompare(agentPageSavedDraft);
       const runtimeOptionsChanged =
         runtimeOptionsPayloadForCompare(draftToSave) !== runtimeOptionsPayloadForCompare(agentPageSavedDraft);
-      const hasProfileOrRuntimeChange = profileChanged || (runtimeOptionsChanged && hasObjectValues(runtimeOptions));
+      const mcpConfigChanged =
+        mcpConfigPayloadForCompare(draftToSave) !== mcpConfigPayloadForCompare(agentPageSavedDraft);
+      const hasProfileOrRuntimeChange =
+        profileChanged || (runtimeOptionsChanged && hasObjectValues(runtimeOptions)) || mcpConfigChanged;
 
       const payload = agentPageBaseUpdatePayload(draftToSave);
       if (profileChanged) {
@@ -1358,6 +1373,9 @@ export function useAgentController({
       if (runtimeOptionsChanged) {
         payload.runtime_options = runtimeOptions || {};
       }
+      if (mcpConfigChanged) {
+        payload.mcp_config = mcpConfig;
+      }
       if (!hasProfileOrRuntimeChange) {
         debugAgentPageSavePayload("meta-only", payload);
         const savedMetaOnly = await updateAgentRequest(selectedAgentForPage.id, payload);
@@ -1383,7 +1401,7 @@ export function useAgentController({
       const profileIncompleteBeforeSave = !isAgentProfileMarkedComplete(agentPageSavedDraft);
       const saved = await updateAgentRequest(selectedAgentForPage.id, payload);
       await saveLinkedAgentUserAvatar(selectedAgentForPage, draft.avatar);
-      if (canApplyAgentPageProfileSaveImmediately(saved, profileChanged, runtimeOptionsChanged)) {
+      if (canApplyAgentPageProfileSaveImmediately(saved, profileChanged, runtimeOptionsChanged, mcpConfigChanged)) {
         applyAgentListUpdate(saved);
         const savedDraft = agentToDraft(saved);
         setAgentPageDraft(savedDraft);
@@ -1505,6 +1523,7 @@ export function useAgentController({
       const runtimeOptions = draftRuntimeOptionsForSave(draft, {
         mergeNotifier: false,
       });
+      const mcpConfig = draftMCPConfigForSave(draft);
       const payload: AgentUpdatePayload = {
         name: agentDraft.name,
         role: WORKER_AGENT_ROLE,
@@ -1522,13 +1541,22 @@ export function useAgentController({
       const runtimeOptionsChanged = !isCreate
         ? runtimeOptionsPayloadForCompare(agentDraft) !== runtimeOptionsPayloadForCompare(editingDraftBaseline)
         : Boolean(runtimeOptions);
+      const mcpConfigChanged = !isCreate
+        ? mcpConfigPayloadForCompare(agentDraft) !== mcpConfigPayloadForCompare(editingDraftBaseline)
+        : Boolean(mcpConfig);
       if (isCreate) {
         if (runtimeOptions) {
           payload.runtime_options = runtimeOptions;
         }
+        if (mcpConfig) {
+          payload.mcp_config = mcpConfig;
+        }
       } else if (runtimeOptionsChanged) {
         payload.runtime_options = runtimeOptions || {};
       }
+      if (!isCreate && mcpConfigChanged) {
+        payload.mcp_config = mcpConfig;
+      }
       const saved = isCreate
         ? await (async () => {
             const existingNames = agentItems.map((item) => String(item.name || "").trim()).filter(Boolean);
@@ -1557,6 +1585,7 @@ export function useAgentController({
             agent_profile: payload.agent_profile,
             profile: payload.profile,
             ...(payload.runtime_options !== undefined ? { runtime_options: payload.runtime_options } : {}),
+            ...(payload.mcp_config !== undefined ? { mcp_config: payload.mcp_config } : {}),
           });
       await saveLinkedAgentUserAvatar(saved?.participants?.length ? saved : editingAgent || saved, agentDraft.avatar);
       if (isCreate) {
diff --git a/web/app/src/models/agents.ts b/web/app/src/models/agents.ts
index 4552399f..dba85067 100644
--- a/web/app/src/models/agents.ts
+++ b/web/app/src/models/agents.ts
@@ -26,7 +26,7 @@ export type ProviderName = "csghub_lite" | "csghub" | "codex" | "claude_code" |
 export type JSONRecord = Record<string, unknown>;
 
 export const MCP_RUNTIME_OPTION_KEY = "mcp";
-export const MCP_RUNTIME_OPTIONS_EXAMPLE: JSONRecord = {
+export const MCP_CONFIG_EXAMPLE: JSONRecord = {
   mcpServers: {
     context7: {
       command: "npx",
@@ -35,7 +35,7 @@ export const MCP_RUNTIME_OPTIONS_EXAMPLE: JSONRecord = {
   },
 };
 
-export type MCPRuntimeOptionsParseResult =
+export type MCPConfigParseResult =
   | { ok: true; value: JSONRecord | null }
   | { ok: false; error: "invalid_json" | "object_required" };
 
@@ -88,6 +88,7 @@ export type AgentProfileLike = {
   reasoning_effort?: string | null;
   request_options?: JSONRecord | null;
   runtime_options?: JSONRecord | null;
+  mcp_config?: JSONRecord | null;
   runtime_kind?: string | null;
   runtime_name?: RuntimeName | null;
   sandbox_enabled?: boolean | null;
@@ -126,6 +127,7 @@ export type AgentLike = AgentProfileLike & {
   sandbox_enabled?: boolean | null;
   runtime_option_schemas?: RuntimeOptionSchema[] | null;
   runtime_options?: JSONRecord | null;
+  mcp_config?: JSONRecord | null;
   status?: string | null;
   template_name?: string | null;
   user_id?: string | null;
@@ -313,6 +315,18 @@ export function agentRuntimeOptions(item: AgentLike | AgentProfileLike | null |
   return {};
 }
 
+export function agentMCPConfig(item: AgentLike | AgentProfileLike | null | undefined): JSONRecord {
+  const agent = item as AgentLike | null | undefined;
+  if (agent?.mcp_config && typeof agent.mcp_config === "object" && !Array.isArray(agent.mcp_config)) {
+    return { ...(agent.mcp_config as JSONRecord) };
+  }
+  const legacyMCP = agentRuntimeOptions(item)[MCP_RUNTIME_OPTION_KEY];
+  if (legacyMCP && typeof legacyMCP === "object" && !Array.isArray(legacyMCP)) {
+    return { ...(legacyMCP as JSONRecord) };
+  }
+  return {};
+}
+
 export function agentProfileConfig(item: AgentLike | null | undefined): AgentProfileLike | null {
   if (item?.model_config && typeof item.model_config === "object" && !Array.isArray(item.model_config)) {
     return item.model_config;
@@ -362,6 +376,7 @@ export type AgentDraft = {
   role?: string;
   bot_type?: BotType;
   runtime_options?: JSONRecord;
+  mcp_config?: JSONRecord;
   runtime_name?: RuntimeName;
   sandbox_enabled?: boolean;
   runtime_kind: RuntimeKind;
@@ -533,19 +548,20 @@ function isJSONRecord(value: unknown): value is JSONRecord {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 
-export function supportsMCPRuntimeOptions(runtimeKind: unknown): boolean {
-  return normalizeRuntimeKind(runtimeKind) === "openclaw_sandbox";
+export function supportsMCPConfig(runtimeKind: unknown): boolean {
+  const normalized = normalizeRuntimeKind(runtimeKind);
+  return normalized === "openclaw_sandbox" || normalized === "picoclaw_sandbox" || normalized === "codex";
 }
 
-export function mcpRuntimeOptionsText(runtimeOptions: JSONRecord | null | undefined): string {
-  const value = normalizeRuntimeOptionsRecord(runtimeOptions)[MCP_RUNTIME_OPTION_KEY];
-  if (value == null) {
+export function mcpConfigText(mcpConfig: JSONRecord | null | undefined): string {
+  const value = normalizeRuntimeOptionsRecord(mcpConfig);
+  if (Object.keys(value).length === 0) {
     return "";
   }
   return JSON.stringify(value, null, 2);
 }
 
-export function parseMCPRuntimeOptionsText(text: string): MCPRuntimeOptionsParseResult {
+export function parseMCPConfigText(text: string): MCPConfigParseResult {
   const trimmed = text.trim();
   if (!trimmed) {
     return { ok: true, value: null };
@@ -562,16 +578,16 @@ export function parseMCPRuntimeOptionsText(text: string): MCPRuntimeOptionsParse
   return { ok: true, value: parsed };
 }
 
-export function setMCPRuntimeOptions(
-  runtimeOptions: JSONRecord | null | undefined,
-  value: JSONRecord | null,
-): JSONRecord {
-  const next = normalizeRuntimeOptionsRecord(runtimeOptions);
+export function setMCPConfig(value: JSONRecord | null): JSONRecord | undefined {
   if (value == null) {
-    delete next[MCP_RUNTIME_OPTION_KEY];
-    return next;
+    return undefined;
   }
-  next[MCP_RUNTIME_OPTION_KEY] = value;
+  return normalizeRuntimeOptionsRecord(value);
+}
+
+export function stripLegacyMCPRuntimeOption(runtimeOptions: JSONRecord | null | undefined): JSONRecord {
+  const next = normalizeRuntimeOptionsRecord(runtimeOptions);
+  delete next[MCP_RUNTIME_OPTION_KEY];
   return next;
 }
 
@@ -832,6 +848,8 @@ export function agentDraftWithRuntimeFieldsFromAgent(
   if (Object.keys(updatedRuntimeOptions).length > 0) {
     next.runtime_options = normalizeRuntimeOptionsRecord(updatedRuntimeOptions);
   }
+  const updatedMCPConfig = agentMCPConfig(updated);
+  next.mcp_config = normalizeRuntimeOptionsRecord(updatedMCPConfig);
   return next;
 }
 
@@ -1238,6 +1256,7 @@ export function agentToDraft(agent: AgentDraftSource | null | undefined): AgentD
     from_template: agent?.from_template || "",
     template_name: agent?.template_name || "",
     runtime_options: normalizeRuntimeOptionsRecord(agentRuntimeOptions(agent as AgentLike | null | undefined)),
+    mcp_config: normalizeRuntimeOptionsRecord(agentMCPConfig(agent as AgentLike | null | undefined)),
     ...base,
     notifier_delivery_mode: normalizeNotifierDeliveryMode(agent?.notifier_delivery_mode || base.notifier_delivery_mode),
     runtime_name: agentRuntimeName(agent as AgentLike | null | undefined),
@@ -1509,6 +1528,11 @@ export function draftRuntimeOptionsForSave(
   return { ...(base || {}), ...(notifier || {}) };
 }
 
+export function draftMCPConfigForSave(draft: Partial<AgentDraft> | null | undefined): JSONRecord | null {
+  const config = normalizeRuntimeOptionsRecord(draft?.mcp_config);
+  return Object.keys(config).length > 0 ? config : null;
+}
+
 export function notifierRemoteTokenPlaceholderText(
   draft: Partial<AgentDraft> | null | undefined,
   t: TranslateFn,
diff --git a/web/app/src/pages/AgentPage/components/AgentDetailPane/AgentDetailPane.tsx b/web/app/src/pages/AgentPage/components/AgentDetailPane/AgentDetailPane.tsx
index 3daa43f2..817c4e0e 100644
--- a/web/app/src/pages/AgentPage/components/AgentDetailPane/AgentDetailPane.tsx
+++ b/web/app/src/pages/AgentPage/components/AgentDetailPane/AgentDetailPane.tsx
@@ -18,7 +18,7 @@ import { AGENT_PROFILE_ACTIVE_TAB_STORAGE_KEY } from "@/shared/storage/keys";
 import {
   EnvKeyValueEditor,
   FieldHelpTooltip,
-  MCPRuntimeOptionsPanel,
+  MCPConfigPanel,
   ModelOptionLabel,
   NotifierControls,
   requiredFieldLabel,
@@ -44,7 +44,7 @@ import {
   isManagerAgent,
   isNotifierRuntimeDraftOnAgentPage,
   runtimeOptionSchemasForAgent,
-  supportsMCPRuntimeOptions,
+  supportsMCPConfig,
 } from "@/models/agents";
 import type { AgentDraft, AgentLike } from "@/models/agents";
 import {
@@ -83,7 +83,7 @@ import { AgentActivityPanel } from "./AgentActivityPanel";
 type VoidOrPromise = void | Promise<void>;
 type AgentActionHandler = (item: AgentLike) => VoidOrPromise;
 type AgentNoticeTone = "info" | "warning" | "success";
-const AGENT_PROFILE_TAB_IDS = ["profile", "activity", "channels", "instructions", "skills"] as const;
+const AGENT_PROFILE_TAB_IDS = ["profile", "activity", "channels", "instructions", "skills", "mcp"] as const;
 type AgentProfileTabID = (typeof AGENT_PROFILE_TAB_IDS)[number];
 type UpdateAgentDraft = (patch: Partial<AgentDraft>) => void;
 type RuntimeOptionSchemaList = ReturnType<typeof runtimeOptionSchemasForAgent>;
@@ -211,7 +211,8 @@ export function AgentDetailPane({
   const [selectedSkillNames, setSelectedSkillNames] = useState<string[]>([]);
   const [deleteSkillDialogOpen, setDeleteSkillDialogOpen] = useState(false);
   const [skillPendingDelete, setSkillPendingDelete] = useState<SlashSkillOption | null>(null);
-  const [mcpRuntimeOptionsInvalid, setMcpRuntimeOptionsInvalid] = useState(false);
+  const [mcpConfigInvalid, setMcpConfigInvalid] = useState(false);
+  const [mcpPanelMounted, setMcpPanelMounted] = useState(false);
   const descriptionInputRef = useRef<HTMLTextAreaElement | null>(null);
   const nameInputRef = useRef<HTMLInputElement | null>(null);
   const isManager = isManagerAgent(item);
@@ -228,7 +229,7 @@ export function AgentDetailPane({
   const canPublish = runtimeKind === "picoclaw_sandbox" || runtimeKind === "openclaw_sandbox";
   const hasUnsavedChanges =
     hasUnsavedChangesProp ?? Boolean(draft && savedDraft && JSON.stringify(draft) !== JSON.stringify(savedDraft));
-  const saveDisabled = agentProfilePageSaveDisabled(draft, item, { saving, savedDraft }) || mcpRuntimeOptionsInvalid;
+  const saveDisabled = agentProfilePageSaveDisabled(draft, item, { saving, savedDraft }) || mcpConfigInvalid;
   const updateDraft = (patch: Partial<AgentDraft>) => onDraftChange?.({ ...(draft || agentToDraft(item)), ...patch });
   const runtimeOptionSchemas = runtimeOptionSchemasForAgent(draft?.runtime_kind || runtimeKind, item);
   const fallbackProviderID = String(draft?.model_provider_id || "").trim();
@@ -254,8 +255,8 @@ export function AgentDetailPane({
   const selectedProviderModels = selectedProvider?.models ?? [];
   const selectedModelValue = draft?.model_id || "";
   const isNotifierDraft = Boolean(draft && isNotifierRuntimeDraftOnAgentPage(draft, item));
-  const showMCPRuntimeOptions = Boolean(
-    draft && !isNotifierDraft && supportsMCPRuntimeOptions(draft.runtime_kind || item.runtime_kind),
+  const showMCPConfig = Boolean(
+    draft && !isNotifierDraft && supportsMCPConfig(draft.runtime_kind || item.runtime_kind),
   );
   const profileTabs = useMemo(
     () =>
@@ -263,14 +264,13 @@ export function AgentDetailPane({
         ? [
             { id: "profile" as const, label: t("agentProfileTab") },
             { id: "activity" as const, label: t("agentActivityTab") },
-            ...(!isNotifierDraft ? [{ id: "instructions" as const, label: t("agentInstructions") }] : []),
-            ...(workspaceSupported
-              ? [{ id: "skills" as const, label: t("agentProfileSkillsTab"), count: skills.length }]
-              : []),
             ...(!isNotificationBotAgent(item) ? [{ id: "channels" as const, label: t("agentChannelsTitle") }] : []),
+            ...(!isNotifierDraft ? [{ id: "instructions" as const, label: t("agentInstructions") }] : []),
+            ...(workspaceSupported ? [{ id: "skills" as const, label: t("agentProfileSkillsTab") }] : []),
+            ...(showMCPConfig ? [{ id: "mcp" as const, label: t("agentProfileMCPTab") }] : []),
           ]
         : [],
-    [draft, isNotifierDraft, item, skills.length, t, workspaceSupported],
+    [draft, isNotifierDraft, item, showMCPConfig, t, workspaceSupported],
   );
   const visibleActiveProfileTab = profileTabs.some((tab) => tab.id === activeProfileTab)
     ? activeProfileTab
@@ -311,16 +311,15 @@ export function AgentDetailPane({
   }, [addSkillsDialogOpen]);
 
   useEffect(() => {
-    if (visibleActiveProfileTab && activeProfileTab !== visibleActiveProfileTab) {
-      setActiveProfileTab(visibleActiveProfileTab);
+    if (!showMCPConfig) {
+      setMcpConfigInvalid(false);
+      setMcpPanelMounted(false);
+      return;
     }
-  }, [activeProfileTab, visibleActiveProfileTab]);
-
-  useEffect(() => {
-    if (!showMCPRuntimeOptions) {
-      setMcpRuntimeOptionsInvalid(false);
+    if (visibleActiveProfileTab === "mcp") {
+      setMcpPanelMounted(true);
     }
-  }, [showMCPRuntimeOptions]);
+  }, [showMCPConfig, visibleActiveProfileTab]);
 
   async function handleAddSkillsConfirm(): Promise<void> {
     if (!selectedSkillNames.length) {
@@ -537,12 +536,7 @@ export function AgentDetailPane({
                   aria-controls={`agent-profile-${section.id}`}
                   onClick={() => selectProfileTab(section.id)}
                 >
-                  <span>{section.label}</span>
-                  {typeof section.count === "number" ? (
-                    <span className="agent-profile-section-tab-count" aria-label={String(section.count)}>
-                      {section.count}
-                    </span>
-                  ) : null}
+                  {section.label}
                 </button>
               );
             })}
@@ -630,19 +624,6 @@ export function AgentDetailPane({
                 onDisconnectFeishu={onDisconnectFeishu}
               />
             ) : null}
-            {visibleActiveProfileTab === "runtime" ? (
-              <AgentRuntimePanel
-                draft={draft}
-                item={item}
-                locale={locale}
-                runtimeKind={runtimeKind}
-                runtimeOptionSchemas={runtimeOptionSchemas}
-                t={t}
-                onDraftChange={onDraftChange}
-                onMCPRuntimeOptionsInvalidChange={setMcpRuntimeOptionsInvalid}
-                showMCPRuntimeOptions={showMCPRuntimeOptions}
-              />
-            ) : null}
 
             {visibleActiveProfileTab === "instructions" && !isNotifierDraft ? (
               <AgentInstructionsPanel draft={draft} t={t} updateDraft={updateDraft} />
@@ -666,6 +647,17 @@ export function AgentDetailPane({
                 }}
               />
             ) : null}
+
+            {showMCPConfig && (mcpPanelMounted || visibleActiveProfileTab === "mcp") ? (
+              <div hidden={visibleActiveProfileTab !== "mcp"}>
+                <AgentMCPPanel
+                  draft={draft}
+                  t={t}
+                  onDraftChange={onDraftChange || (() => {})}
+                  onInvalidChange={setMcpConfigInvalid}
+                />
+              </div>
+            ) : null}
           </div>
         ) : null}
       </div>
@@ -818,10 +810,8 @@ type AgentRuntimePanelProps = {
   item: AgentLike;
   locale: LocaleCode;
   onDraftChange?: (draft: AgentDraft) => void;
-  onMCPRuntimeOptionsInvalidChange: (invalid: boolean) => void;
   runtimeKind: string;
   runtimeOptionSchemas: RuntimeOptionSchemaList;
-  showMCPRuntimeOptions: boolean;
   t: TranslateFn;
 };
 
@@ -830,10 +820,8 @@ function AgentRuntimePanel({
   item,
   locale,
   onDraftChange,
-  onMCPRuntimeOptionsInvalidChange,
   runtimeKind,
   runtimeOptionSchemas,
-  showMCPRuntimeOptions,
   t,
 }: AgentRuntimePanelProps) {
   const isNotifierDraft = isNotifierRuntimeDraftOnAgentPage(draft, item);
@@ -880,14 +868,29 @@ function AgentRuntimePanel({
               embedded
             />
           ) : null}
-          {showMCPRuntimeOptions ? (
-            <MCPRuntimeOptionsPanel
-              draft={draft}
-              t={t}
-              onDraftChange={onDraftChange || (() => {})}
-              onInvalidChange={onMCPRuntimeOptionsInvalidChange}
-            />
-          ) : null}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+type AgentMCPPanelProps = {
+  draft: AgentDraft;
+  onDraftChange: (draft: AgentDraft) => void;
+  onInvalidChange: (invalid: boolean) => void;
+  t: TranslateFn;
+};
+
+function AgentMCPPanel({ draft, onDraftChange, onInvalidChange, t }: AgentMCPPanelProps) {
+  return (
+    <section id="agent-profile-mcp" className="profile-section agent-profile-scroll-target">
+      <div className="profile-section-heading">
+        <div className="profile-section-title">{t("profileMCPServers")}</div>
+        <p className="profile-section-description">{t("profileMCPServersHint")}</p>
+      </div>
+      <div className="agent-section-form">
+        <div className="profile-grid-compact agent-page-form-content">
+          <MCPConfigPanel draft={draft} t={t} onDraftChange={onDraftChange} onInvalidChange={onInvalidChange} />
         </div>
       </div>
     </section>
@@ -1064,7 +1067,7 @@ function AgentInstructionsPanel({ draft, t, updateDraft }: AgentInstructionsPane
     >
       <div className="profile-grid-compact">
         <label className="field span-2">
-          <span className="sr-only">{t("agentInstructions")}</span>
+          <span>{t("agentInstructions")}</span>
           <textarea
             className="compact-textarea"
             value={draft.instructions || ""}
@@ -1106,48 +1109,59 @@ function AgentSkillsPanel({
 }: AgentSkillsPanelProps) {
   return (
     <section id="agent-profile-skills" className="profile-section agent-skills-section agent-profile-scroll-target">
-      <div className="profile-section-heading agent-skills-section-heading">
+      <div className="profile-section-heading">
+        <div className="profile-section-title">{t("agentSkillsTitle")}</div>
         <p className="profile-section-description">{t("agentSkillsDescription")}</p>
-        <Button
-          className="agent-skill-add-button"
-          variant="secondaryGray"
-          size="sm"
-          aria-label={t("agentSkillAdd")}
-          title={t("agentSkillAdd")}
-          disabled={skillCandidatesLoading || skillAddBusy}
-          onClick={onOpenAddSkills}
-        >
-          <Plus aria-hidden="true" size={16} strokeWidth={2.2} />
-        </Button>
       </div>
-      {skillsError ? <div className="form-error">{skillsError}</div> : null}
-      {skillAddError ? <div className="form-error">{skillAddError}</div> : null}
-      {skillDeleteError ? <div className="form-error">{skillDeleteError}</div> : null}
-      {skillsLoading ? <div className="agent-skills-empty">{t("agentSkillsLoading")}</div> : null}
-      {!skillsLoading && !skills.length ? <div className="agent-skills-empty">{t("agentSkillsEmpty")}</div> : null}
-      {!skillsLoading && skills.length ? (
-        <div className="agent-skills-list">
-          {skills.map((skill) => (
-            <article key={skill.name} className="agent-skill-card">
-              <div className="agent-skill-card-header">
-                <div className="agent-skill-name">{skill.name}</div>
-                <Button
-                  className="agent-skill-icon-button"
-                  variant="outlineDanger"
-                  size="sm"
-                  aria-label={t("agentDeleteSkill")}
-                  title={t("agentDeleteSkill")}
-                  disabled={skillDeleteBusy}
-                  onClick={() => onRequestDeleteSkill(skill)}
-                >
-                  <Trash2 aria-hidden="true" size={16} strokeWidth={1.9} />
-                </Button>
-              </div>
-              <p className="agent-skill-description">{skill.description || "-"}</p>
-            </article>
-          ))}
+      <div className="agent-section-form">
+        <div className="agent-page-form-content agent-skills-form-content">
+          <div className="agent-skills-title">
+            <div className="agent-skills-title-copy">
+              <span>{t("agentSkillsTitle")}</span>
+              <small>{skills.length}</small>
+            </div>
+            <Button
+              className="agent-skill-add-button"
+              variant="secondaryGray"
+              size="sm"
+              aria-label={t("agentSkillAdd")}
+              title={t("agentSkillAdd")}
+              disabled={skillCandidatesLoading || skillAddBusy}
+              onClick={onOpenAddSkills}
+            >
+              <Plus aria-hidden="true" size={16} strokeWidth={2.2} />
+            </Button>
+          </div>
+          {skillsError ? <div className="form-error">{skillsError}</div> : null}
+          {skillAddError ? <div className="form-error">{skillAddError}</div> : null}
+          {skillDeleteError ? <div className="form-error">{skillDeleteError}</div> : null}
+          {skillsLoading ? <div className="agent-skills-empty">{t("agentSkillsLoading")}</div> : null}
+          {!skillsLoading && !skills.length ? <div className="agent-skills-empty">{t("agentSkillsEmpty")}</div> : null}
+          {!skillsLoading && skills.length ? (
+            <div className="agent-skills-list">
+              {skills.map((skill) => (
+                <article key={skill.name} className="agent-skill-card">
+                  <div className="agent-skill-card-header">
+                    <div className="agent-skill-name">{skill.name}</div>
+                    <Button
+                      className="agent-skill-icon-button"
+                      variant="outlineDanger"
+                      size="sm"
+                      aria-label={t("agentDeleteSkill")}
+                      title={t("agentDeleteSkill")}
+                      disabled={skillDeleteBusy}
+                      onClick={() => onRequestDeleteSkill(skill)}
+                    >
+                      <Trash2 aria-hidden="true" size={16} strokeWidth={1.9} />
+                    </Button>
+                  </div>
+                  <p className="agent-skill-description">{skill.description || "-"}</p>
+                </article>
+              ))}
+            </div>
+          ) : null}
         </div>
-      ) : null}
+      </div>
     </section>
   );
 }
@@ -1230,6 +1244,9 @@ function AgentChannelsSection({
       aria-labelledby="agent-channels-title"
     >
       <div className="profile-section-heading">
+        <h2 id="agent-channels-title" className="profile-section-title agent-channels-title">
+          {t("agentChannelsTitle")}
+        </h2>
         <p className="profile-section-description">{t("agentChannelsDescription")}</p>
       </div>
       <div className="agent-channel-row">
diff --git a/web/app/src/pages/WorkspacePage/components/WorkspaceModals/AgentProfileModal.tsx b/web/app/src/pages/WorkspacePage/components/WorkspaceModals/AgentProfileModal.tsx
index 9d618142..11cb3ad5 100644
--- a/web/app/src/pages/WorkspacePage/components/WorkspaceModals/AgentProfileModal.tsx
+++ b/web/app/src/pages/WorkspacePage/components/WorkspaceModals/AgentProfileModal.tsx
@@ -6,7 +6,7 @@ import {
   EnvKeyValueEditor,
   FieldHelpTooltip,
   isBlank,
-  MCPRuntimeOptionsPanel,
+  MCPConfigPanel,
   ModelOptionLabel,
   NotifierControls,
   requiredFieldLabel,
@@ -29,8 +29,8 @@ import {
   pickDefaultAgentTemplate,
   defaultWorkerImageForRuntime,
   runtimeOptionSchemasForAgent,
-  setMCPRuntimeOptions,
-  supportsMCPRuntimeOptions,
+  stripLegacyMCPRuntimeOption,
+  supportsMCPConfig,
   templateMatchesRuntime,
   workerSelectableTemplates,
 } from "@/models/agents";
@@ -109,7 +109,7 @@ export function AgentProfileModal({
   onSave,
 }: AgentProfileModalProps) {
   const [isEditorScrolling, setIsEditorScrolling] = useState(false);
-  const [mcpRuntimeOptionsInvalid, setMcpRuntimeOptionsInvalid] = useState(false);
+  const [mcpConfigInvalid, setMcpConfigInvalid] = useState(false);
   const editorScrollTimerRef = useRef<number | null>(null);
   const lastTemplateIDRef = useRef("");
   const createBotKind = agentModalMode === "create" ? agentCreateBotKind : undefined;
@@ -118,7 +118,7 @@ export function AgentProfileModal({
   const isTemplateCreate = isWorkerCreate && agentCreateMode === "template";
   const isCustomCreate = isWorkerCreate && agentCreateMode === "custom";
   const templateLocked = agentCreateTemplateLocked(agentDraft, agentModalMode);
-  const showMCPRuntimeOptions = !isNotificationContext && supportsMCPRuntimeOptions(agentDraft.runtime_kind);
+  const showMCPConfig = !isNotificationContext && supportsMCPConfig(agentDraft.runtime_kind);
   const runtimeOptionSchemas = isNotificationContext
     ? []
     : runtimeOptionSchemasForAgent(
@@ -169,10 +169,10 @@ export function AgentProfileModal({
     runtimeOptions: AgentDraft["runtime_options"],
     runtimeKind: string,
   ): AgentDraft["runtime_options"] {
-    if (supportsMCPRuntimeOptions(runtimeKind) || !runtimeOptions || !(MCP_RUNTIME_OPTION_KEY in runtimeOptions)) {
+    if (supportsMCPConfig(runtimeKind) || !runtimeOptions || !(MCP_RUNTIME_OPTION_KEY in runtimeOptions)) {
       return runtimeOptions;
     }
-    const next = setMCPRuntimeOptions(runtimeOptions, null);
+    const next = stripLegacyMCPRuntimeOption(runtimeOptions);
     return Object.keys(next).length > 0 ? next : undefined;
   }
 
@@ -271,10 +271,10 @@ export function AgentProfileModal({
   );
 
   useEffect(() => {
-    if (!showMCPRuntimeOptions) {
-      setMcpRuntimeOptionsInvalid(false);
+    if (!showMCPConfig) {
+      setMcpConfigInvalid(false);
     }
-  }, [showMCPRuntimeOptions]);
+  }, [showMCPConfig]);
 
   function onEditorShellScroll() {
     setIsEditorScrolling(true);
@@ -589,12 +589,12 @@ export function AgentProfileModal({
                       embedded
                     />
                   ) : null}
-                  {showMCPRuntimeOptions ? (
-                    <MCPRuntimeOptionsPanel
+                  {showMCPConfig ? (
+                    <MCPConfigPanel
                       draft={agentDraft}
                       t={t}
                       onDraftChange={onAgentDraftChange}
-                      onInvalidChange={setMcpRuntimeOptionsInvalid}
+                      onInvalidChange={setMcpConfigInvalid}
                     />
                   ) : null}
                 </div>
@@ -767,7 +767,7 @@ export function AgentProfileModal({
             size="md"
             disabled={
               agentBusy ||
-              mcpRuntimeOptionsInvalid ||
+              mcpConfigInvalid ||
               isBlank(agentDraft.name) ||
               (isNotificationContext
                 ? !notifierFormIsComplete(agentDraft, editingAgent)
diff --git a/web/app/src/shared/i18n/messages.ts b/web/app/src/shared/i18n/messages.ts
index 753c662d..c9ed0344 100644
--- a/web/app/src/shared/i18n/messages.ts
+++ b/web/app/src/shared/i18n/messages.ts
@@ -60,37 +60,6 @@ export const messages = {
     csghubLoginURLMissing: "登录地址为空，请重试。",
     csghubLoginCompleted: "用户 {user} 登录完成。",
     csghubLogoutCompleted: "用户 {user} 已登出。",
-    connectorManagerTitle: "管理连接器",
-    connectorGitHub: "GitHub",
-    connectorConnected: "已连接",
-    connectorConfigured: "已配置",
-    connectorSetUp: "设置",
-    connectorNotConnected: "未连接",
-    connectorConnect: "连接",
-    connectorConnectGitHub: "连接 GitHub",
-    connectorGitHubConnectedAs: "GitHub 已连接：{user}",
-    connectorManage: "管理",
-    connectorDisconnect: "断开",
-    connectorEdit: "编辑",
-    connectorSave: "保存",
-    connectorClientID: "Client ID",
-    connectorClientSecret: "Client Secret",
-    connectorCallbackURL: "Callback URL",
-    connectorScopes: "Scopes",
-    connectorOAuthPending: "等待 GitHub 授权完成...",
-    connectorClientIDRequired: "请填写 GitHub Client ID。",
-    connectorClientSecretRequired: "请填写 GitHub Client Secret。",
-    connectorSaveFailed: "保存 GitHub 连接器失败。",
-    connectorNotConfigured: "请先配置 GitHub OAuth Client ID 和 Client Secret。",
-    connectorConnectFailed: "GitHub 授权启动失败。",
-    connectorManageFailed: "打开 GitHub App 管理失败。",
-    connectorDisconnectFailed: "断开 GitHub 连接失败。",
-    connectorStatusFailed: "读取连接器状态失败。",
-    connectorLoginTimedOut: "GitHub 授权超时，请重新连接。",
-    connectorOAuthURLMissing: "GitHub 授权地址为空，请重试。",
-    connectorOAuthPopupBlocked: "浏览器阻止了 GitHub 授权窗口，请允许弹窗后重试。",
-    connectorManageURLMissing: "GitHub App 管理地址为空，请重试。",
-    connectorManagePopupBlocked: "浏览器阻止了 GitHub App 管理窗口，请允许弹窗后重试。",
     localAgentConsole: "本地 Agent 控制台",
     loading: "正在加载 IM 工作区...",
     loadingFailed: "加载失败，请稍后重试。",
@@ -139,18 +108,17 @@ export const messages = {
     resourcesSkillPreviewHint: "在左侧文件树中选择 skill 文件以查看其内容",
     resourcesSkillFileLoadFailed: "Skill 文件内容加载失败，请稍后重试。",
     resourcesSkillUpload: "上传 skill",
-    resourcesSkillUploadSubtitle: "上传 zip，或从社区列表选择 skill。",
+    resourcesSkillUploadSubtitle: "上传 zip，或从官方远端列表选择 skill。",
     resourcesSkillUploadZipTab: "上传 zip",
-    resourcesSkillRemoteInstallTab: "社区安装",
-    resourcesSkillRemoteSkillsLoading: "正在加载社区 skills...",
-    resourcesSkillRemoteSkillsEmpty: "暂无社区 skills。",
-    resourcesSkillRemoteSkillsLoadFailed: "社区 skills 加载失败，请稍后重试。",
+    resourcesSkillRemoteInstallTab: "远端安装",
+    resourcesSkillRemoteSkillsLoading: "正在加载远端 skills...",
+    resourcesSkillRemoteSkillsEmpty: "暂无远端 skills。",
+    resourcesSkillRemoteSkillsLoadFailed: "远端 skills 加载失败，请稍后重试。",
     resourcesSkillRemoteInstallAction: "安装",
-    resourcesSkillRemoteReplaceAction: "替换",
     resourcesSkillRemoteInstalling: "安装中...",
-    resourcesSkillRemoteInstallFailed: "社区 skill 安装失败，请稍后重试。",
+    resourcesSkillRemoteInstallFailed: "远端 skill 安装失败，请稍后重试。",
     resourcesSkillRemoteRefresh: "刷新",
-    resourcesSkillRemoteSearchPlaceholder: "搜索社区 skill",
+    resourcesSkillRemoteSearchPlaceholder: "搜索远端 skill",
     resourcesSkillUploadDropTitle: "点击选择 zip，或拖拽到这里",
     resourcesSkillUploadDropHint: "仅支持 .zip，且压缩包内必须只包含一个合法 skill。",
     resourcesSkillUploadChoose: "选择 zip",
@@ -241,7 +209,8 @@ export const messages = {
     agentActivityTimelineLabel: "活动时间线",
     agentActivityTimelineSegment: "{label} #{index} {time}",
     agentActivityNoFilteredResults: "没有符合筛选的活动记录。",
-    agentProfileSkillsTab: "技能",
+    agentProfileSkillsTab: "skills",
+    agentProfileMCPTab: "MCP",
     agentSkillAdd: "添加技能",
     agentSkillAddSubtitle: "候选来自全局 skills，选择后会复制到当前 Agent 的 runtime skills 目录。",
     agentSkillAddFailed: "添加技能失败，请稍后重试。",
@@ -497,11 +466,9 @@ export const messages = {
     inputPlaceholder: "输入消息，使用 @ 选择成员",
     send: "发送",
     composerTip: "Enter 发送，Shift + Enter 换行。支持房间、私信和 @ 提及。",
-    messageLongExpand: "展开全文",
-    messageLongCollapse: "收起",
     profileSetupTitle: "配置 Manager Profile",
     profileSetupSubtitle: "自动检测没有找到可用模型。请完成 Manager 的运行配置后再开始对话。",
-    profileProvider: "模型提供方",
+    profileProvider: "服务商",
     profileModel: "模型",
     profileBaseURL: "Base URL",
     profileAPIKey: "API Key",
@@ -620,7 +587,6 @@ export const messages = {
     userIDLabel: "用户 ID",
     status: "状态",
     modelsSection: "模型",
-    resourcesModelProvidersSection: "模型提供方",
     modelProviderAdd: "添加 OpenAI API",
     modelProviderAvatar: "头像",
     modelProviderModelCount: "{count} 个模型",
@@ -635,7 +601,7 @@ export const messages = {
     modelProviderCreateIdentityDescription: "为侧边栏和 Agent 选择器设置一个清晰名称。",
     modelProviderCreateIdentityTitle: "身份",
     modelProviderCreateSubtitle: "添加一个 OpenAI 兼容 API 提供方。",
-    modelProviderCreateTitle: "添加 OpenAI API",
+    modelProviderCreateTitle: "添加模型提供方",
     modelProviderConfiguration: "配置",
     modelProviderDisplayName: "显示名称",
     modelProviderDuplicateDisplayName: "显示名称已存在，请换一个名称。",
@@ -692,11 +658,11 @@ export const messages = {
     createAgentKindNotificationDescription: "将事件发送到外部 Webhook 端点。",
     createAgentModeTabAriaLabel: "创建方式",
     createAgentModeTemplate: "从模板创建",
-    createAgentModeTemplateDescription: "选择模板继承运行时与默认配置。",
+    createAgentModeTemplateDescription: "选择模板继承运行时与默认配置，头像、名称和描述仍可自定义。",
     createAgentModeCustom: "自定义创建",
     createAgentModeCustomDescription: "手动配置运行时、模型和指令。",
     createAgentTemplateSectionTitle: "模板配置",
-    createAgentTemplateSectionDescription: "选择模板后会继承运行时与默认配置。",
+    createAgentTemplateSectionDescription: "选择模板后会继承运行时与默认配置，头像、名称和描述仍可自定义。",
     notificationsSection: "通知",
     createNotificationBot: "新建通知 Bot",
     noNotificationBots: "暂无通知 Bot",
@@ -946,37 +912,6 @@ export const messages = {
     csghubLoginURLMissing: "The sign-in URL was empty. Please retry.",
     csghubLoginCompleted: "{user} signed in.",
     csghubLogoutCompleted: "Signed out: {user}.",
-    connectorManagerTitle: "Manage connectors",
-    connectorGitHub: "GitHub",
-    connectorConnected: "Connected",
-    connectorConfigured: "Configured",
-    connectorSetUp: "Set up",
-    connectorNotConnected: "Not connected",
-    connectorConnect: "Connect",
-    connectorConnectGitHub: "Connect GitHub",
-    connectorGitHubConnectedAs: "GitHub connected: {user}",
-    connectorManage: "Manage",
-    connectorDisconnect: "Disconnect",
-    connectorEdit: "Edit",
-    connectorSave: "Save",
-    connectorClientID: "Client ID",
-    connectorClientSecret: "Client Secret",
-    connectorCallbackURL: "Callback URL",
-    connectorScopes: "Scopes",
-    connectorOAuthPending: "Waiting for GitHub authorization...",
-    connectorClientIDRequired: "Enter a GitHub Client ID.",
-    connectorClientSecretRequired: "Enter a GitHub Client Secret.",
-    connectorSaveFailed: "Failed to save GitHub connector.",
-    connectorNotConfigured: "Configure the GitHub OAuth Client ID and Client Secret before connecting.",
-    connectorConnectFailed: "Failed to start GitHub authorization.",
-    connectorManageFailed: "Failed to open GitHub App management.",
-    connectorDisconnectFailed: "Failed to disconnect GitHub.",
-    connectorStatusFailed: "Failed to read connector status.",
-    connectorLoginTimedOut: "GitHub authorization timed out. Please connect again.",
-    connectorOAuthURLMissing: "The GitHub authorization URL was empty. Please retry.",
-    connectorOAuthPopupBlocked: "The browser blocked the GitHub authorization window. Allow pop-ups and retry.",
-    connectorManageURLMissing: "The GitHub App management URL was empty. Please retry.",
-    connectorManagePopupBlocked: "The browser blocked the GitHub App management window. Allow pop-ups and retry.",
     localAgentConsole: "Local agent console",
     loading: "Loading IM workspace...",
     loadingFailed: "Failed to load the workspace. Please try again.",
@@ -1025,18 +960,17 @@ export const messages = {
     resourcesSkillPreviewHint: "Choose a skill file from the tree on the left to view its content",
     resourcesSkillFileLoadFailed: "Failed to load the skill file content. Please try again later.",
     resourcesSkillUpload: "Upload skill",
-    resourcesSkillUploadSubtitle: "Upload a zip file, or choose a skill from the community list.",
+    resourcesSkillUploadSubtitle: "Upload a zip file, or choose a skill from the official remote list.",
     resourcesSkillUploadZipTab: "Upload zip",
-    resourcesSkillRemoteInstallTab: "Community install",
-    resourcesSkillRemoteSkillsLoading: "Loading community skills...",
-    resourcesSkillRemoteSkillsEmpty: "No community skills yet.",
-    resourcesSkillRemoteSkillsLoadFailed: "Failed to load community skills. Please try again later.",
+    resourcesSkillRemoteInstallTab: "Remote install",
+    resourcesSkillRemoteSkillsLoading: "Loading remote skills...",
+    resourcesSkillRemoteSkillsEmpty: "No remote skills yet.",
+    resourcesSkillRemoteSkillsLoadFailed: "Failed to load remote skills. Please try again later.",
     resourcesSkillRemoteInstallAction: "Install",
-    resourcesSkillRemoteReplaceAction: "Replace",
     resourcesSkillRemoteInstalling: "Installing...",
-    resourcesSkillRemoteInstallFailed: "Failed to install the community skill. Please try again later.",
+    resourcesSkillRemoteInstallFailed: "Failed to install the remote skill. Please try again later.",
     resourcesSkillRemoteRefresh: "Refresh",
-    resourcesSkillRemoteSearchPlaceholder: "Search community skills",
+    resourcesSkillRemoteSearchPlaceholder: "Search remote skills",
     resourcesSkillUploadDropTitle: "Click to choose a zip, or drag it here",
     resourcesSkillUploadDropHint:
       "Only .zip files are supported, and the archive must contain exactly one valid skill.",
@@ -1124,7 +1058,8 @@ export const messages = {
     agentActivityTimelineLabel: "Activity timeline",
     agentActivityTimelineSegment: "{label} #{index} {time}",
     agentActivityNoFilteredResults: "No activity matches the current filters.",
-    agentProfileSkillsTab: "Skills",
+    agentProfileSkillsTab: "skills",
+    agentProfileMCPTab: "MCP",
     agentSkillAdd: "Add skill",
     agentSkillAddSubtitle:
       "Candidates come from global skills. Selected items will be copied into this agent's runtime skills directory.",
@@ -1390,12 +1325,10 @@ export const messages = {
     inputPlaceholder: "Type a message and use @ to mention members",
     send: "Send",
     composerTip: "Press Enter to send and Shift + Enter for a new line. Supports rooms, DMs, and @ mentions.",
-    messageLongExpand: "Expand full text",
-    messageLongCollapse: "Collapse",
     profileSetupTitle: "Manager Profile",
     profileSetupSubtitle:
       "Auto-detection did not find a usable model. Complete the manager runtime profile before chatting.",
-    profileProvider: "Model Provider",
+    profileProvider: "Provider",
     profileModel: "Model",
     profileBaseURL: "Base URL",
     profileAPIKey: "API Key",
@@ -1516,7 +1449,6 @@ export const messages = {
     userIDLabel: "User ID",
     status: "Status",
     modelsSection: "Models",
-    resourcesModelProvidersSection: "Model Providers",
     modelProviderAdd: "Add OpenAI API",
     modelProviderAvatar: "Avatar",
     modelProviderModelCount: "{count} models",
@@ -1531,7 +1463,7 @@ export const messages = {
     modelProviderCreateIdentityDescription: "Give this provider a clear name for the sidebar and agent selector.",
     modelProviderCreateIdentityTitle: "Identity",
     modelProviderCreateSubtitle: "Add an OpenAI-compatible API provider.",
-    modelProviderCreateTitle: "Add OpenAI API",
+    modelProviderCreateTitle: "Add model provider",
     modelProviderConfiguration: "Configuration",
     modelProviderDisplayName: "Display name",
     modelProviderDuplicateDisplayName: "Display name is already used. Choose another name.",
@@ -1590,11 +1522,13 @@ export const messages = {
     createAgentKindNotificationDescription: "Send events to an external webhook endpoint.",
     createAgentModeTabAriaLabel: "Create mode",
     createAgentModeTemplate: "From template",
-    createAgentModeTemplateDescription: "Pick a template to inherit runtime and defaults.",
+    createAgentModeTemplateDescription:
+      "Pick a template to inherit runtime and defaults; avatar, name, and description stay editable.",
     createAgentModeCustom: "Custom",
     createAgentModeCustomDescription: "Manually configure runtime, model, and instructions.",
     createAgentTemplateSectionTitle: "Template setup",
-    createAgentTemplateSectionDescription: "Selecting a template inherits runtime and default settings.",
+    createAgentTemplateSectionDescription:
+      "Selecting a template inherits runtime and default settings, while avatar, name, and description remain editable.",
     notificationsSection: "Notifications",
     createNotificationBot: "New notification bot",
     noNotificationBots: "No notification bots yet",
diff --git a/web/app/tests/components/AgentActions.test.tsx b/web/app/tests/components/AgentActions.test.tsx
index fadc3274..1e070654 100644
--- a/web/app/tests/components/AgentActions.test.tsx
+++ b/web/app/tests/components/AgentActions.test.tsx
@@ -24,6 +24,7 @@ const labels: Record<string, string> = {
   agentProfileSectionNavLabel: "Profile sections",
   agentProfileTab: "Profile",
   agentProfileSkillsTab: "skills",
+  agentProfileMCPTab: "MCP",
   agentSaved: "Saved",
   agentSaveChanges: "Save changes",
   agentUpdateSave: "Save",
@@ -806,7 +807,7 @@ describe("agent action visibility", () => {
     expect(screen.queryByLabelText("Image")).not.toBeInTheDocument();
   });
 
-  it("edits MCP runtime options in the detail runtime section for OpenClaw agents", async () => {
+  it("edits MCP config in the detail MCP tab for supported agents", async () => {
     const user = userEvent.setup();
     const onDraftChange = vi.fn();
     const item = {
@@ -814,11 +815,11 @@ describe("agent action visibility", () => {
       runtime_kind: "openclaw_sandbox",
       runtime_options: {
         local_workspace_dir: "/tmp/project",
-        mcp: {
-          mcpServers: {
-            existing: {
-              command: "node",
-            },
+      },
+      mcp_config: {
+        mcpServers: {
+          existing: {
+            command: "node",
           },
         },
       },
@@ -839,6 +840,7 @@ describe("agent action visibility", () => {
         saveError=""
         authStatuses={{}}
         authBusyProvider=""
+        workspaceSupported
         notifierWebhookPublicOrigin="http://127.0.0.1:18080"
         onDraftChange={onDraftChange}
         onSave={vi.fn()}
@@ -853,7 +855,18 @@ describe("agent action visibility", () => {
       />,
     );
 
-    await user.click(screen.getByRole("button", { name: "Runtime environment" }));
+    expect(screen.queryByLabelText("MCP Servers")).not.toBeInTheDocument();
+    const navigation = screen.getByRole("navigation", { name: "Profile sections" });
+    expect(within(navigation).getAllByRole("button").map((button) => button.textContent)).toEqual([
+      "Profile",
+      "Activity",
+      "Channels",
+      "Instructions",
+      "skills",
+      "MCP",
+    ]);
+
+    await user.click(within(navigation).getByRole("button", { name: "MCP" }));
 
     const editor = screen.getByLabelText("MCP Servers");
     expect((editor as HTMLTextAreaElement).value).toContain('"existing"');
@@ -868,11 +881,11 @@ describe("agent action visibility", () => {
       expect.objectContaining({
         runtime_options: {
           local_workspace_dir: "/tmp/project",
-          mcp: {
-            mcpServers: {
-              context7: {
-                command: "npx",
-              },
+        },
+        mcp_config: {
+          mcpServers: {
+            context7: {
+              command: "npx",
             },
           },
         },
@@ -880,6 +893,68 @@ describe("agent action visibility", () => {
     );
   });
 
+  it("keeps invalid MCP config blocking save after switching tabs", async () => {
+    const user = userEvent.setup();
+    const item = {
+      ...worker,
+      runtime_kind: "openclaw_sandbox",
+      runtime_options: {},
+      mcp_config: {
+        mcpServers: {
+          existing: {
+            command: "node",
+          },
+        },
+      },
+    };
+
+    render(
+      <AgentDetailPane
+        item={item}
+        t={t}
+        activeRoom={null}
+        busyKey=""
+        error=""
+        draft={agentToDraft(item)}
+        models={[]}
+        modelBusy={false}
+        saving={false}
+        publishBusy={false}
+        saveError=""
+        authStatuses={{}}
+        authBusyProvider=""
+        workspaceSupported
+        notifierWebhookPublicOrigin="http://127.0.0.1:18080"
+        onDraftChange={vi.fn()}
+        onSave={vi.fn()}
+        onPublish={vi.fn()}
+        onProviderLogin={vi.fn()}
+        onStart={vi.fn()}
+        onStop={vi.fn()}
+        onRecreate={vi.fn()}
+        onDelete={vi.fn()}
+        onInvite={vi.fn()}
+        onOpenDM={vi.fn()}
+      />,
+    );
+
+    const navigation = screen.getByRole("navigation", { name: "Profile sections" });
+    await user.click(within(navigation).getByRole("button", { name: "MCP" }));
+
+    const editor = screen.getByLabelText("MCP Servers");
+    fireEvent.input(editor, { target: { value: "{" } });
+
+    expect(screen.getByText("Enter a valid JSON object.")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Save changes" })).toBeDisabled();
+
+    await user.click(within(navigation).getByRole("button", { name: "Profile" }));
+    expect(screen.getByRole("button", { name: "Save changes" })).toBeDisabled();
+
+    await user.click(within(navigation).getByRole("button", { name: "MCP" }));
+    expect(screen.getByLabelText("MCP Servers")).toHaveValue("{");
+    expect(screen.getByRole("button", { name: "Save changes" })).toBeDisabled();
+  });
+
   it("shows a saved status instead of a save button when the draft is unchanged", () => {
     const draft = agentToDraft(worker);
     render(
@@ -1226,7 +1301,14 @@ describe("agent action visibility", () => {
 
     const navigation = screen.getByRole("navigation", { name: "Profile sections" });
     const tabs = within(navigation).getAllByRole("button");
-    expect(tabs.map((tab) => tab.textContent)).toEqual(["Profile", "Activity", "Channels", "Instructions", "skills"]);
+    expect(tabs.map((tab) => tab.textContent)).toEqual([
+      "Profile",
+      "Activity",
+      "Channels",
+      "Instructions",
+      "skills",
+      "MCP",
+    ]);
     expect(tabs[0]).toHaveAttribute("aria-current", "location");
     expect(screen.getByText("Request options")).toBeInTheDocument();
     expect(screen.queryByRole("heading", { name: "Channels" })).not.toBeInTheDocument();
diff --git a/web/app/tests/components/AgentProfileModal.test.tsx b/web/app/tests/components/AgentProfileModal.test.tsx
index ab7663e7..76be5310 100644
--- a/web/app/tests/components/AgentProfileModal.test.tsx
+++ b/web/app/tests/components/AgentProfileModal.test.tsx
@@ -854,7 +854,7 @@ describe("AgentProfileModal", () => {
     );
   });
 
-  it("edits MCP runtime options only for OpenClaw agent drafts", async () => {
+  it("edits MCP config for supported agent drafts", async () => {
     const user = userEvent.setup();
     const onAgentDraftChange = vi.fn();
     const openclawDraft = {
@@ -863,11 +863,11 @@ describe("AgentProfileModal", () => {
       runtime_kind: "openclaw_sandbox",
       runtime_options: {
         local_workspace_dir: "/tmp/project",
-        mcp: {
-          mcpServers: {
-            existing: {
-              command: "node",
-            },
+      },
+      mcp_config: {
+        mcpServers: {
+          existing: {
+            command: "node",
           },
         },
       },
@@ -915,11 +915,11 @@ describe("AgentProfileModal", () => {
       expect.objectContaining({
         runtime_options: {
           local_workspace_dir: "/tmp/project",
-          mcp: {
-            mcpServers: {
-              context7: {
-                command: "npx",
-              },
+        },
+        mcp_config: {
+          mcpServers: {
+            context7: {
+              command: "npx",
             },
           },
         },
@@ -933,6 +933,7 @@ describe("AgentProfileModal", () => {
         runtime_options: {
           local_workspace_dir: "/tmp/project",
         },
+        mcp_config: undefined,
       }),
     );
 
@@ -968,10 +969,10 @@ describe("AgentProfileModal", () => {
       />,
     );
 
-    expect(screen.queryByLabelText("MCP Servers")).not.toBeInTheDocument();
+    expect(screen.getByLabelText("MCP Servers")).toBeInTheDocument();
   });
 
-  it("drops MCP runtime options when OpenClaw drafts switch to unsupported runtimes", async () => {
+  it("preserves MCP config when switching between MCP-capable runtimes", async () => {
     const user = userEvent.setup();
     const onAgentDraftChange = vi.fn();
     const openclawDraft: AgentDraft = {
@@ -983,11 +984,11 @@ describe("AgentProfileModal", () => {
       sandbox_enabled: true,
       runtime_options: {
         local_workspace_dir: "/tmp/project",
-        mcp: {
-          mcpServers: {
-            context7: {
-              command: "npx",
-            },
+      },
+      mcp_config: {
+        mcpServers: {
+          context7: {
+            command: "npx",
           },
         },
       },
@@ -1047,7 +1048,14 @@ describe("AgentProfileModal", () => {
     const nextDraft = onAgentDraftChange.mock.calls.at(-1)?.[0] as AgentDraft;
     expect(nextDraft.runtime_kind).toBe("picoclaw_sandbox");
     expect(nextDraft.runtime_options).toEqual({ local_workspace_dir: "/tmp/project" });
-    expect(screen.queryByLabelText("MCP Servers")).not.toBeInTheDocument();
+    expect(nextDraft.mcp_config).toEqual({
+      mcpServers: {
+        context7: {
+          command: "npx",
+        },
+      },
+    });
+    expect(screen.getByLabelText("MCP Servers")).toBeInTheDocument();
   });
 
   it("shows provider logos only in the provider field, not in the model field", () => {
diff --git a/web/app/tests/models/agents.test.ts b/web/app/tests/models/agents.test.ts
index 69a5ccab..e6f0151a 100644
--- a/web/app/tests/models/agents.test.ts
+++ b/web/app/tests/models/agents.test.ts
@@ -30,14 +30,14 @@ import {
   mergeAgentIntoList,
   isNotificationBotAgent,
   mapToEnvRows,
-  mcpRuntimeOptionsText,
+  mcpConfigText,
   partitionWorkspaceAgentItems,
   notifierComputedPullRoutes,
   notifierFormIsComplete,
   notifierThirdPartyRelayWebhookURL,
   normalizeAuthProviderName,
   normalizeRuntimeKind,
-  parseMCPRuntimeOptionsText,
+  parseMCPConfigText,
   notificationPushWebhookPathForBot,
   parseJSONMap,
   pickDefaultAgentTemplate,
@@ -49,10 +49,11 @@ import {
   resolveAgentAvatarSource,
   runtimeImageForKind,
   runtimeOptionSchemasForAgent,
-  setMCPRuntimeOptions,
+  setMCPConfig,
   localizedRuntimeOptionLabel,
   localizedRuntimeOptionDescription,
-  supportsMCPRuntimeOptions,
+  draftMCPConfigForSave,
+  supportsMCPConfig,
   shouldWaitForManagerRuntimeAfterProfileSave,
   workerSelectableTemplates,
 } from "@/models/agents";
@@ -510,8 +511,8 @@ describe("agent model helpers", () => {
     ).toBe("Leave empty to use the default agent workspace.");
   });
 
-  it("parses and saves OpenClaw MCP runtime options under runtime_options.mcp", () => {
-    const parsed = parseMCPRuntimeOptionsText('{"mcpServers":{"context7":{"command":"npx","args":["-y"]}}}');
+  it("parses and saves MCP config under top-level mcp_config", () => {
+    const parsed = parseMCPConfigText('{"mcpServers":{"context7":{"command":"npx","args":["-y"]}}}');
 
     expect(parsed).toEqual({
       ok: true,
@@ -524,31 +525,27 @@ describe("agent model helpers", () => {
         },
       },
     });
-    expect(parseMCPRuntimeOptionsText("")).toEqual({ ok: true, value: null });
-    expect(parseMCPRuntimeOptionsText("[1]")).toEqual({ ok: false, error: "object_required" });
-    expect(parseMCPRuntimeOptionsText("{")).toEqual({ ok: false, error: "invalid_json" });
-    expect(supportsMCPRuntimeOptions("openclaw_sandbox")).toBe(true);
-    expect(supportsMCPRuntimeOptions("picoclaw_sandbox")).toBe(false);
-
-    const runtimeOptions = setMCPRuntimeOptions(
-      { local_workspace_dir: "/tmp/project" },
-      { mcpServers: { context7: { command: "npx" } } },
-    );
-    expect(runtimeOptions).toEqual({
-      local_workspace_dir: "/tmp/project",
-      mcp: {
-        mcpServers: {
-          context7: {
-            command: "npx",
-          },
+    expect(parseMCPConfigText("")).toEqual({ ok: true, value: null });
+    expect(parseMCPConfigText("[1]")).toEqual({ ok: false, error: "object_required" });
+    expect(parseMCPConfigText("{")).toEqual({ ok: false, error: "invalid_json" });
+    expect(supportsMCPConfig("openclaw_sandbox")).toBe(true);
+    expect(supportsMCPConfig("picoclaw_sandbox")).toBe(true);
+    expect(supportsMCPConfig("codex")).toBe(true);
+
+    const mcpConfig = setMCPConfig({ mcpServers: { context7: { command: "npx" } } });
+    expect(mcpConfig).toEqual({
+      mcpServers: {
+        context7: {
+          command: "npx",
         },
       },
     });
-    expect(mcpRuntimeOptionsText(runtimeOptions)).toContain('"mcpServers"');
-    expect(draftRuntimeOptionsForSave({ runtime_options: runtimeOptions })).toEqual(runtimeOptions);
-    expect(setMCPRuntimeOptions(runtimeOptions, null)).toEqual({
+    expect(mcpConfigText(mcpConfig)).toContain('"mcpServers"');
+    expect(draftMCPConfigForSave({ mcp_config: mcpConfig })).toEqual(mcpConfig);
+    expect(draftRuntimeOptionsForSave({ runtime_options: { local_workspace_dir: "/tmp/project" } })).toEqual({
       local_workspace_dir: "/tmp/project",
     });
+    expect(setMCPConfig(null)).toBeUndefined();
   });
 
   it("selects runtime-specific templates and images", () => {