十分钟装好自托管 AI 助手：如何从零跑通 Octop 并完成第一次对话
【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/Octop
跟着本文走一遍，大约十分钟后你的电脑上就会有一个可以对话、可以接飞书、可以按点推送的自托管 AI 助手。Octop 把它全部装在本地：聊天记录、工作区、密钥都留在你自己的机器上，而不是某个云端服务里。
从一个真实痛点说起 🫠
你有没有这种经历：白天用着 SaaS 版聊天工具，想让 AI 帮你盯着日报、在群里回消息，结果发现数据在别人服务器上，而且每个功能都得单独找入口。Octop 的思路是把「Web 控制台、命令行、IM 通道、定时任务」这四件事合并到一个进程里跑，装一次，全家都能用。
Octop 速览：它是什么，数据在哪里
先说结论：它是一个面向家庭和小团队的自托管 AI 助手，单进程启动，默认用 SQLite 当控制面数据库，不需要你额外装任何中间件。
- 📦一个进程管全部— 控制台、
octop命令行、飞书/钉钉/QQ/企业微信通道、Cron 定时任务共享同一个控制面库（octop.db），重启后状态自动重建 - 🔒数据不出门— 配置、对话、Agent 工作区、JWT 密钥全部落在
~/.octop/下，想离线就接本地 Ollama - 👥多人共用一套— 一个管理员账号即可管理，给每位成员分配独立的 Agent 与工作区
- 🎭人格化 Agent— 内置 16 种 MBTI 人格模板和专家库，不用从零写提示词
- 🐍零 Python 前置— 安装脚本自动创建隔离的 Python 3.12 环境，不碰系统环境
环境准备与一条命令安装 ⚙️
跑通下面的命令后，octop就能在你的终端里用了。前置条件只有两条：macOS / Linux / Windows 之一，以及能访问外网（下载安装包与依赖）。
macOS / Linux 直接执行：
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bashWindows 在 PowerShell 里执行irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iex即可，效果和上面等价。脚本会在~/.octop/venv建隔离环境，并把octop包装脚本放进~/.octop/bin加入 PATH。
验证方式：打开一个新终端（或先执行source ~/.zshrc/source ~/.bashrc），然后输入octop --version，能打印版本号就成功了。如果你本来就要用浏览器自动化，安装时追加--extras browser会顺带下载 Playwright Chromium；已有 Python 环境的也可以直接pip install octop。全部安装选项在 scripts/README.md 里有完整列表。
首次启动最短路径：从 octop run 到第一次对话 🚀
执行完下面这条命令，浏览器打开http://127.0.0.1:8088就能看到初始化引导页：
octop run首次访问会自动跳到/setup引导流程，顺序是：
- 输入临时口令— 启动终端里打印的那串一次性密码，用来给初始化上锁
- 选控制面数据库— 保持默认 SQLite 直接「保存并继续」，进阶用户可填 PostgreSQL
- 建管理员账号— 密码规则是至少 8 位且同时含字母和数字，这个账号后面全靠它登录
- 配模型— 选一个预设供应商（OpenAI、DeepSeek、Ollama 等）填 Key 并点「测试连接」；想先跑通流程可以跳过，之后随时在「设置 → 模型」里补
向导走完会自动以管理员身份登录控制台，此时就能直接开始聊天了。如果希望它开机常驻，把octop run换成octop service start（Linux 走 systemd、macOS 走 launchd、Windows 注册为系统服务）。
核心能力拆解：专家库、IM 通道与定时任务 💬
下面三个功能是大多数人上手后最先用到的，各配一个实际场景。
用专家库创建专属 Agent
场景：你想让 AI 写周报，又不想用一个"啥都聊"的通用机器人。进入「Agent → 专家」页，从内置专家库里挑一个模板（比如办公自动化），点一下就能建出一个带独立工作区、独立供应商配置的 Agent。也可以走 MBTI 人格测试给它定个性格。日常对话支持多轮追问、附件上传和斜杠命令。
让助手住进飞书或钉钉
场景：你希望在钉钉群里直接 @机器人 查数据、发日报。进「通道」页安装对应平台（飞书需要 App ID + App Secret，钉钉需要 App Key + App Secret，企业微信需要 Corp ID + Agent Secret），填完凭证即可。IM 消息和 Web 控制台走的是同一条消息处理链路，所以通道里能用的能力，网页上同样能用。
用自然语言配定时推送
场景：每天早上九点把昨日监控数据整理成日报发到群里。进「定时任务」页新建 Cron，用自然语言描述触发时间和动作，保存后 Agent 就会按时执行——不需要你手写 cron 表达式。
部署与进阶：容器、服务与桌面客户端 🐳
上面是本地开发式的玩法；要放到服务器或 NAS 上，Docker 方式的数据边界更清晰。执行docker compose -f docker/docker-compose.yml up -d构建并启动后，访问http://localhost:8088。首次启动时如果设置了合格的OCTOP_DEFAULT_PASSWORD（≥8 位、含字母和数字），会自动创建管理员并把凭据写到容器内/data/.octop/credential.txt；没设置则进设置向导，向导口令在/data/.octop/octop-login.txt，可用docker exec <容器名> cat /data/.octop/octop-login.txt查看。细节见 docker/README.md。
不想碰终端的话，官方还有 Windows / macOS / Linux 三平台的桌面客户端，以及飞牛 NAS（FnOS）安装包，与 Web 控制台可并行使用，说明在 desktop/README.md。升级统一走octop update，~/.octop/下的数据库、工作区和config.json都会保留。
排坑清单：新手最容易卡住的四个点 🧯
command not found: octop— 安装只写入了当前 shell 的 PATH。开新终端，或执行source ~/.bashrc/source ~/.zshrc再试；仍不行就检查~/.octop/bin是否真的在 PATH 里http://127.0.0.1:8088打不开— 回到octop run的终端看有没有报错；如果你改过端口，要访问新端口；用系统服务方式跑的，可以用octop service status看状态- 模型「测试连接」失败— 依次核对 API Key、Base URL、网络能否到该服务、账户余额/配额；自建网关记得走「自定义」供应商类型
- 跨版本升级前— 先执行
octop backup再octop update，数据目录结构虽然保留，但备份一次永远不亏
收尾：接下来去哪儿深入 📚
Octop 的最小闭环就三步——一条命令装、一个向导初始化、一次对话开聊。跑通之后，建议按这条线继续：
| 想做的事 | 去哪儿看 |
|---|---|
| 完整使用流程（安装 → 向导 → 模型 → 日常） | docs/user-guide.md |
| 所有 CLI 子命令 | docs/cli.md |
环境变量与config.json配置项 | docs/configuration.md |
| 单进程架构是怎么设计的 | docs/architecture.md |
安装脚本全部参数（--version、--mirror等） | scripts/README.md |
【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/Octop
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
