# claude-claw

**Repository Path**: codingdb/claude-claw

## Basic Information

- **Project Name**: claude-claw
- **Description**: claude windows 客户端
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude Claw

> 🐾 基于 Electron 的 Claude Code 图形化客户端 —— 多工作区、多 Agent 并行编排，集成对话、知识库、Git、任务、插件、工具箱于一体的桌面端 AI 编程助手。

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
![Electron](https://img.shields.io/badge/Electron-33-47848F)
![Claude Code SDK](https://img.shields.io/badge/Claude%20Code%20SDK-0.3-D97757)

---

## ✨ 项目简介

Claude Claw 把命令行里的 Claude Code 包装成一个可视化的多 Agent 工作台。你可以在一个窗口里同时跑多个项目的 Agent、检索沉淀的知识、管理 Git、对接任务平台、调用开发者工具，并通过飞书机器人远程驱动。所有数据本地存储，零云端依赖。

### 核心特性一览

| 模块 | 能力 |
|------|------|
| 🤖 多 Agent 编排 | 多工作区并行、外部 Agent 自动发现、PM Agent 任务分发 |
| 💬 AI 对话 | 流式回复、文件附件、语音输入、模型切换、上下文用量监控 |
| 📚 知识库 | 代码扫描入库、文件导入、向量 + 关键词检索、自动记忆、Karpathy 知识库 |
| 🌿 Git 管理 | 变更 Diff、分支、Worktree、提交日志 |
| ✅ 任务管理 | TAPD / Jira / Linear / 手动任务，看板视图，一键发给 Agent |
| 🔌 插件系统 | MCP / 命令 / 插件包，内置市场 |
| 🛠️ 开发者工具箱 | 9 个内置常用工具 |
| ✈️ 飞书 Bot | 远程私聊驱动 Agent |
| 🎨 主题 | 6 款内置皮肤 |

---

## 📦 安装

### 方式一：下载安装包（推荐普通用户）

前往 [Releases](../../releases) 下载对应平台的安装包（`.exe` / `.dmg` / `.AppImage`），双击安装即可。

### 方式二：从源码构建

> 前置要求：Node.js ≥ 18、npm、Git

```bash
git clone <仓库地址>
cd claude-claw
npm install          # 安装依赖（含 electron 依赖）
npm run dev          # 本地开发模式启动
npm run build        # 构建产物
npm run dist         # 打包成可分发安装包
```

常用脚本：

| 命令 | 说明 |
|------|------|
| `npm run dev` | 以开发模式启动（热重载） |
| `npm run build` | 编译主进程 + 渲染进程 |
| `npm run dist` | 打包发布安装包 |
| `npm run pack` | 仅打包不解包（用于测试） |
| `npm test` | 运行单元测试（Vitest） |
| `npm run test:e2e` | 运行端到端测试（Playwright） |
| `npm run test:all` | 单元 + 端到端全量测试 |

---

## 🚀 快速开始

1. **启动** Claude Claw。
2. 点击左侧栏顶部 **「添加」**，选择你的项目目录作为一个工作区。
3. 在 **设置** 中配置好 Claude API Key（首次使用必填）。
4. 点击工作区，系统自动启动该工作区的 Claude Agent。
5. 在底部输入框提问，按 `Enter` 发送，Agent 流式回复。

---

## 🧩 功能详解

### 1. 工作区管理

- **添加工作区**：侧边栏顶部「添加」→ 目录选择器 → 选项目文件夹。
- **切换工作区**：点击工作区名称，自动切换并启动对应 Agent。
- **删除工作区**：悬停工作区 → 🗑 删除图标。

每个工作区对应一个独立的 Agent 与会话空间，互不干扰。

### 2. 多 Agent 并行编排

Claude Claw 是一个**多 Agent 工作台**：

- **多工作区并行**：每个工作区跑一个 Agent，可同时执行多个任务。
- **外部 Agent 发现**：自动扫描本机 `~/.claude/sessions` 中由命令行或其他方式启动的 Claude Code 进程，纳入面板统一查看状态。
- **PM Agent**：内置产品经理角色 Agent，可对任务进行拆解与分发。
- **Agent 卡片**：每个 Agent 一张卡片，实时显示状态、队列、上下文用量。
- **自动化**：可配置线程级自动化规则，让 Agent 按规则自动响应。

### 3. AI 对话

| 功能 | 说明 |
|------|------|
| **流式回复** | 实时逐字输出 |
| **文件附件** | 📎 支持图片（JPG/PNG/GIF/WebP）、PDF、文档 |
| **语音输入** | 🎤 支持 OpenAI Whisper 与**豆包（字节）语音识别**两种 STT，需在设置配置 |
| **模型切换** | 聊天顶部切换模型，模型列表在设置中维护 |
| **消息操作** | 删除单条 / 清空对话（可撤销）/ 压缩对话（省 token） |
| **上下文用量** | 顶部进度条：🟢 <50% / 🟡 50–80% / 🔴 >80%，附带 token 数与费用 |

- `Enter` 发送，`Shift + Enter` 换行，`Esc` 停止录音。

### 4. 会话管理

- **历史会话**：展开工作区查看历史会话列表（首条消息 + 时间 + 消息数）。
- **搜索**：会话超过 5 个时自动出现搜索框，按消息内容/备注实时过滤。
- **恢复 / 新建**：点击恢复旧会话，或「+ 新对话」开新会话。
- **置顶 / 备注 / 删除**：悬停会话显示对应操作图标。

### 5. 知识库（Knowledge Base）

详见 [`知识库使用说明.md`](./知识库使用说明.md)。要点：

- **代码扫描**：递归扫描工作区源码，按目录生成「模块摘要」入库，支持增量同步。
- **文件导入**：导入 `.md/.txt/.json/.yaml/.yml/.toml`。
- **手动笔记**：自由添加带标签的知识条目。
- **双通道检索**：关键词兜底 + 向量语义（向量库后端可选 `sql.js` 本地 或 `MemPalace`）。
- **自动记忆**：对话中自动提取可复用事实（偏好 / 上下文 / 解决方案 / 事实）。
- **Karpathy 知识库**：内置 Karpathy 的 YouTube / GitHub / 博客内容索引。
- **知识包迁移**：一键导出/导入 `.clawkb.json`。
- **统计**：总条目数、已索引数、来源分布、总分块数。

> 向量库可选 **MemPalace**（自带 Embedding，需 Python 运行时，应用内一键安装）或 **sql.js**（纯本地，需另配 Embedding API）。

### 6. Git 管理

需要先选中一个 Git 工作区。

- **变更（Changes）**：文件变更列表 + 代码 Diff，三种模式（未暂存 / 已暂存 / 分支对比）。
  - 🟢 A 新增 / 🟢 M 修改 / 🔴 D 删除 / 🔵 R 重命名 / ⚪ U 未跟踪
- **分支（Branches）**：本地 + 远程分支，切换 / 创建 / 拉取 / 获取。
- **Worktree**：查看、创建、删除 Git Worktree。
- **日志（Log）**：最近 100 条提交，点击查看 Diff。

### 7. 任务管理（Tasks）

对接主流任务平台，把需求/缺陷直接发给 Agent 执行：

| 平台 | 接入方式 |
|------|----------|
| **TAPD** | API Token；或**企业微信扫码登录**（浏览器鉴权） |
| **Jira** | API Token |
| **Linear** | API Key |
| **手动** | 本地手动录入任务 |

- **看板视图（Kanban）**：可视化任务流转。
- **发送给 Agent**：选中任务一键发给当前工作区 Agent。

### 8. 技能商店（Skills）

技能 = 预定义的专家提示词，安装后让 Claude 扮演特定角色（代码审查、测试、安全、运维等）。

- **分类筛选 + 关键词搜索**（名称/描述/标签）。
- **中英文切换**。
- **详情 / 体验（发给当前 Agent）/ 安装（持久化）**。
- 内置技能示例：`code-review`（代码审查）、`security-review`（安全审查）等。

### 9. 插件管理

| 类型 | 说明 |
|------|------|
| **MCP** | 模型上下文协议服务器，扩展 Claude 的工具能力 |
| **命令** | 可复用的命令型扩展 |
| **插件** | 完整功能插件包 |

- **已安装**：查看 / 配置 / 卸载。
- **市场**：浏览、搜索、安装社区插件。

### 10. 开发者工具箱（Toolbox）

内置 9 个常用工具，按类别分组：

| 工具 | 类别 | 功能 |
|------|------|------|
| JSON 格式化 | 编码 | 美化 / 压缩 |
| 时间戳转换 | 编码 | 时间戳 ↔ 日期互转 |
| Base64 编解码 | 编码 | 文本 ↔ Base64 |
| URL 编解码 | 编码 | 编码 / 解码 / URL 解析 |
| Hash 生成 | 安全 | SHA-1/256/384/512 |
| 颜色转换 | 设计 | HEX ↔ RGB ↔ HSL |
| 正则测试 | 开发 | 正则匹配验证 |
| 字数统计 | 文本 | 字符 / 单词 / 行 / 中英文 |
| 短网址/编码 | 工具 | 编码辅助 |

### 11. 用量统计

- **概览卡片**：今日 / 本周 / 本月 / 总计 的 token 与费用。
- **趋势图**：按天（30天）/ 按周（12周）/ 按月（12月），Input（蓝）+ Output（粉）柱状图。
- **明细表**：每日 Input / Output / Total / Cost。
- 数据每次对话后自动落盘，重启不丢失。

### 12. 内置浏览器与终端

- **浏览器面板**：内嵌 webview，可在应用内浏览网页、查阅文档，地址栏导航、外链自动转交系统浏览器。
- **终端**：内嵌 PTY 终端，直接在工作区执行命令行操作。

### 13. 飞书 Bot（远程驱动）

在飞书私聊机器人即可远程驱动 Agent：

| 指令 | 说明 |
|------|------|
| 直接发消息 | 发送任务给当前工作区 Agent |
| `workspace` | 选择 / 切换工作区 |
| `session` | 查看和恢复历史会话 |
| `status` | 查询当前 Agent 状态 |
| `clear` | 清除所有会话 |

Agent 回复实时流式更新，支持发送图片。配置方式见 [`使用说明.md`](./使用说明.md) 的飞书章节（需在飞书开放平台创建应用并开通相应权限）。

### 14. 通知设置

- **主开关**：任务完成时通知。
- **渠道（多选）**：📱 桌面通知 / 📋 应用内 Toast / ✈️ 飞书推送。
- **智能抑制**：正在查看某 Agent 时，该 Agent 的通知自动抑制；Agent 需要操作时（如权限请求）闪烁任务栏提醒。

### 15. 主题切换

侧边栏标题右侧 🎨 调色板，6 款内置皮肤，选择即时生效、重启保持：

| 主题 | 风格 | 强调色 |
|------|------|--------|
| 极光紫 | 深色 | 💜 紫色 |
| 赛博蓝 | 深色 | 💙 蓝色 |
| 抹茶绿 | 深色 | 💚 绿色 |
| 日落橙 | 深色 | 🧡 橙色 |
| 樱花粉 | 深色 | 💗 粉色 |
| 素纸白 | 浅色 | 💜 靛蓝 |

### 16. 键盘快捷键

| 快捷键 | 功能 |
|--------|------|
| `Enter` | 发送消息 |
| `Shift + Enter` | 换行 |
| `Esc` | 停止语音录音 |

---

## 🏗️ 软件架构

```
claude-claw/
├── src/
│   ├── main/                    # Electron 主进程
│   │   ├── index.ts             # 入口
│   │   ├── ipc.ts               # IPC 处理器（渲染↔主进程桥梁）
│   │   ├── sdk-agent-manager.ts # Claude Code SDK Agent 管理
│   │   ├── claude-manager.ts    # Claude 进程管理
│   │   ├── codex-manager.ts     # Codex Agent 管理
│   │   ├── agent-orchestrator.ts# 多 Agent 编排
│   │   ├── external-agent-scanner.ts  # 外部 Agent 发现
│   │   ├── automation-service.ts# 自动化规则
│   │   ├── knowledge/           # 知识库子系统
│   │   │   ├── knowledge-service.ts   # CRUD + 检索
│   │   │   ├── adapters/        # sql.js / MemPalace 向量库适配器
│   │   │   ├── auto-memory/     # 自动记忆
│   │   │   ├── karpathy/        # Karpathy 知识库
│   │   │   ├── code-scanner.ts  # 代码扫描入库
│   │   │   └── ...
│   │   ├── task-providers/      # TAPD / Jira / Linear 任务平台
│   │   ├── feishu/              # 飞书 Bot
│   │   ├── git-utils.ts         # Git 操作
│   │   ├── browser-manager.ts   # 内置浏览器
│   │   ├── voice-stt.ts         # 语音识别（Whisper / 豆包）
│   │   ├── plugin-registry.ts   # 插件注册
│   │   ├── skill-registry.ts    # 技能注册
│   │   └── store.ts             # 本地配置存储
│   ├── preload/                 # 预加载脚本（IPC 桥接）
│   └── renderer/                # 渲染进程（React + Ant Design）
│       └── src/components/      # UI 组件
├── tests/                       # 单元测试 + E2E 测试
├── resources/                   # 打包资源
└── electron-builder.yml         # 打包配置
```

**技术栈**：Electron 33 · React 18 · TypeScript · Ant Design 5 · Zustand · sql.js · @anthropic-ai/claude-agent-sdk · Vitest · Playwright。

---

## 📁 数据存储

所有用户数据保存在本地应用数据目录（Windows 下通常为 `%APPDATA%\claude-claw\`），包括：

- 配置（API Key、模型、主题、各模块设置）
- 知识库（`knowledge.db` + MemPalace 数据）
- 会话与用量统计
- 运行时调试日志

复制该目录即可完整备份 / 迁移。

---

## 📚 相关文档

- [`使用说明.md`](./使用说明.md) —— 各模块交互细节（工作区、对话、会话、技能、插件、Git、统计、飞书等）
- [`知识库使用说明.md`](./知识库使用说明.md) —— 知识库配置、导入、检索、自动记忆、Karpathy 详解

---

## ❓ 常见问题

**Q：Agent 启动失败？**
确保 API Key 已正确配置，网络连接正常。

**Q：飞书 Bot 无法连接？**
1. 检查 App ID / App Secret；2. 确认飞书应用已启用「机器人」能力并发布；3. 确认已开通消息权限。

**Q：Git 面板显示「不是 Git 仓库」？**
确保工作区目录含 `.git`，或用 `git init` 初始化。

**Q：知识库检索不到结果？**
确认已为该工作区启用知识库；sql.js 模式需配置 Embedding API。详见知识库文档的「常见问题」。

**Q：如何减少 token 消耗？**
及时开新对话而非在旧会话里续聊；用「压缩对话」；控制单次输入长度。

---

## 🤝 参与贡献

1. Fork 本仓库
2. 新建 `Feat_xxx` 分支
3. 提交代码
4. 新建 Pull Request

---

## 📄 开源协议

[MIT License](./LICENSE)

---

*Claude Claw — 让 AI 编程更高效。* 🚀