> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Octop 快速入门：几分钟内完成安装与运行

Octop 是一个自托管的多用户 AI 助手，完全运行在您自己的机器上。在本指南中，您将安装 `octop` CLI，运行 `octop init`，启动服务器，完成首次设置向导，并发送第一条消息——整个过程不到五分钟。


### 安装 Octop

选择适合您平台的安装方式。每种方法都会在 `~/.octop/venv` 处配置一个隔离环境，并通过 `~/.octop/bin` 将 `octop` 添加到您的 PATH 中——无需系统 Python。

```bash macOS / Linux
curl -fsSL https://download.octop.cloud/octop/scripts/install.sh | bash
```
```powershell Windows (PowerShell)
irm https://download.octop.cloud/octop/scripts/install.ps1 | iex
```
```bat Windows (cmd)
curl -fsSL https://download.octop.cloud/octop/scripts/install.bat -o install.bat
install.bat
```
```bash Docker（国内源）
docker run -d --name octop -p 8088:8088 -v octop-data:/data/.octop -e HOME=/data ghcr.nju.edu.cn/tencentcloud/octop:latest
```
```bash Docker（GitHub 源）
docker run -d --name octop -p 8088:8088 -v octop-data:/data/.octop -e HOME=/data ghcr.io/tencentcloud/octop:latest
```
```bash PyPI（已有 Python 环境）
pip install octop
```

`:latest` 是精简镜像，不含虚拟桌面、OCR 和本地向量。需要这些能力时，使用 `ghcr.io/tencentcloud/octop:full` 或 `:<version>-full`。国内镜像在 `ghcr.nju.edu.cn/tencentcloud/octop` 上使用同样的标签。

### 重新加载 shell

打开**新的终端**，或重新加载当前 shell 会话，以便 PATH 能够识别 `~/.octop/bin`：

```bash Zsh
source ~/.zshrc
```
```bash Bash
source ~/.bashrc
```


> **说明**
> 
> 在 Windows 上，安装程序会自动更新用户 PATH——关闭并重新打开终端以使更改生效。无需执行 shell 重载命令。
> 

确认安装成功：
```bash
octop --version
```

### 初始化 Octop

初始化本地环境：
```bash
octop init
```
这会准备好 `~/.octop/`（数据库、密钥等相关文件）。所有数据都保留在您机器的 `~/.octop/` 目录下。

### 启动服务器

在前台启动 Octop：
```bash
octop run
```
看到服务器就绪消息后，打开浏览器并访问：
```text
http://127.0.0.1:8088
```
首次启动时，页面会进入**设置向导**。请先到用户主目录打开 `~/octop-login.txt`，将其中的一次性设置密码粘贴到向导中，然后自行设置管理员用户名和密码。

> **说明**
> 
> 该文件位于用户主目录的 `~/octop-login.txt`，不在 `~/.octop/` 下。设置完成后 Octop **不再删除**该文件；请使用您自设的用户名和密码登录。忘记密码见[重置密码](/guide/guides/reset-password.md)。Docker 首次启动会把 `admin` 和生成（或 `OCTOP_DEFAULT_PASSWORD`）的密码写入 `/data/.octop/credential.txt`——见 [Docker 部署](/guide/quickstart-docker.md)。
> 

如需绑定所有网络接口或使用不同端口，直接传递参数即可：
```bash
octop run --host 0.0.0.0 --port 9000
```
如需将 Octop 作为持久后台服务运行（systemd、launchd 或 Windows Service），请使用：
```bash
octop service start
```

### 配置模型提供商

Octop 内置了腾讯云、OpenAI、Anthropic、DeepSeek、Ollama 等大量预设。在页面中添加您的第一个提供商：
```text
管理 → 模型
```

![模型管理](/images/ui-models.png "模型管理")

选择一个预置提供商，填入 API 密钥并启用。它的模型会进入可用模型池，供您账户下的所有专家使用。

> **提示**
> 
> 更习惯终端？使用 `octop models config`——详见 [专家命令](/cli/agent-commands.md#octop-models)。
> 

### 发出第一条消息

打开**对话**，地址为 `http://127.0.0.1:8088`。选中设置向导创建的默认专家 `main`，发送一条您真的想办的事，例如「帮我把下面这段会议记录整理成三条待办」。

![对话](/images/ui-chat.png "对话")

> **提示**
> 
> 终端交互式聊天见 [`octop chats`](/cli/agent-commands.md#octop-chats)。
> 

### 让它开始帮你干活

第一条消息能回来，就可以按您的日常往下配。每次只加一样：
- 要换一种专业角色或口气：打开[专家](/guide/concepts/agents.md)，从**发现专家**创建，再到 **MBTI** 里点**测一测**。
- 要让它依据您的文件回答：把文档放进[知识库](/guide/concepts/knowledge.md)，在输入框打开**知识库**并勾选。
- 要让它查会议、文档或邮箱：在[连接器](/guide/concepts/connectors.md)里**点击连接**并完成授权，然后直接说「查一下我明天的腾讯会议」。
- 要在飞书或微信里找到它：按[IM 通道](/guide/guides/im-channels.md)扫码绑定。


> **说明**
> 
> 基础安装程序会设置核心平台。如需解锁额外功能，请使用 `--extras` 参数重新运行安装程序：
> ```bash
> # 浏览器自动化（Playwright Chromium）
> curl -fsSL https://download.octop.cloud/octop/scripts/install.sh | bash -s -- --extras browser
> 
> # 飞书渠道支持
> curl -fsSL https://download.octop.cloud/octop/scripts/install.sh | bash -s -- --extras channels-feishu
> ```
> 浏览器自动化支持无头 Chromium 会话，用于网页任务和截图。飞书扩展添加了一个渠道桥接，让您的专家能够接收和回复飞书消息。
> 



> **提示**
> 
> 对于生产部署或多用户环境，请使用 Docker Compose 而非裸机安装。请参阅 [Docker 部署指南](/guide/quickstart-docker.md)。想直接买一台预装 Octop 的云主机，见 [在腾讯云中使用](/guide/use-in-tencent-cloud.md)。想在飞牛OS 上安装，见 [飞牛OS](/guide/fnos.md)。
> 



> **提示**
> 
> 更想使用原生桌面应用？从 [Octop v1.0.3b5 发布页](https://github.com/TencentCloud/Octop/releases/tag/v1.0.3b5)下载对应平台的安装包，例如 `Octop-desktop-darwin-arm64-1.0.3b5.dmg`。统信 UOS 和银河麒麟见[在国产系统内使用](/guide/domestic-os.md)。桌面客户端在 `~/.octop` 下使用便携运行时，并用 Electron 窗口打开页面。登录过期后，它会用 `~/.octop/desktop-device.json` 里的设备凭据续上会话。只在服务器或命令行里使用时，不必安装桌面端。桌面安装包只带浏览器自动化。虚拟桌面、OCR 和本地向量在 Docker 镜像标签 `:full` 上。
> 

