English | 简体中文
多引擎 AI 助手桌面客户端，基于 ACP (Agent Client Protocol) 协议，支持任何兼容 ACP 的 Agent 引擎，提供跨平台的本地 AI Agent 执行能力。
NuwaClaw 采用 ACP (Agent Client Protocol) 协议与 Agent 引擎通信，支持任何实现了 ACP 协议的 Agent：
| 引擎 | 说明 |
|---|---|
| Claude Code | Anthropic 官方 CLI Agent，推荐使用 ⭐ |
| Codex CLI | OpenAI 的代码 Agent |
| Gemini CLI | Google 的 AI Agent |
| GitHub Copilot | GitHub 的 AI 编程助手 |
| Cline | 开源自主编程 Agent |
| Cursor | Cursor IDE 的 Agent 能力 |
| Goose | Block 开源的 AI Agent |
| Qwen Code | 阿里通义千问代码 Agent |
| Junie | JetBrains 的 AI Agent |
| OpenCode | 开源代码 Agent |
| Nuwaxcode | 基于 OpenCode 修改的 Agent 引擎 |
| 更多... | 查看完整列表 |
ACP 协议: Agent Client Protocol，标准化编辑器/IDE 与 AI Agent 之间的通信协议，基于 NDJSON 格式。类似 LSP 之于语言服务，ACP 让你可以将任何 ACP 兼容的 Agent 接入到任何支持的客户端。
- 引擎隔离运行，独立环境配置
- 动态切换引擎，无需重启应用
- 避免厂商锁定，自由选择 Agent
- Electron 客户端 - 基于 Electron + React 的桌面客户端
- 动态 MCP 服务器管理
- 多协议支持 (stdio, SSE, Streamable HTTP)
- 弹性连接与自动重连
- 持久化存储 - SQLite 本地存储
- 系统托盘 - 后台运行，快速操作
nuwax-agent-client/
├── crates/
│ ├── agent-electron-client/ # Electron 客户端 (主要开发)
│ ├── nuwax-mcp-stdio-proxy/ # MCP 协议聚合代理
│ ├── agent-gpui-client/ # GPUI 客户端 (实验性)
│ ├── agent-server-admin/ # 管理端 API 服务
│ ├── agent-protocol/ # 通信协议定义
│ ├── system-permissions/ # 系统权限管理
│ └── nuwax-agent-core/ # 核心逻辑 (Rust)
└── vendors/ # 第三方依赖
# 方式一：使用 Makefile（推荐，项目根目录执行）
make electron-dev # 开发模式
make electron-build # 构建
make electron-dist # 打包
# 方式二：进入目录执行 npm 命令
cd crates/agent-electron-client
# 安装依赖
npm install
# 开发模式
npm run dev
# 构建
npm run build
# 打包
npm run dist:mac # macOS
npm run dist:win # Windows
npm run dist:linux # Linuxcd crates/nuwax-mcp-stdio-proxy
# 安装依赖
npm install
# 构建
npm run build
# 运行 (stdio 聚合模式)
nuwax-mcp-stdio-proxy --config '{"mcpServers":{...}}'
# 运行 (协议转换模式)
nuwax-mcp-stdio-proxy convert http://remote-mcp-server/sse
# 运行 (持久化桥接模式)
nuwax-mcp-stdio-proxy proxy --port 18099 --config '{"mcpServers":{...}}'| 平台 | 架构 | 状态 |
|---|---|---|
| macOS | arm64, x86_64 | ✅ |
| Windows | x86_64, arm64 | ✅ |
| Linux | x86_64, arm64 | ✅ |
- 主进程: Electron + TypeScript
- 渲染进程: React 18 + Ant Design
- 存储: SQLite (better-sqlite3)
- 构建: Vite + electron-builder
| 服务 | 说明 |
|---|---|
| Unified Agent | 统一的 ACP 引擎管理 |
| Engine Manager | 引擎生命周期管理 |
| MCP | MCP 服务器管理 |
| Dependencies | 依赖包管理 |
| Permissions | 权限控制 |
~/.nuwaclaw/
├── engines/ # Agent 引擎
├── workspaces/ # 会话工作空间
├── node_modules/ # 本地 npm 包
│ ├── .bin/ # 可执行文件
│ └── mcp-servers/ # MCP 服务器
├── bin/ # 应用二进制
├── logs/ # 日志文件
│ ├── main.log # 主进程日志
│ └── mcp-proxy.log # MCP 代理日志
└── nuwaclaw.db # SQLite 数据库
| 分类 | 通道 |
|---|---|
| Session | session:list, session:create, session:delete |
| Message | message:list, message:add |
| Settings | settings:get, settings:set |
| Agent | agent:init, agent:destroy, agent:prompt |
| MCP | mcp:install, mcp:uninstall, mcp:start, mcp:stop |
nuwax-mcp-stdio-proxy 是一个 MCP 协议聚合代理，解决多 MCP 服务器集成时的生命周期管理问题。
| 模式 | 用途 | 命令 |
|---|---|---|
| stdio | 聚合多个 MCP 服务器为单个 stdio 接口 | nuwax-mcp-stdio-proxy --config '...' |
| convert | 将远程 MCP 服务转换为本地 stdio | nuwax-mcp-stdio-proxy convert <url> |
| proxy | 持久化桥接，预先启动并暴露 HTTP 接口 | nuwax-mcp-stdio-proxy proxy --port 18099 |
- 就绪状态检测: 阻塞等待 MCP 服务器就绪
- 弹性传输: 心跳检测、指数退避重连、请求队列
- 集中清理: 优雅终止所有子进程
| 参数 | 默认值 | 说明 |
|---|---|---|
pingIntervalMs |
20000 | 心跳间隔 |
maxConsecutiveFailures |
3 | 连续失败阈值 |
maxReconnectDelayMs |
60000 | 重连延迟上限 |
maxQueueSize |
100 | 请求队列容量 |
首次运行时通过设置向导配置：
- 输入 Anthropic API Key
- 选择默认模型
- 配置 MCP 服务器
敏感配置存储在 SQLite 数据库中，不在代码中硬编码。
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
},
"github": {
"url": "https://api.github.com/mcp"
}
}
}crates/agent-electron-client/
├── src/
│ ├── main/ # 主进程
│ │ ├── main.ts # 入口
│ │ ├── preload.ts # 预加载脚本
│ │ ├── ipc/ # IPC 处理器
│ │ └── services/ # 主进程服务
│ ├── renderer/ # 渲染进程
│ │ ├── main.tsx # React 入口
│ │ ├── App.tsx # 主组件
│ │ ├── components/ # React 组件
│ │ └── services/ # 渲染进程服务
│ └── shared/ # 共享代码
├── resources/ # 打包资源
├── scripts/ # 构建脚本
└── package.json
# Electron 客户端
cd crates/agent-electron-client
npm run test
# MCP 代理
cd crates/nuwax-mcp-stdio-proxy
npm run test:run
npm run test:coverage# 启用详细日志
RUST_LOG=debug npm run dev| 工作流 | 触发条件 | 说明 |
|---|---|---|
ci-electron.yml |
crates/agent-electron-client/** 变更 |
Electron 测试构建 |
release-electron.yml |
推送 electron-v* tag |
Electron 发布构建 |
# Electron 发布
git tag electron-v0.9.0
git push origin electron-v0.9.0欢迎提交 Issue 和 Pull Request！
- Fork 本仓库
- 创建功能分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add amazing feature') - 推送分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
- Electron - 跨平台桌面应用框架
- MCP - Model Context Protocol
- Ant Design - React UI 组件库