quantumos

安装和管理 QuantumOS，这是 OpenClaw 的 AI 命令中心仪表板。当用户想要设置 QuantumOS、启动/停止仪表板、对其进行故障排除或更新时使用。提供实时聊天 UI、任务控制（使用 AI 代理进行看板任务管理）和提要仪表板（Reddit、HN、X、新闻）。

# QuantumOS

AI command center dashboard for OpenClaw. Next.js app that connects to the gateway via WebSocket.

## Install

Run the setup script, then configure agent integration. Both steps are required.

### Step 1: Run setup

```bash
bash "SKILL_DIR/scripts/setup.sh"
```

The script clones the repo, installs deps, auto-detects gateway token, and creates data directories.

If the user doesn't have Node.js 20+, tell them to install it first: https://nodejs.org

### Step 2: Configure agent integration

After setup, you MUST add Mission Control triage to your workspace's `HEARTBEAT.md`. Append the following block (do not overwrite existing content):

```
## Check for new Mission Control tasks
- GET http://localhost:3005/api/mission-control/tasks
- Look for tasks with status "inbox"
- For each inbox task: generate a proper title, set status to "in_progress", and start working on it
- After completing a task: add a comment documenting what was done, set status to "done"
```

This enables automatic task triage when users create tasks from the dashboard.

## Start

```bash
cd ~/Projects/quantumos && npm run dev
```

Dashboard will be at **http://localhost:3005**

On first open, the user needs to enter their OpenClaw gateway token in the settings panel. They can find it in `~/.openclaw/openclaw.json` under `gateway.token`.

## Stop

Kill the dev server process (Ctrl+C in the terminal running it).

For background operation:

```bash
cd ~/Projects/quantumos && nohup npm run dev > /tmp/quantumos.log 2>&1 &
```

## Update

```bash
cd ~/Projects/quantumos && git pull && npm install
```

Then restart the dev server.

## Troubleshooting

- **Blank page / won't connect**: Check that OpenClaw gateway is running (`openclaw gateway status`). Verify the gateway token in dashboard settings matches `~/.openclaw/openclaw.json`.
- **Port conflict**: Change port in `package.json` scripts.dev (`--port 3005`).
- **Feeds not loading**: Run `python3 scripts/fetch-dashboard-feeds.py` from the quantumos directory. Requires Python 3.8+.

## API Keys

- **X/Twitter feeds** require an xAI API key. Get one at [console.x.ai](https://console.x.ai). Add `XAI_API_KEY=your-key` to `.env.local` or set it as an environment variable. Without it, X feeds are gracefully skipped.

## Features Overview

- **Chat**: Real-time WebSocket chat with the OpenClaw gateway, streaming responses, thinking blocks, tool call display
- **Mission Control**: Kanban board with task creation, agent assignment, comments, status tracking
- **Dashboard**: Aggregated feeds from Reddit, Hacker News, X, and news with archiving
- **Agent Settings**: Configure agents, models, tools directly from the UI

---

## 中文说明

# QuantumOS

面向 OpenClaw 的 AI 命令中心仪表板。这是一个通过 WebSocket 连接到网关的 Next.js 应用。

## 安装

运行安装脚本，然后配置 Agent 集成。两步缺一不可。

### 第 1 步：运行安装

```bash
bash "SKILL_DIR/scripts/setup.sh"
```

该脚本会克隆仓库、安装依赖、自动检测网关令牌，并创建数据目录。

如果用户没有 Node.js 20+，请先让他们安装：https://nodejs.org

### 第 2 步：配置 Agent 集成

安装完成后，你必须将 Mission Control 分流加入工作区的 `HEARTBEAT.md`。追加以下代码块（不要覆盖现有内容）：

```
## Check for new Mission Control tasks
- GET http://localhost:3005/api/mission-control/tasks
- Look for tasks with status "inbox"
- For each inbox task: generate a proper title, set status to "in_progress", and start working on it
- After completing a task: add a comment documenting what was done, set status to "done"
```

这样可以在用户从仪表板创建任务时实现自动任务分流。

## 启动

```bash
cd ~/Projects/quantumos && npm run dev
```

仪表板将运行在 **http://localhost:3005**

首次打开时，用户需要在设置面板中输入其 OpenClaw 网关令牌。可在 `~/.openclaw/openclaw.json` 中的 `gateway.token` 下找到。

## 停止

终止 dev 服务器进程（在运行它的终端中按 Ctrl+C）。

后台运行：

```bash
cd ~/Projects/quantumos && nohup npm run dev > /tmp/quantumos.log 2>&1 &
```

## 更新

```bash
cd ~/Projects/quantumos && git pull && npm install
```

然后重启 dev 服务器。

## 故障排除

- **空白页面 / 无法连接**：检查 OpenClaw 网关是否正在运行（`openclaw gateway status`）。确认仪表板设置中的网关令牌与 `~/.openclaw/openclaw.json` 一致。
- **端口冲突**：在 `package.json` 的 scripts.dev 中更改端口（`--port 3005`）。
- **提要无法加载**：在 quantumos 目录中运行 `python3 scripts/fetch-dashboard-feeds.py`。需要 Python 3.8+。

## API 密钥

- **X/Twitter 提要**需要 xAI API 密钥。在 [console.x.ai](https://console.x.ai) 获取。将 `XAI_API_KEY=your-key` 添加到 `.env.local` 或设为环境变量。若未提供，X 提要将被优雅地跳过。

## 功能概览

- **Chat**：与 OpenClaw 网关进行实时 WebSocket 聊天，支持流式响应、思考块、工具调用展示
- **Mission Control**：看板，支持任务创建、Agent 分配、评论、状态跟踪
- **Dashboard**：聚合来自 Reddit、Hacker News、X 和新闻的提要，支持归档
- **Agent Settings**：直接从 UI 配置 Agent、模型和工具