# xclaw

**Repository Path**: x-claw/xclaw

## Basic Information

- **Project Name**: xclaw
- **Description**: openclaw 管理工具
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xclaw

<div align="center">

🦐 **OpenClaw GUI 管理工具** - AI Agent 框架的可视化管理界面

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/openclaw/xclaw)

[English](#english) | [中文文档](#中文文档)

</div>

---

## 中文文档

### ✨ 功能特性

xclaw 是 OpenClaw AI Agent 框架的官方图形化管理工具，为非开发者用户提供简单直观的可视化界面。

#### 🎯 核心亮点

- **🚀 一键部署** - 自动检测系统、安装 Node.js、配置 OpenClaw
- **🎨 可视化管理** - 图形化配置，告别 JSON 手工编辑
- **📊 实时监控** - 状态监控、日志查看、费用统计
- **🌐 国际化支持** - 完整的中英文界面
- **🌙 深色模式** - 护眼的深色主题，跟随系统自动切换

#### 📱 界面模块

| 模块 | 功能 | 状态 |
|------|------|------|
| 概览 Dashboard | OpenClaw 状态总览、快速操作 | ✅ |
| 配置管理 Configuration | 表单式配置、JSON 编辑器 | ✅ |
| AI 模型 Models | 多提供商支持、API Key 管理 | ✅ |
| 通道集成 Channels | 飞书/微信/钉钉/Telegram/Discord/Slack | ✅ |
| 日志监控 Logs | 实时日志、过滤、导出 | ✅ |
| 费用统计 Costs | Token 用量、成本统计 | ✅ |
| 记忆管理 Memory | 记忆搜索、编辑、删除 | ✅ |
| 应用设置 Settings | 主题、语言、行为配置 | ✅ |

#### 🤖 支持的 AI 模型

- **OpenAI** - GPT-4, GPT-3.5 Turbo
- **DeepSeek** - DeepSeek Chat, DeepSeek Coder (推荐)
- **智谱 AI** - ChatGLM-4, ChatGLM-3 Turbo
- **Anthropic** - Claude 3 Opus, Claude 3 Sonnet
- **Moonshot** - Moonshot v1 (月之暗面)
- **Ollama** - 本地模型支持

#### 💬 支持的通信平台

- **飞书** (Feishu/Lark)
- **企业微信** (WeCom)
- **钉钉** (DingTalk)
- **Telegram**
- **Discord**
- **Slack**

### 📥 安装指南

#### 前提条件

- Python 3.9 或更高版本
- pip 包管理器
- Git
- 至少一个 AI 模型提供商的 API Key

#### 快速安装

**macOS / Linux:**

```bash
# 克隆仓库
git clone https://gitee.com/x-claw/xclaw.git
cd xclaw

# 创建虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate

# 安装
pip install -e .

# 运行
xclaw
```

**Windows:**

```powershell
# 克隆仓库
git clone https://gitee.com/x-claw/xclaw.git
cd xclaw

# 创建虚拟环境（推荐）
python -m venv venv
venv\Scripts\activate

# 安装
pip install -e .

# 运行
xclaw
```

#### 开发模式安装

```bash
# 克隆仓库
git clone https://gitee.com/x-claw/xclaw.git
cd xclaw

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 代码格式化
black src tests

# 代码检查
ruff check src tests

# 类型检查
mypy src
```

### 🚀 快速开始

#### 1. 首次启动

首次运行 `xclaw` 会自动显示配置向导：

1. **欢迎页面** - 了解 xclaw 核心功能
2. **模型配置** - 选择 AI 提供商并输入 API Key
3. **通道配置** - 选择默认通信平台（可选）
4. **完成** - 点击"开始使用"进入主界面

#### 2. 获取 API Key

- **DeepSeek** (推荐): https://platform.deepseek.com/api_keys
- **OpenAI**: https://platform.openai.com/api-keys
- **智谱 AI**: https://open.bigmodel.cn/api-keys
- **Anthropic**: https://console.anthropic.com/

#### 3. 启动 OpenClaw

1. 进入主界面后，点击 **"启动"** 按钮
2. 等待服务启动（3-10 秒）
3. 状态显示"运行中"表示启动成功

#### 4. 验证安装

```bash
# 检查 OpenClaw 状态
openclaw gateway status

# 测试 API
curl http://127.0.0.1:18789/health
```

详细步骤请参考 [快速开始指南](docs/user-guide/QUICKSTART.md)

### 📚 文档

#### 用户文档

- [快速开始](docs/user-guide/QUICKSTART.md) - 5分钟上手指南
- [功能说明](docs/user-guide/FEATURES.md) - 详细功能介绍
- [常见问题](docs/FAQ.md) - FAQ 常见问题解答
- [用户手册](docs/user-guide.md) - 完整用户手册

#### 开发者文档

- [架构设计](docs/development/ARCHITECTURE.md) - 系统架构说明
- [贡献指南](docs/development/CONTRIBUTING.md) - 如何贡献代码
- [API 文档](docs/api/README.md) - 开发者 API
- [插件开发](docs/api/PLUGINS.md) - 插件开发指南

#### 其他文档

- [更新日志](CHANGELOG.md) - 完整版本历史
- [发布说明](RELEASE_NOTES.md) - 版本发布说明
- [路线图](docs/ROADMAP.md) - 未来规划

### 🎨 界面预览

> 📸 截图准备中，敬请期待！Screenshots coming soon!

<!-- #### 概览页面
![Dashboard](docs/images/dashboard.png)

#### 配置管理
![Configuration](docs/images/configuration.png)

#### 深色模式
![Dark Mode](docs/images/dark-mode.png) -->

### 🏗️ 项目结构

```
xclaw/
├── src/xclaw/           # Python 包
│   ├── core/            # 核心逻辑
│   │   ├── config.py    # 配置管理
│   │   ├── process.py   # 进程管理
│   │   └── deploy.py    # 部署管理
│   ├── gui/             # 图形界面
│   │   ├── pages/       # 页面组件
│   │   │   ├── dashboard.py
│   │   │   ├── configuration.py
│   │   │   ├── models.py
│   │   │   ├── channels.py
│   │   │   ├── logs.py
│   │   │   ├── costs.py
│   │   │   └── settings.py
│   │   └── widgets/     # UI 控件
│   ├── resources/       # 资源文件
│   │   ├── i18n/        # 国际化翻译
│   │   └── styles/      # QSS 样式主题
│   └── utils/           # 工具函数
├── docs/                # 文档
│   ├── user-guide/      # 用户指南
│   ├── development/     # 开发文档
│   └── api/             # API 文档
├── config/              # 配置示例
├── tests/               # 测试文件
├── scripts/             # 辅助脚本
├── CHANGELOG.md         # 更新日志
├── RELEASE_NOTES.md     # 发布说明
└── README.md            # 本文件
```

### 🛠️ 技术栈

- **Python 3.9+** - 编程语言
- **PySide6** - Qt6 图形界面框架
- **OpenClaw** - AI Agent 框架
- **PyYAML** - YAML 配置解析
- **jsonschema** - JSON Schema 验证
- **requests** - HTTP 客户端
- **psutil** - 系统监控
- **websockets** - WebSocket 客户端

### 🧪 开发

#### 运行测试

```bash
# 运行所有测试
pytest

# 运行测试并生成覆盖率报告
pytest --cov=src/xclaw --cov-report=html

# 运行特定测试文件
pytest tests/test_config.py -v
```

#### 代码质量

```bash
# 代码格式化
black src tests

# 代码检查
ruff check src tests

# 类型检查
mypy src
```

#### 构建打包

```bash
# 构建 Python 包
python -m build

# 打包桌面应用（需要 PyInstaller）
pyinstaller xclaw.spec
```

### 🤝 贡献

欢迎为 xclaw 做出贡献！

#### 如何贡献

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交变更 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 发起 Pull Request

详见 [贡献指南](docs/development/CONTRIBUTING.md)

#### 行为准则

- 尊重所有贡献者
- 欢迎不同观点和建议
- 专注于对社区最有利的事情
- 友善和建设性地交流

### 📝 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

### 🔗 链接

- **项目主页**: https://gitee.com/x-claw/xclaw
- **问题反馈**: https://gitee.com/x-claw/xclaw/issues
- **更新日志**: https://gitee.com/x-claw/xclaw/blob/main/CHANGELOG.md
- **发布页面**: https://gitee.com/x-claw/xclaw/releases
- **OpenClaw**: https://github.com/openclaw/openclaw

### 💬 社区与支持

#### 获取帮助

- 📖 [文档站](https://docs.xclaw.dev)
- ❓ [常见问题](docs/FAQ.md)
- 🐛 [问题反馈](https://gitee.com/x-claw/xclaw/issues)

#### 社区

- 💬 Discord: https://discord.gg/xclaw
- 🐦 Twitter: [@xclaw_dev](https://twitter.com/xclaw_dev)
- 📧 Email: support@xclaw.dev

### 🗺️ 路线图

#### v1.0.0 (当前版本) - 2025-03-17
- ✅ 完整的 GUI 管理界面
- ✅ 一键部署和配置向导
- ✅ 国际化支持（中英文）
- ✅ 深色模式
- ✅ 费用统计
- ✅ 记忆搜索

#### v1.1.0 (计划 2025 Q2)
- 🔌 插件市场集成
- 🌍 更多语言支持
- 📱 移动端适配
- ⚡ 性能优化

#### v1.2.0 (计划 2025 Q3)
- ☁️ 云端配置同步
- 🤝 协作功能
- 📊 高级数据分析

详见 [路线图](docs/ROADMAP.md)

---

## English

### ✨ Features

xclaw is the official GUI management tool for the OpenClaw AI Agent framework, providing a simple and intuitive visual interface for non-developer users.

#### 🎯 Core Highlights

- **🚀 One-Click Deployment** - Auto-detect system, install Node.js, configure OpenClaw
- **🎨 Visual Management** - Graphical configuration, no more manual JSON editing
- **📊 Real-time Monitoring** - Status monitoring, log viewing, cost statistics
- **🌐 Internationalization** - Full Chinese and English interface support
- **🌙 Dark Mode** - Eye-friendly dark theme with system auto-switch

#### 📱 Interface Modules

| Module | Features | Status |
|--------|----------|--------|
| Dashboard | OpenClaw status overview, quick actions | ✅ |
| Configuration | Form-based config, JSON editor | ✅ |
| Models | Multi-provider support, API Key management | ✅ |
| Channels | Feishu/WeChat/DingTalk/Telegram/Discord/Slack | ✅ |
| Logs | Real-time logs, filtering, export | ✅ |
| Costs | Token usage, cost statistics | ✅ |
| Memory | Memory search, edit, delete | ✅ |
| Settings | Theme, language, behavior config | ✅ |

### 📥 Installation

#### Prerequisites

- Python 3.9 or higher
- pip package manager
- Git
- At least one AI model provider's API Key

#### Quick Install

**macOS / Linux:**

```bash
# Clone repository
git clone https://gitee.com/x-claw/xclaw.git
cd xclaw

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install
pip install -e .

# Run
xclaw
```

**Windows:**

```powershell
# Clone repository
git clone https://gitee.com/x-claw/xclaw.git
cd xclaw

# Create virtual environment (recommended)
python -m venv venv
venv\Scripts\activate

# Install
pip install -e .

# Run
xclaw
```

### 🚀 Quick Start

#### 1. First Launch

First time running `xclaw` will automatically show the setup wizard:

1. **Welcome Page** - Learn about xclaw core features
2. **Model Config** - Select AI provider and enter API Key
3. **Channel Config** - Select default communication platform (optional)
4. **Complete** - Click "Start Using" to enter main interface

#### 2. Get API Key

- **DeepSeek** (Recommended): https://platform.deepseek.com/api_keys
- **OpenAI**: https://platform.openai.com/api-keys
- **Anthropic**: https://console.anthropic.com/

#### 3. Start OpenClaw

1. After entering main interface, click **"Start"** button
2. Wait for service to start (3-10 seconds)
3. Status shows "Running" indicates successful start

See [Quick Start Guide](docs/user-guide/QUICKSTART.md) for details

### 📚 Documentation

- [Quick Start](docs/user-guide/QUICKSTART.md) - 5-minute guide
- [Features](docs/user-guide/FEATURES.md) - Detailed feature introduction
- [FAQ](docs/FAQ.md) - Frequently asked questions
- [Architecture](docs/development/ARCHITECTURE.md) - System architecture
- [Contributing](docs/development/CONTRIBUTING.md) - How to contribute
- [Changelog](CHANGELOG.md) - Complete version history
- [Release Notes](RELEASE_NOTES.md) - Release announcements

### 🤝 Contributing

Contributions are welcome! Please see [Contributing Guide](docs/development/CONTRIBUTING.md)

### 📝 License

This project is licensed under the MIT License. See [LICENSE](LICENSE) file.

### 🔗 Links

- **Homepage**: https://gitee.com/x-claw/xclaw
- **Issues**: https://gitee.com/x-claw/xclaw/issues
- **Changelog**: https://gitee.com/x-claw/xclaw/blob/main/CHANGELOG.md
- **Releases**: https://gitee.com/x-claw/xclaw/releases
- **OpenClaw**: https://github.com/openclaw/openclaw

---

<div align="center">

**Made with ❤️ by xclaw Team**

**[⬆️ Back to Top](#xclaw)**

</div>