Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 33 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[中文版](README.zh-CN.md)

**MicroClaw** makes [OpenClaw](https://github.com/openclaw) instantly available on Windows through a familiar, low-friction install experience. It packages the desktop client, local Gateway, managed runtime, preloaded skills, and permission-controlled sandbox into one product so users can get to real tasks quickly. You bring the LLM connection; MicroClaw brings the Windows app, local runtime, and trust boundary.
**MicroClaw** makes [OpenClaw](https://github.com/openclaw) instantly available on Windows through a familiar, low-friction install experience. This branch contains an experimental Microsoft MXC sandbox POC.

> [!WARNING]
> **AI & Security Notice**
Expand All @@ -19,7 +19,7 @@ MicroClaw is designed to remove the usual Windows setup friction around OpenClaw
### Instant Availability

- **Familiar Windows install flow**: packaged installer with desktop shortcut, Start menu entry, and one-click uninstall
- **One run sets up the runtime**: Git, managed Node.js, OpenClaw Gateway, the MicroClaw desktop app, managed skills, and AppContainer provisioning
- **One run sets up the runtime**: Git, managed Node.js, OpenClaw Gateway, the MicroClaw desktop app, managed skills, and the pinned MXC package
- **Ready after install**: launch the app immediately after setup instead of building a local OpenClaw environment by hand

### Ready-to-Use Experience
Expand All @@ -31,9 +31,9 @@ MicroClaw is designed to remove the usual Windows setup friction around OpenClaw

### Built-In Trust

- **Transparent, permission-controlled actions**: file and tool access requests are surfaced to the user instead of being silently granted
- **Sandboxed with Windows AppContainer**: tool execution runs inside an OS-enforced AppContainer boundary on supported systems
- **Hooks plus sandbox, defense in depth**: hook-based prechecks improve UX while AppContainer ACL enforcement remains the actual security boundary
- **Native folder policy**: approved read-only/read-write folders are selected through the desktop's native picker
- **Microsoft MXC experiment**: dedicated Node workers run through `@microsoft/mxc-sdk@0.7.0`
- **Fail closed**: OpenClaw host file/runtime, elevated, browser, canvas, and native code-execution tools are denied; MXC tools have no host fallback
- **Hard blocks for sensitive paths**: credential-heavy locations such as `.ssh` and cloud config folders are denied rather than merely warned about

---
Expand Down Expand Up @@ -88,7 +88,7 @@ graph TB
| Gateway → LLM | HTTPS | Streaming API calls to Claude / OpenAI / Gemini |
| Gateway → Skills | In-process | Agent loop invokes tool calls; results fed back to LLM |
| WeChat Plugin → WeChat | HTTPS | Long-poll `getUpdates` + `sendMessage` |
| Permission ManagerAppContainer | Win32 API | AppContainer security capabilities + Job Object resource limits |
| MXC pluginMXC worker | Native process containment | Hash-verified `wxc-exec` launches a secret-stripped Node worker |

---

Expand All @@ -97,7 +97,7 @@ graph TB
| Component | Path | Stack | Description |
|---|---|---|---|
| **Desktop App** | `desktop/` | Electron 33 + TypeScript + Vue 3 + Element Plus | Chat UI, Gateway lifecycle management, system tray |
| **AppContainer Sandbox** | `appcontainer/` | .NET 9 + Node.js preload hooks | Windows AppContainer launcher + permission hooks for tool isolation |
| **MXC tool plugin** | `desktop/mxc-plugin/` | OpenClaw Plugin SDK + MXC 0.7.0 | Registers non-conflicting `mxc_*` tools and launches the contained worker |
| **Installer** | `deploy.py` + `deployer/` | Python 3 + Tkinter | Wizard-style graphical installer (can be packaged as a single exe) |
| **Skill Packs** | `skills/` | Markdown + JSON + Python/Node | Office, search, browser automation managed skills |
| **WeChat Plugin** | `plugins/openclaw-weixin/` | TypeScript + OpenClaw Plugin SDK | WeChat channel integration |
Expand Down Expand Up @@ -127,7 +127,7 @@ The installer handles the Windows-side setup in a single run:
- Node.js 22+ via the official signed `.msi` (per-machine install to `%ProgramFiles%\nodejs\`, UAC-elevated; an existing system Node ≥22.16 at that path is reused as-is)
- OpenClaw Gateway (`npm install -g openclaw`)
- Configures the npm registry mirror and V8 compile cache
- Installs the MicroClaw desktop client, managed skills, AppContainer sandbox, WeChat plugin
- Installs the MicroClaw desktop client, managed skills, pinned MXC runtime, and WeChat plugin
- Adds Windows Defender exclusions, creates desktop shortcuts (including one-click Uninstall)

After install, launch **MicroClaw** from the Start menu or the desktop shortcut. The desktop app auto-starts the Gateway.
Expand Down Expand Up @@ -196,13 +196,29 @@ npm run lint:sarif # outputs eslint-results.sarif

## Sandbox Isolation

`appcontainer/` provides a Windows AppContainer-based sandbox for isolating tool execution:
This branch pins [`@microsoft/mxc-sdk@0.7.0`](https://github.com/microsoft/mxc/tree/v0.7.0)
(tag commit `34d7fe2b4b3226bd4d11dc4a32419b7ec198a88b`) and stable policy
`0.7.0-alpha`. The packaged OpenClaw plugin exposes `mxc_read`, `mxc_write`,
`mxc_edit`, and bounded `mxc_exec`. Each call launches a dedicated Node worker
inside MXC with network/UI denied and a secret-stripped environment; descendants
remain in the same containment. Chat is blocked unless package version, official
`wxc-exec` hash, OS tier, policy, and worker proof all succeed.

- **.NET launcher** (`AppContainerLauncher.exe`) runs child processes inside an AppContainer with restricted ACLs
- **Node.js preload hooks** (`sandbox-preload.js`, `sandbox-fs-hooks.js`, …) intercept `fs.*` / `child_process.*` calls and prompt the user for permission
- **Sensitive-path shield** hard-denies access to `~/.ssh`, `~/.azure`, and other credential directories — no override
POC scope is intentionally narrow: file operations are UTF-8 and capped at 1 MiB,
`mxc_edit` replaces one unique string, and `mxc_exec` is non-interactive with a
30-second/1 MiB output limit. There is no background/process-control tool,
`apply_patch`, unrestricted host fallback, or automatic host preparation.

See [appcontainer/README.md](appcontainer/README.md) for details.
> [!WARNING]
> MXC is a **public preview**. Policies may be overly permissive and no current
> profile is a production security boundary. This POC sets
> `fallback.allowDaclMutation=false`. If Settings reports that host preparation is
> required, Microsoft documents elevated `wxc-host-prep prepare-system-drive`
> (machine-wide metadata ACEs) and `wxc-host-prep prepare-null-device`. MSIX cannot
> chain those steps. MicroClaw never invokes them, elevates, or mutates ACLs
> automatically. This POC cannot attest preparation or collect consent for
> temporary folder-DACL mutation, so it remains blocked on `appcontainer-dacl`;
> legacy AppContainer ACLs are left unchanged.

---

Expand Down Expand Up @@ -255,7 +271,7 @@ Installed to `~/.openclaw/skills/`, these are custom advanced skills included in
| **Skill Integrity Checks** | SHA-256 hashes + Ed25519 signatures — detects tampering of all skill files at startup |
| **Device Authentication** | Each device generates an Ed25519 key pair; Gateway connections are signature-authenticated |
| **Skill Allowlist** | `allowBundled` / `allowManaged` control the available skill scope |
| **Sandbox Isolation** | OS-native AppContainer + Job Object isolation for file system, network, and resource limits |
| **Sandbox Isolation** | Experimental MXC 0.7.0 worker with hash verification, network/UI denial, strict folder policy, and no host fallback |
| **Local Gateway** | Binds to loopback only — does not accept remote connections |

---
Expand All @@ -278,7 +294,7 @@ This script sequentially:

The CI and release workflows also build `desktop/release/MicroClawDesktop-<version>-x64.msix`
with Electron Builder. The package includes the Electron app, the pinned OpenClaw
runtime, Node.js, and the AppContainer launcher resources. On first launch, the
runtime, Node.js, and MXC SDK/native resources. On first launch, the
read-only bundled runtime archive is expanded under Electron's per-user
`userData` directory; configuration and other writable state remain in per-user
application data.
Expand Down Expand Up @@ -310,7 +326,6 @@ download-update path.

- Node.js 22+
- Python 3.10+ — install build deps with `pip install -r requirements.txt` (includes PyInstaller)
- .NET 9 SDK (for the AppContainer launcher)
- npm dependencies installed (`cd desktop && npm install`)

---
Expand All @@ -330,7 +345,8 @@ Operational Windows scripts now live under `scripts/windows/`. Root `.bat` and `
├── desktop/ # Electron desktop app
│ ├── src/ # Main process (TypeScript)
│ └── renderer/ # Vue 3 renderer process
├── appcontainer/ # Windows AppContainer sandbox (.NET + preload hooks)
├── appcontainer/ # Legacy inactive AppContainer sources (not packaged)
├── desktop/mxc-plugin/ # Experimental MXC-backed OpenClaw tools
├── skills/ # Managed skill definitions
├── plugins/openclaw-weixin/ # WeChat channel plugin
├── scripts/
Expand Down
32 changes: 22 additions & 10 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[English](README.md)

**MicroClaw** 的目标是让 [OpenClaw](https://github.com/openclaw) 在 Windows 上做到“装好就能用”。它把桌面客户端、本地 Gateway、运行时、预装技能和带权限控制的沙箱整合成一个熟悉、低摩擦的安装体验,让用户尽快进入真实任务。你只需要提供大模型连接信息,Windows 侧运行环境、桌面应用和信任边界都由 MicroClaw 预置完成
**MicroClaw** 的目标是让 [OpenClaw](https://github.com/openclaw) 在 Windows 上做到“装好就能用”。此分支包含 Microsoft MXC 实验性沙箱 POC

> [!WARNING]
> **AI 与安全声明**
Expand All @@ -19,7 +19,7 @@ MicroClaw 的设计重点,是把 OpenClaw 在 Windows 上常见的安装和配
### 即装即用

- **熟悉的 Windows 安装流程**:带桌面快捷方式、开始菜单入口和一键卸载
- **一次安装补齐运行环境**:自动准备 Git、受管 Node.js、OpenClaw Gateway、MicroClaw 桌面端、托管技能和 AppContainer 配置
- **一次安装补齐运行环境**:自动准备 Git、受管 Node.js、OpenClaw Gateway、MicroClaw 桌面端、托管技能和固定版本 MXC 包
- **安装完成即可启动**:不需要先手动搭本地 OpenClaw 运行环境

### 真正可用,而不是只装了个壳
Expand All @@ -31,19 +31,31 @@ MicroClaw 的设计重点,是把 OpenClaw 在 Windows 上常见的安装和配

### 内建信任

- **动作透明、权限可控**:文件和工具访问需要明确向用户申请,而不是静默放行
- **基于 Windows AppContainer 的沙箱隔离**:在支持的系统上,工具执行运行在操作系统强制边界内
- **Hook 加沙箱,形成纵深防御**:Hook 负责更好的交互体验,真正的安全边界仍由 AppContainer ACL 强制执行
- **原生文件夹策略**:通过桌面端原生选择器配置只读/读写文件夹
- **Microsoft MXC 实验**:专用 Node 工作进程通过 `@microsoft/mxc-sdk@0.7.0` 启动
- **故障关闭**:禁用 OpenClaw 主机文件/运行时、提权、浏览器、画布和原生代码执行工具;MXC 工具没有主机回退
- **敏感路径直接硬拦截**:例如 `.ssh`、云凭据目录等不会只是提醒,而是直接拒绝访问

> [!WARNING]
> 本分支固定 [`@microsoft/mxc-sdk@0.7.0`](https://github.com/microsoft/mxc/tree/v0.7.0)
>(提交 `34d7fe2b4b3226bd4d11dc4a32419b7ec198a88b`)和稳定策略
> `0.7.0-alpha`。MXC 仍是**公共预览**:策略可能过度宽松,当前没有任何配置可作为生产安全边界。
> POC 设置 `fallback.allowDaclMutation=false`。Microsoft 文档要求管理员明确同意运行
> `wxc-host-prep prepare-system-drive`(机器级元数据 ACE)及 `prepare-null-device`,MSIX 无法串联这些步骤。
> MicroClaw 不会自动运行、提权或修改 ACL;本 POC 也无法验证准备状态或收集临时文件夹 DACL 修改同意,
> 因此在 `appcontainer-dacl` 层级仍保持阻止,且不会静默清理旧 AppContainer ACL。
>
> POC 范围有意收窄:文件工具仅支持 UTF-8 且上限 1 MiB,`mxc_edit` 只替换一个唯一字符串,
> `mxc_exec` 为非交互式(最多 30 秒、输出 1 MiB)。不提供后台进程控制、`apply_patch`、无限制主机回退或自动主机准备。

---

## 项目组成

| 组件 | 路径 | 技术栈 | 说明 |
|---|---|---|---|
| **桌面应用** | `desktop/` | Electron 33 + TypeScript + Vue 3 + Element Plus | 聊天界面、Gateway 生命周期管理、托盘菜单 |
| **AppContainer 沙盒** | `appcontainer/` | .NET 9 + Node.js preload hooks | Windows AppContainer 启动器 + 权限钩子,隔离工具执行 |
| **MXC 工具插件** | `desktop/mxc-plugin/` | OpenClaw Plugin SDK + MXC 0.7.0 | 注册 `mxc_*` 工具并启动受隔离工作进程 |
| **安装器** | `deploy.py` + `deployer/` | Python 3 + Tkinter | 向导式图形化安装器(可打包为单文件 exe) |
| **技能包** | `skills/` | Markdown + JSON + Python/Node | Office、搜索、浏览器自动化等托管技能 |
| **微信插件** | `plugins/openclaw-weixin/` | TypeScript + OpenClaw Plugin SDK | 微信频道接入 |
Expand Down Expand Up @@ -73,7 +85,7 @@ MicroClaw 仅支持 **Windows 10/11**。对大多数用户来说,真正需要
- Node.js 22+,通过官方签名 `.msi` 以 per-machine 方式安装到 `%ProgramFiles%\nodejs\`(UAC 提权;若该路径已存在 ≥22.16 的系统 Node 则直接复用)
- OpenClaw Gateway(`npm install -g openclaw`)
- 配置 npm 镜像源与 V8 编译缓存
- 安装 MicroClaw 桌面客户端、托管技能、AppContainer 沙箱、微信插件
- 安装 MicroClaw 桌面客户端、托管技能、固定版本 MXC 运行时和微信插件
- 添加 Windows Defender 排除项,创建桌面快捷方式(含一键卸载)

安装完成后,从开始菜单或桌面快捷方式启动 **MicroClaw**。桌面应用会自动拉起 Gateway。
Expand Down Expand Up @@ -170,7 +182,7 @@ npm run dev
| **技能完整性校验** | SHA-256 哈希 + Ed25519 签名,启动时检测所有技能文件是否被篡改 |
| **设备认证** | 每台设备生成 Ed25519 密钥对,Gateway 连接时签名认证 |
| **技能白名单** | `allowBundled` / `allowManaged` 控制可用技能范围 |
| **沙盒隔离** | Windows AppContainer 沙盒,限制 AI 工具执行环境 |
| **沙盒隔离** | 实验性 MXC 0.7.0 工作进程;校验哈希、禁用网络/UI、严格文件夹策略且无主机回退 |
| **本地 Gateway** | 仅绑定 loopback,不接受远程连接 |

---
Expand All @@ -193,7 +205,6 @@ npm run dev

- Node.js 22+
- Python 3.10+ —— 通过 `pip install -r requirements.txt` 安装构建依赖(已包含 PyInstaller)
- .NET 9 SDK(用于构建 AppContainer 启动器)
- npm 依赖已安装(`cd desktop && npm install`)

---
Expand All @@ -213,7 +224,8 @@ Windows 侧运维脚本现在统一放在 `scripts/windows/` 下。仓库根目
├── desktop/ # Electron 桌面应用
│ ├── src/ # 主进程(TypeScript)
│ └── renderer/ # Vue 3 渲染进程
├── appcontainer/ # Windows AppContainer 沙盒(.NET + preload hooks)
├── appcontainer/ # 旧版未激活 AppContainer 源码(不再打包)
├── desktop/mxc-plugin/ # 实验性 MXC OpenClaw 工具
├── skills/ # 托管技能定义
├── plugins/openclaw-weixin/ # 微信频道插件
├── scripts/
Expand Down
Loading
Loading