import { TagSelector } from '../../features/docs/TagSelector'

export const meta = {
  title: '安装',
  description: 'Linux/Mac 下一键安装路径。',
  section: '快速开始',
  order: 30,
  slug: 'install',
}

# 安装

## 一键安装

> 一键安装脚本预期能在网络正常的情况下自动处理所有场景，如果遇到问题请联系 [Github Issues](https://github.com/coooolfan/onlyboxes/issues) 寻求帮助。

安装脚本支持在 Linux/Mac 机器上快速安装或者体验，请提前**确保系统的 Docker 或者 KVM 环境可用**。

```bash
curl -fsSL https://onlybox.es/install.sh | bash
```

### 安装器实现

1. 检查 Linux/Mac、Docker、Docker Compose v2 与 systemd。
2. 下载 compose 模板并渲染初始凭据。
3. 通过 `docker compose up -d` 启动控制节点。
4. 创建一个 `normal` worker。
5. 根据可用运行时（Docker 或 boxlite）下载与当前架构匹配的 worker release 二进制。
6. 生成并启用 systemd 服务。
7. 轮询直到 worker 上线。

### 支持的参数

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `--tag` | `0.6.1` | 可选的 Release 版本覆盖参数，仅建议在高级场景下使用 |
| `--workdir` | `$PWD/onlyboxes` | 工作目录 |
| `--yes` / `-y` | `false` | 非交互模式 |
| `--console-http-port` | `8089` | 宿主机上的 Console HTTP 端口 |
| `--console-grpc-port` | `50051` | 宿主机上的 Console gRPC 端口 |
| `--console-start` | `auto` | 控制台启动模式 |
| `--worker-runtime` | `auto` | Worker 运行时选择（`docker` / `boxlite` / `auto`） |
| `--worker-start` | `auto` | Worker 启动模式 |

### 常用示例

通过 `bash -s --` 把参数透传给安装脚本。

安装指定版本（下拉框中的 tag 实时来自 GitHub）：

<TagSelector locale="zh-CN" />

非交互安装到自定义目录：

```bash
curl -fsSL https://onlybox.es/install.sh | bash -s -- \
  --yes \
  --workdir /opt/onlyboxes
```

自定义控制台端口：

```bash
curl -fsSL https://onlybox.es/install.sh | bash -s -- \
  --console-http-port 18089 \
  --console-grpc-port 50052
```

强制使用 boxlite 运行时（无 Docker 的环境）：

```bash
curl -fsSL https://onlybox.es/install.sh | bash -s -- --worker-runtime boxlite
```

### 运行要求

- Linux/Mac
- Python 3（安装脚本本身由 Python 编写）

## 下一步

- [快速开始](/zh-CN/docs/quick-start) — 从控制节点到 Claude Code 的完整上手流程
- [控制台配置](/zh-CN/docs/console-config) — 控制节点的所有环境变量

## 手动安装

OnlyBoxes 当然允许您手动部署和控制所有组件和节点，但是对于非专业人士，这会略显复杂。尤其是不同 worker 实现需要的额外要求。

我们不希望向您提供一份未经人工审核的 LLM 生成的低质量文档，因此我们还需要一部分时间撰写相关内容。

在本节完成之前，我们建议您直接阅读[安装脚本的实现](https://github.com/coooolfan/onlyboxes/blob/main/scripts/install.py)，并在 LLM Agent 能访问[代码仓库](https://github.com/coooolfan/onlyboxes)的情况下协助您完成手动安装。
