# 安装和启动 BitSeek Claw

本指南介绍如何安装和启动 BitSeek Claw（Hermes WebUI）。

## 系统要求

- **操作系统**：macOS、Linux 或 WSL2（Windows 需通过 WSL2）
- **Python**：3.8 或更高版本
- **Hermes Agent**：需要预先安装 Hermes Agent

## 安装步骤

### 1. 克隆仓库

```bash
git clone https://github.com/your-repo/agent-frontend-shell.git
cd agent-frontend-shell
```

### 2. 环境配置

#### 方法一：使用 `.env` 文件（推荐）

```bash
# 复制示例环境文件
cp .env.example .env

# 编辑 .env 文件配置必要参数
nano .env
```

#### 方法二：直接设置环境变量

```bash
export HERMES_WEBUI_HOST=127.0.0.1
export HERMES_WEBUI_PORT=8787
export HERMES_HOME=~/.hermes
```

### 3. 启动服务

#### 方法一：使用启动脚本（推荐）

```bash
# 使用 start.sh 启动
./start.sh
```

#### 方法二：使用 Python 启动器

```bash
# 使用 bootstrap.py 启动（会自动检查依赖）
python3 bootstrap.py
```

#### 方法三：使用控制脚本

```bash
# 使用 ctl.sh 管理服务
./ctl.sh start
```

## 启动参数

### 环境变量配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `HERMES_WEBUI_HOST` | `127.0.0.1` | 监听地址 |
| `HERMES_WEBUI_PORT` | `8787` | 监听端口 |
| `HERMES_HOME` | `~/.hermes` | Hermes 主目录 |
| `HERMES_WEBUI_STATE_DIR` | - | 状态目录路径 |
| `HERMES_WEBUI_DEFAULT_WORKSPACE` | - | 默认工作区路径 |

### 启动选项

```bash
# 指定端口启动
HERMES_WEBUI_PORT=8888 ./start.sh

# 指定主机和端口
HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PORT=8787 ./start.sh

# 使用自定义状态目录
HERMES_WEBUI_STATE_DIR=/tmp/hermes-state ./start.sh
```

## 访问界面

启动成功后，在浏览器中访问：

```
http://localhost:8787
```

### 首次访问

1. 打开浏览器访问上述地址
2. 首次访问会进入**首次运行向导**
3. 按照向导提示配置：
   - AI 提供商设置（如 OpenAI、Anthropic 等）
   - API 密钥配置
   - 基本偏好设置

## Docker 部署

### 单容器部署

```bash
# 使用 Docker Compose
docker-compose up -d

# 或使用自定义配置
docker-compose -f docker-compose.custom.yml up -d
```

### 多容器部署

```bash
# 三容器架构
docker-compose -f docker-compose.three-container.yml up -d

# 两容器架构
docker-compose -f docker-compose.two-container.yml up -d
```

## 常见问题

### 端口被占用

```bash
# 检查端口占用
lsof -i :8787

# 使用其他端口
HERMES_WEBUI_PORT=8788 ./start.sh
```

### 权限问题

```bash
# 确保脚本有执行权限
chmod +x start.sh
chmod +x ctl.sh
chmod +x bootstrap.py
```

### 依赖缺失

```bash
# 安装 Python 依赖
pip install -r requirements.txt

# 或使用虚拟环境
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

## 停止服务

```bash
# 使用控制脚本停止
./ctl.sh stop

# 或查找进程并终止
pkill -f "python.*server.py"
```

## 下一步

安装启动完成后，请查看：
- **[整体概览](01-整体概览.md)** - 了解界面布局
- **[页面操作](02-页面操作.md)** - 学习具体操作
