一天一个开源项目（第67篇）：OpenClaw-Admin - AI Agent 网关的可视化管理驾驶舱

引言

"把 AI Agent 部署到每个人最常用的聊天工具里，让 AI 无处不在。"

这是「一天一个开源项目」系列的第 67 篇文章。今天介绍的项目是 OpenClaw-Admin （GitHub）。

在 AI Agent 大规模落地的今天，一个棘手的问题摆在开发者面前：我部署了一个强大的 AI Agent，但用户要在哪里使用它？专门开发一个 App 成本太高，而 OpenClaw 的思路是------让 Agent 直接入驻用户已有的 IM 平台（QQ、飞书、钉钉、企业微信），这样用户无需改变习惯，Agent 就能触达每一个人。

OpenClaw-Admin 就是这个多渠道 AI Agent 网关的"驾驶舱"------一个基于 Vue 3 + TypeScript 的现代化 Web 管理后台，提供从 Agent 配置、会话管理、模型接入到远程终端、系统监控的全套可视化管理能力。

你将学到什么

• OpenClaw 生态的整体架构与 OpenClaw-Admin 的定位
• Vue 3 + Composition API + Naive UI 的管理后台最佳实践
• 如何通过 Web 界面管理多渠道 AI Agent 的完整生命周期
• 基于 Express + SQLite + WebSocket 的轻量全栈方案
• 远程终端（xterm.js）、SSH 连接、系统监控等高级功能实现思路

前置知识

• 了解 Vue 3 基本概念（Composition API、Pinia）
• 有 AI Agent / LLM API 使用经验
• 熟悉 Node.js 基本生态

---

项目背景

项目简介

OpenClaw-Admin 是 OpenClaw Gateway 生态的前端管理控制台。OpenClaw Gateway 是一个多渠道 AI Agent 运行时，核心价值是将 AI 智能体桥接到 QQ、飞书、钉钉、企业微信等主流 IM 平台，让用户在熟悉的聊天软件里直接与 Agent 交互。

OpenClaw-Admin 作为网关的"大脑"，提供完整的 Web 可视化管理能力：

• 智能体管理：配置 Agent 身份、能力、权限
• 渠道配置：连接各 IM 平台的 API/机器人
• 模型接入：管理 OpenAI、Claude、本地模型等多模型提供商
• 会话监控：实时追踪所有用户与 Agent 的对话
• 运维工具：内置远程终端、SSH、桌面访问、文件浏览器

作者介绍

• 作者 ：itq5
• 背景：西南大学继续教育学院，个人开发者
• 风格：高频迭代，从 2026 年 3 月到 4 月持续发布新版本（v0.1.x → v0.2.x）
• 专长：API 格式转换代理、Web 工具、AI/LLM 集成

项目数据

• ⭐ GitHub Stars: 276
• 🍴 Forks: 87
• 🐛 Open Issues: 11
• 📦 最新版本: v0.2.6
• 📄 License: MIT
• 🔄 活跃状态: 最近更新于 2026 年 4 月

---

主要功能

核心作用

OpenClaw-Admin 提供约 17 个功能模块，覆盖 AI Agent 管理的完整生命周期：

功能模块	说明
登录 & 仪表盘	安全登录，实时展示 Token 用量趋势、活跃会话统计
在线对话	支持斜杠命令（/new、/skill、/model）的实时对话界面
会话管理	创建、监控、删除 Agent 会话，含历史导出
记忆管理	内置 Markdown 编辑器，编辑 AGENTS/SOUL/IDENTITY 等核心文档
定时任务	Cron 表达式配置自动化任务，含执行历史
多渠道支持	集成 QQ、飞书、钉钉、企业微信
模型配置	管理多模型 API，安全存储密钥
技能管理	插件安装、控制技能在对话中的可见性
多智能体协作	创建独立身份和权限的多个 Agent
远程终端	SSE 实现终端模拟，支持 SSH 远程连接
远程桌面	Linux/Windows 远程桌面访问
文件浏览器	远程文件浏览、编辑和传输
系统监控	CPU、内存、磁盘、网络实时可视化
虚拟办公室	多角色交互的虚拟协作环境
Agent 工坊	多实体协作场景编排
备份/恢复	系统数据一键备份与恢复
PDF 查看器	内置 PDF 查看，支持 LaTeX 公式渲染

使用场景

1. 企业 AI 助手部署

   • 将 ChatGPT/Claude 等 AI 能力接入企业飞书/钉钉，员工无需切换工具即可使用 AI

2. 开发者个人 Agent 托管

   • 在个人服务器部署 OpenClaw 网关，通过 Admin 界面管理多个专属 AI 助手

3. 多模型路由管理

   • 统一管理多个 AI 模型提供商，根据场景灵活切换模型

4. 运维辅助 Agent

   • 结合远程终端和系统监控功能，让 Agent 直接参与服务器运维

5. 团队知识 AI 化

   • 通过记忆管理功能为 Agent 注入团队专属知识库

快速开始

# 克隆仓库
git clone https://github.com/itq5/OpenClaw-Admin.git
cd OpenClaw-Admin

# 安装依赖（Node.js >= 18）
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env，填写 OpenClaw Gateway 连接地址等

# 同时启动前端和后端（推荐）
npm run dev:all

# 访问管理界面
# http://localhost:3000

生产部署：

# 构建前端
npm run build

# 启动生产服务器
npm run start

核心特性

1. Vue 3 + Composition API

   • 全面使用 <script setup> 语法，逻辑按功能组织而非选项分离，可维护性更强

2. Naive UI 组件库

   • 基于 Naive UI 构建，组件风格统一，支持暗色/亮色主题切换

3. Pinia 状态管理

   • 按业务域拆分 Store（session、agent、model 等），状态流转清晰

4. 轻量全栈

   • 后端仅用 Express + SQLite，无需重型数据库，适合个人或小团队部署

5. 实时通信

   • 前后端通过 WebSocket 实现实时数据推送，终端和监控数据无延迟

6. 内置国际化

   • 开箱支持中文/英文双语，可在设置中无缝切换

7. 多模型统一管理

   • 安全存储多个 AI 提供商 API Key，界面化配置模型参数

8. xterm.js 远程终端

   • 基于 @xterm/xterm 6.x 实现浏览器终端，支持 SSH 远程连接

项目优势

对比维度	OpenClaw-Admin	Dify	One-API
IM 平台集成	✅ QQ/飞书/钉钉/企微	❌ 无原生支持	❌ 无原生支持
管理后台	✅ 全功能 Web UI	✅ 全功能	✅ 基础功能
远程运维工具	✅ 终端+桌面+文件管理	❌	❌
部署复杂度	✅ Node.js 单栈	中（Docker）	✅ 低
多模型管理	✅	✅	✅ 专注于此
开源协议	MIT	Apache 2.0	MIT

为什么选择 OpenClaw-Admin？

• 唯一专为 IM 平台 Agent 部署设计的管理后台
• 前后端一体的轻量部署，无需额外运维
• 内置运维工具减少切换工具的成本

---

项目详细剖析

整体架构

OpenClaw-Admin 采用前后端一体的架构，同一个 Node.js 进程同时提供：

• 静态资源服务：分发 Vite 构建的 Vue 3 前端
• REST API：处理前端的数据请求（Agent 配置、会话数据等）
• WebSocket 服务：实时推送终端输出、系统监控数据
• SSE（Server-Sent Events）：单向实时数据流

Browser (Vue 3 SPA)
     │
     ├── HTTP REST ────────→ Express Routes
     │                          │
     ├── WebSocket ────────→ ws Server ──→ node-pty (终端)
     │                          │         ssh2 (SSH)
     └── SSE ──────────────→ Express SSE ─→ 系统指标采集
                               │
                          SQLite (better-sqlite3)
                               │
                          OpenClaw Gateway API

前端架构剖析

目录结构

src/
├── api/          # RPC 客户端，封装所有后端 API 调用
├── stores/       # Pinia Store，按业务域分类
│   ├── session.ts      # 会话状态
│   ├── agent.ts        # Agent 配置
│   ├── model.ts        # 模型提供商
│   └── ...
├── views/        # 各功能页面组件（约 17 个功能对应的视图）
├── composables/  # 可复用 Vue 3 组合函数（use* 命名约定）
│   ├── useTheme.ts     # 主题切换
│   ├── useTerminal.ts  # 终端控制
│   └── ...
└── i18n/         # 中英文国际化资源

Composition API 最佳实践

项目严格遵循 <script setup> 风格，以 useTerminal.ts 为例：

// composables/useTerminal.ts
import { ref, onMounted, onUnmounted } from 'vue'
import { Terminal } from '@xterm/xterm'
import { FitAddon } from '@xterm/addon-fit'

export function useTerminal(containerId: string) {
  const terminal = ref<Terminal | null>(null)
  const fitAddon = new FitAddon()

  onMounted(() => {
    terminal.value = new Terminal({
      cursorBlink: true,
      theme: { background: '#1e1e1e' }
    })
    terminal.value.loadAddon(fitAddon)
    terminal.value.open(document.getElementById(containerId)!)
    fitAddon.fit()
  })

  onUnmounted(() => {
    terminal.value?.dispose()
  })

  const write = (data: string) => terminal.value?.write(data)
  const resize = () => fitAddon.fit()

  return { terminal, write, resize }
}

逻辑完全封装在 Composable 里，View 组件只关心 UI 渲染：

<!-- views/Terminal.vue -->
<script setup lang="ts">
import { useTerminal } from '@/composables/useTerminal'

const { write, resize } = useTerminal('terminal-container')
// 其余逻辑：WebSocket 连接、输入处理...
</script>

<template>
  <div id="terminal-container" class="h-full" />
</template>

后端架构剖析

Express + SQLite 轻量全栈

后端位于 server/ 目录，核心设计原则是极简：

// server/index.js（简化示意）
import express from 'express'
import { WebSocketServer } from 'ws'
import Database from 'better-sqlite3'

const app = express()
const db = new Database('data.sqlite')

// REST API 路由
app.use('/api/agents', agentRouter(db))
app.use('/api/sessions', sessionRouter(db))
app.use('/api/models', modelRouter(db))

// 静态资源（生产环境）
app.use(express.static('dist'))

// HTTP 服务器
const server = app.listen(3000)

// WebSocket 附着于同一端口
const wss = new WebSocketServer({ server })
wss.on('connection', handleTerminalConnection)

SQLite 通过 better-sqlite3 同步 API 操作，避免了异步数据库操作的复杂性：

// 同步读取，代码简洁
const agents = db.prepare('SELECT * FROM agents WHERE active = 1').all()
const agent = db.prepare('SELECT * FROM agents WHERE id = ?').get(agentId)

终端实现：node-pty + xterm.js

远程终端是项目的技术亮点之一，通过 node-pty （伪终端）在服务器端模拟终端进程，再通过 WebSocket 实时传输到前端的 xterm.js 渲染：

// server/terminal.js（简化示意）
import pty from 'node-pty'

function createTerminalSession(ws) {
  // 创建伪终端进程（bash/sh）
  const ptyProcess = pty.spawn('bash', [], {
    name: 'xterm-color',
    cols: 80,
    rows: 24,
    cwd: process.env.HOME,
    env: process.env
  })

  // 终端输出 → WebSocket → 前端 xterm.js
  ptyProcess.onData((data) => {
    ws.send(JSON.stringify({ type: 'output', data }))
  })

  // 前端输入 → WebSocket → 伪终端
  ws.on('message', (msg) => {
    const { type, data } = JSON.parse(msg)
    if (type === 'input') ptyProcess.write(data)
    if (type === 'resize') ptyProcess.resize(data.cols, data.rows)
  })

  ws.on('close', () => ptyProcess.kill())
}

记忆管理：SOUL/IDENTITY 设计

OpenClaw 体系中最有意思的设计之一是将 Agent 的"人格"和"知识"拆分为多个 Markdown 文档：

文档类型	作用
AGENTS.md	Agent 的能力边界和权限设定
SOUL.md	Agent 的个性、语气、行为风格
IDENTITY.md	Agent 的身份背景和角色设定
USER.md	用户相关的上下文信息

OpenClaw-Admin 提供内置 Markdown 编辑器让管理员直接编辑这些文档，相当于在给 Agent "写灵魂"。这个设计让非技术用户也能调整 Agent 行为，而不需要修改提示词工程代码。

国际化实现

项目的 i18n 基于 src/i18n/ 目录的 JSON 资源文件，通过 Vue I18n 实现：

// 中文资源
{
  "dashboard": {
    "title": "仪表盘",
    "tokenUsage": "Token 使用量",
    "activeSessions": "活跃会话"
  }
}

// 英文资源
{
  "dashboard": {
    "title": "Dashboard",
    "tokenUsage": "Token Usage",
    "activeSessions": "Active Sessions"
  }
}

用户在设置界面切换语言后，整个界面无需刷新即可完成语言切换。

---

项目地址与资源

官方资源

• 🌟 GitHub : github.com/itq5/OpenCl...
• 🐛 Issue Tracker : github.com/itq5/OpenCl...
• 📦 最新版本: v0.2.6

OpenClaw 生态相关项目

• OpenClaw Gateway（主体）: AI Agent 多渠道运行时
• awesome-openclaw-agents: 187 个生产就绪的 AI Agent 模板（SOUL.md 格式）

技术栈参考

• Vue 3 文档 - 核心框架
• Naive UI - UI 组件库
• Pinia - 状态管理
• xterm.js - 终端模拟

---

总结与展望

核心要点回顾

1. 定位独特：OpenClaw-Admin 是专为 IM 平台 AI Agent 部署设计的管理后台，解决了"Agent 如何触达用户"这个关键问题
2. 技术现代：Vue 3 + TypeScript + Composition API + Naive UI，是 2025 年现代 Web 管理后台的典型实践
3. 功能完整：从 Agent 配置到远程终端，17 个模块覆盖 Agent 运维全生命周期
4. 部署简单：前后端一体的 Node.js 栈，无需复杂的微服务架构
5. 设计亮点：SOUL/IDENTITY 文档化 Agent 人格的思路，让非技术用户也能参与 Agent 定制

适用人群

• AI 应用开发者：需要将 AI 能力接入企业 IM 平台的工程师
• Vue 3 学习者：想参考生产级 Vue 3 + TypeScript 管理后台实现的开发者
• 个人 AI 爱好者：想在私有服务器部署和管理多个 AI 助手的技术玩家
• 企业技术团队：探索 AI 辅助运维和知识管理的团队

---

欢迎来我的个人主页找到更多有用的知识和有趣的产品