ClawPanel 是一个开源的 OpenClaw 智能管理面板，提供比官方控制台更强大的可视化管理能力。支持 20+ 通道接入、多模型配置、技能中心、插件管理、定时任务等功能。

GitHub：https://github.com/zhaoxinyi02/ClawPanel

---

📌 本次更新概览

v4.4.0 是一次功能 + 兼容性 + 体验三合一的更新，主要包含：

类型	内容
🆕 新功能	AI 智能助手浮窗
🔧 兼容性	修复非 OpenAI 模型的 developer 角色错误
🎨 UI	技能中心布局优化、AI 助手最大化/还原

---

🤖 新功能：AI 智能助手

功能介绍

在 ClawPanel 管理面板的右下角新增了一个浮窗式 AI 对话助手，可以随时与已配置的 AI 模型进行对话。

核心特性

• 拖拽移动：按住标题栏可自由拖拽到屏幕任意位置
• 调整大小：右下角拖拽手柄可自由调整窗口大小
• 最大化/还原：一键最大化到屏幕中央，再次点击还原到之前的位置和大小
• 模型选择：下拉选择已配置的模型提供商和具体模型
• 深色模式：完美适配 ClawPanel 的深色/浅色主题
• 收起/展开：点击收起按钮折叠为右下角小图标

技术实现

AI 助手组件 AIAssistant.tsx 使用纯 React 实现，核心技术点：

// 拖拽：mousedown + mousemove + mouseup 事件链
const onDragStart = useCallback((e: React.MouseEvent) => {
  dragging.current = true;
  dragOffset.current = { x: e.clientX - pos.x, y: e.clientY - pos.y };
}, [pos]);

// 最大化/还原：保存之前的位置和大小
const [isMaximized, setIsMaximized] = useState(false);
const savedPosSize = useRef({ x: 0, y: 0, w: DEFAULT_W, h: DEFAULT_H });

后端新增 /api/ai/chat 接口，接收聊天历史和模型选择，调用 OpenClaw 的 AI 模型进行对话：

router.post('/ai/chat', auth, async (req, res) => {
  const { messages, providerId, modelId } = req.body;
  // 调用 OpenClaw 模型 API
  const response = await callModel(messages, providerId, modelId);
  res.json({ ok: true, reply: response });
});

---

🔧 重点修复：非 OpenAI 模型兼容性

问题描述

当用户在 ClawPanel 中切换到非 OpenAI 模型（如火山引擎 Doubao、DeepSeek 等）时，会出现以下错误：

Message ordering conflict - please try again.
If this persists, use /new to start a fresh session.

底层错误为：

invalid value: developer (expected one of: system, user, assistant)

根因分析

OpenClaw 使用 @mariozechner/pi-ai 库与模型 API 通信。该库在构造请求时，对于启用了 reasoning: true 的模型，会将系统提示词的角色设置为 developer：

// @mariozechner/pi-ai/dist/providers/openai-completions.js
const useDeveloperRole = model.reasoning && compat.supportsDeveloperRole;
const role = useDeveloperRole ? "developer" : "system";

developer 角色是 OpenAI 专有的概念（用于 o1/o3 等推理模型），火山引擎、DeepSeek 等 OpenAI 兼容 API 并不支持。

解决方案（三重保护）

1. 补丁 pi-ai 源码

直接修改 openai-completions.js 和 openai-responses-shared.js，强制使用 system 角色：

// 修改前
const role = useDeveloperRole ? "developer" : "system";

// 修改后
const role = "system"; // patched: always use system role for compatibility

2. 配置层注入 compat 标志

在 ClawPanel 后端保存配置时，自动为所有非 OpenAI 提供商注入兼容性标志：

function patchModelsJsonCompat() {
  const modelsPath = path.join(ocDir, 'agents', 'main', 'agent', 'models.json');
  const data = JSON.parse(fs.readFileSync(modelsPath, 'utf-8'));
  for (const [, prov] of Object.entries(data?.providers || {})) {
    const isNativeOpenAI = (prov.baseUrl || '').includes('api.openai.com');
    if (!isNativeOpenAI) {
      for (const m of prov.models) {
        if (!m.compat) m.compat = {};
        m.compat.supportsDeveloperRole = false;
      }
    }
  }
  fs.writeFileSync(modelsPath, JSON.stringify(data, null, 2));
}

3. 设置 reasoning=false

对于非 OpenAI 模型，将 reasoning 设置为 false，从根源上避免触发 developer 角色逻辑。

为什么需要三重保护？

层级	作用	原因
pi-ai 源码补丁	强制 system 角色	最可靠，直接修改发送请求的代码
compat 标志注入	告诉 pi-ai 不支持 developer	OpenClaw 可能重新生成 models.json
reasoning=false	避免触发 developer 逻辑	即使 compat 被覆盖也不会出错

---

🎨 UI 优化：技能中心布局

问题

技能和插件卡片在小屏幕上，启用/禁用的开关按钮会被推到屏幕外，需要水平滚动才能看到。

修复

使用 shrink-0 确保开关按钮永远不会被压缩，同时优化 flex 布局：

<div className="flex items-center gap-2 shrink-0 ml-2">
  <button onClick={() => toggleSkill(skill.id)} className="shrink-0">
    {skill.enabled ? <ToggleRight size={36} /> : <ToggleLeft size={36} />}
  </button>
</div>

---

📦 如何更新

Docker 用户

cd ClawPanel
git pull
docker compose up -d --build

原生安装用户

cd ClawPanel
git pull
npm run build --prefix web
npm run build --prefix server
# 重启 ClawPanel 服务

火山引擎/DeepSeek 用户额外步骤

如果你使用火山引擎或 DeepSeek 等非 OpenAI 模型，更新后需要：

1. 在 ClawPanel 系统配置 → 模型配置中保存一次配置（触发自动兼容性修复）
2. 重启网关

---

🔗 相关链接

• GitHub：https://github.com/zhaoxinyi02/ClawPanel
• 在线演示：http://demo.zhaoxinyi.xyz
• 完整更新日志：CHANGELOG

---

ClawPanel — 比官方控制台更强大的 OpenClaw 可视化管理工具。如果觉得有用，欢迎 Star ⭐

本项目仅供学习研究使用，严禁商用。