# AoClaw

**Repository Path**: mykin2026/aoclaw

## Basic Information

- **Project Name**: AoClaw
- **Description**: AoClaw 天工鳌: The Enterprise OS for OpenClaw Agents. (AoClaw：OpenClaw 智能体的企业级操作系统。)
- **Primary Language**: Go
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-06
- **Last Updated**: 2026-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AoClaw

## Windows Git 依赖补充

- AoClaw 在 `windows-native` 安装 OpenClaw 前，会先把 GitHub 的 SSH 依赖改写成 HTTPS。
- 对 `whiskeysockets/*` 依赖，AoClaw 会优先改写到 `https://gitee.com/OpenClaw-CN/`，避免服务器必须连 GitHub SSH。
- 如果你的环境还有自建 Git 代理/镜像，可追加 `--git-mirror-url https://your-mirror.example.com/github/`。
- Web 安装页也提供了可选的 `Git HTTPS 镜像` 输入框；留空时会使用 AoClaw 内置规则。

AoClaw 是面向 OpenClaw 的安装、配置、诊断与桌面化交付工具。

当前仓库同时维护两条产物路线：

- Go 便携版：内置前端静态资源，适合 Linux 直接运行、局域网共享、命令行部署
- Tauri 桌面版：把同一套前端和 Go sidecar 封装成原生桌面应用，双击直接进入窗口，不再依赖外部浏览器承载主界面

## 项目目标

AoClaw 重点解决的是 OpenClaw 的首装、首配、首跑与后续维护体验：

- 自动识别 Windows、Linux、macOS、WSL 场景
- 自动安装或修复 Node.js 24 与 OpenClaw
- 优先直接写入 OpenClaw 配置文件，再做核对，减少高频 CLI 轮询
- 优先配置 OpenAI 兼容 AI 接口，而不是把联网搜索 API 放在最前面
- 提供配置核对、Gateway 状态、Channels 探测、Doctor、安全审计与简单 Web Chat
- 已安装机器再次打开时直接进入配置 / 管理，而不是强制重新走安装流程

## 默认启动行为

`aoclaw` 无参数时会默认进入 `serve`：

- Linux：默认等价于 `serve --bind 0.0.0.0`
- Windows：默认等价于 `serve --open-browser`
- macOS：默认等价于 `serve --open-browser`

这意味着：

- Go Linux 版更适合作为局域网访问入口
- Go Windows / macOS 版更适合作为本机运维工具
- Tauri 版则用于真正的桌面应用交付

## 两条交付路线

### Go 便携版

特点：

- 已内置前端静态资源
- Linux 下可直接运行并对外提供 Web 页面
- Windows / macOS 下可命令行运行并自动打开浏览器
- 不依赖 WebView 运行时

构建：

```bash
node ./scripts/build-go-release.mjs
```

输出目录：

```text
dist/go/
  aoclaw-go-win-x64.exe
  aoclaw-go-linux-x64
  aoclaw-go-mac-arm64
```

### Tauri 桌面版

特点：

- 双击后直接进入原生窗口
- 内部仍复用同一套 Go sidecar 与前端
- 不再额外弹系统浏览器作为主界面
- 更适合交付给普通桌面用户

构建：

```bash
npm --prefix tauri install
npm --prefix tauri run build
```

输出目录：

```text
dist/tauri/
  aoclaw-tauri-win-x64.exe
  aoclaw-tauri-win-x64-setup.exe
  aoclaw-tauri-<platform>.dmg / .app / .AppImage
```

## Windows Node.js 安装兜底

AoClaw 现在默认使用系统级 Node.js 安装，不再写入便携 Node 路径。

在 Windows 上如果没有现成的系统 Node.js，AoClaw 会优先：

- 使用 `winget` 安装系统级 `OpenJS.NodeJS.LTS`
- 或使用 `choco install nodejs-lts -y`
- 如果都不可用，则回退到官方 Node.js MSI 静默安装

这样可以避免把 `LOCALAPPDATA\AoClaw\tools\nodejs\current` 写入用户 `PATH`，也能减少 `npm.ps1` 被 PowerShell 执行策略拦截的问题。

## Windows 原生依赖跳过策略

Windows 原生环境下，`openclaw@latest` 的依赖链有时会因为不同系统底层差异而失败，常见问题包括：

- `node-llama-cpp` 的 `postinstall` 崩溃
- 某些原生依赖在旧系统 / 精简系统 / 特定运行库环境中无法落盘
- 服务器能安装 `npm`，但装不上全部扩展能力

为此，AoClaw 现在提供两层兜底：

- 自动策略：`install` / `setup` 在 `windows-native` 下默认按以下顺序重试
  - 完整依赖
  - `--npm-omit peer`
  - `--npm-omit peer,optional`
- 手动策略：命令行可显式指定 `--npm-omit`

支持的 `--npm-omit` 值：

- `auto`：默认值，仅在 Windows 原生下自动降级重试
- `none`：禁用自动跳过，始终按完整依赖安装
- `peer`
- `optional`
- `dev`
- 组合写法：`peer,optional`

命令示例：

```bash
# 默认自动策略
./aoclaw-go-win-x64.exe install --mode windows-native --npm-registry https://registry.npmmirror.com

# 明确跳过 peer 依赖
./aoclaw-go-win-x64.exe install --mode windows-native --npm-registry https://registry.npmmirror.com --npm-omit peer

# 进一步收缩为 peer + optional
./aoclaw-go-win-x64.exe install --mode windows-native --npm-registry https://registry.npmmirror.com --npm-omit peer,optional

# 只装 Node，不装 OpenClaw
./aoclaw-go-win-x64.exe install --mode windows-native --skip-openclaw
```

如果你确认某台服务器必须完全手动执行，也建议优先显式调用 `npm.cmd`，而不是直接输入 `npm`：

```bat
"%ProgramFiles%\nodejs\npm.cmd" -v
"%ProgramFiles%\nodejs\npm.cmd" install -g openclaw@latest --prefix "%APPDATA%\npm" --registry "https://registry.npmmirror.com"
"%APPDATA%\npm\openclaw.cmd" --version
```

如果在 PowerShell 中只想临时放行当前会话，也可以先执行：

```powershell
Set-ExecutionPolicy -Scope Process Bypass
```
## Tauri 分发注意事项

现在支持两种桌面分发方式：

- `dist/tauri/aoclaw-tauri-win-x64.exe`：单文件版，首次启动自动释放 sidecar
- `dist/tauri/aoclaw-tauri-win-x64-setup.exe`：Windows 安装包

两种方式都仍然依赖 Windows WebView2 Runtime。普通用户也可以继续使用安装包 `setup.exe` 或 `.msi`。

## 当前 UI 方向

当前控制台已调整为更接近桌面软件的工作台布局：

- 顶部主导航：安装 / 配置 / 管理
- 配置页使用子 tab，减少长页面滚动
- `AI 接口` 与 `工作目录与访问` 横向并列
- `能力与安全预设` 单独分组，避免内容高低不齐导致的大留白
- `AI 聊天测试` 改为浮层，不挤占主工作区
- 表单状态、识别结果与最近聊天会缓存恢复

## 快速验证

```bash
go test ./...
npm --prefix web run build
npm --prefix tauri run build
```

## 文档索引

- 构建与目录约定：`BUILD.md`
- Tauri 专项说明：`tauri/README.md`
- 桌面交付说明：`docs/desktop-packaging.zh-CN.md`
- OpenClaw 工作流梳理：`docs/openclaw-workflows.zh-CN.md`
- 产品方向记录：`docs/product-shape.zh-CN.md`

## Unix Node.js / OpenClaw fallback

Linux / macOS / WSL 也带有系统级安装兜底逻辑：

- Linux 优先复用 `apt/dnf/yum/pacman` 安装或升级 Node.js 24
- macOS 默认使用官方 Node.js `.pkg` 安装器
- 如果 Linux 上没有可用包管理器，AoClaw 会回退到 `/usr/local` 下的系统级 Node.js 安装
- `openclaw` 本身仍然默认安装到 AoClaw 管理的 npm 前缀中，避免污染系统全局包