elizaOS 保姆级部署教程：从源码启动你的开源智能体操作系统

elizaOS（仓库 elizaOS/eliza，MIT 协议，GitHub 星数约 1.97 万，最近提交 2026-10-30）是一个开源的 TypeScript 智能体操作系统：一个 monorepo 同时包含核心运行时、Eliza 桌面/移动/Web 应用、CLI、云服务、原生桥接和官方插件。它最初因为加密圈"AI 分身"而走红，现在已经演化成一个完整的 agentic OS——聊天、语音、记忆、知识库、浏览器自动化、日历、邮件，甚至 EVM/Solana 钱包，都通过插件接进同一个智能体。

本文严格对照官方 README 给出从源码部署的完整流程。

一、项目介绍与适用场景

elizaOS 官方定位："Your agentic operating system"。它把智能体拆成几层：

@elizaos/core：定义 AgentRuntime、类型、鉴权、记忆、插件契约；
@elizaos/agent：独立 agent + HTTP 后端；
@elizaos/app：应用层托管；
@elizaos/ui：共享 React UI；
plugins/：模型、连接器、领域、设备插件。

适用场景：

个人 AI 分身：在本地跑一个有记忆、有性格、能跨 Telegram/Discord/Slack 说话的智能体；
团队助手：日历、待办、邮件、浏览器自动化整合到一个 agent；
开发者：基于 core 自己写插件，接自有业务系统；
设备级部署：packages/os 提供可启动的 Linux / AOSP 发行版，把一整台小机器变成 elizaOS。

二、核心功能逐条拆解

聊天、语音、记忆、知识、文档工作流：内置能力，不靠插件。
消息与工作台连接器：接 Discord/Telegram/Slack 等。
个人助理域：日历、提醒、收件箱、目标、健康。
浏览器与桌面自动化：通过插件驱动本机浏览器/桌面。
原生设备桥：相机、电话、短信、通讯录、定位（移动端）。
非托管钱包：EVM/Solana 钱包操作带审批边界。
定时工作流与编码 agent 编排：内置。
本地推理（Eliza-1）：插件 @elizaos/plugin-local-inference 提供 2B/4B/9B/27B 本地模型，基于 Gemma 4，离线可用。
模型无关：可路由到本地、直连 Provider、Eliza Cloud。
插件体系：一个 Plugin 对象注册 actions / providers / evaluators / services / model handlers / routes / events / app views。

三、全套官方链接

类型	链接
GitHub 仓库	https://github.com/elizaOS/eliza
官方文档	https://docs.elizaos.ai/
官方 Demo	https://cloud.eliza.app
License	MIT（README 末尾明确）

四、硬件与环境前置要求

官方 README 明确：仓库在 package.json 里 pin 死了 Bun 与 Node 版本，请按仓库里指定的版本安装。

其他：

内存 8 GB 起步（本地推理模型另算）；
磁盘 20 GB（monorepo + 模型资产）；
网络：首次 clone 要拉 submodule，装依赖；
可选 GPU：本地 9B/27B 模型需要对应显存，否则自动路由到云端。

五、多平台部署步骤

5.1 从源码运行（官方 Quickstart）

官方 README 原文：

git clone --filter=blob:none https://github.com/elizaos/eliza.git
cd eliza
bun install
bun run dev

逐条解释：

git clone --filter=blob:none：浅克隆，不拉历史二进制，省时间；
cd eliza：进入仓库根；
bun install：官方强调这一步会同时准备 submodule 与补丁、装宿主机构建依赖、构建/校验 libelizainference；embedding GGUF 是运行时托管的，首次本地推理预热时自动下载；
bun run dev：启动完整开发栈（app + API）。

预期：终端打印启动日志，浏览器打开本地端口即可进入 Eliza UI。

5.2 常用仓库命令（官方原文）

bun run dev:local   # app + API with the runtime chooser（本地 agent + 自有 provider key，无需 Cloud 登录）
bun run start       # 独立 agent host（仅 API，无 UI）
bun run build       # 用 Turbo 构建整个 workspace
bun run verify      # 依赖、类型、lint、audit 四道闸
bun run test        # 仓库端到端测试
bun run test:e2e    # E2E 测试
bun run cloud:mock  # 本地带 mock 的 Eliza Cloud 栈

单包命令用 bun run --cwd <package> <script> 指定工作目录。

5.3 跑 Benchmark（官方）

官方要求 Python 3.11+，从仓库根：

PYTHONPATH=packages python3 -m benchmarks.orchestrator list-benchmarks
PYTHONPATH=packages python3 -m benchmarks.orchestrator run --benchmarks <id> --provider <provider> --model <model>

活跑 benchmark 需要对应 provider 的凭证，会产生模型费用。

5.4 桌面发行版（官方下载）

官方 README 给出三个入口：

打开 Web 应用 https://cloud.eliza.app ；
访问 https://eliza.app/downloads ；
用 GitHub Release 里的安装包。

不想要源码，直接下 Release 即可。

5.5 Docker 部署

官方 README 当前版本未提供官方 Docker 一键部署命令，本文不展开 Docker；如需容器化，按 packages/ 下各包 README 自行打包。

六、配置文件全部参数解释

参数名	作用	可选值	默认值	配置示例	改错后果
模型 provider key	在 `bun run dev:local` 的 runtime chooser 里填	OpenAI/Anthropic/Gemma 等	无	见 5.2	不填则只能走 Cloud
本地推理开关	是否用 Eliza-1 on-device	开关	自动硬件检测	在 UI 里切换	硬件不支持时强制开会失败
`--cwd <package>`	指定单包工作目录	包路径	仓库根	`bun run --cwd packages/core test`	改错包则命令跑错地方

更细的插件配置见各包 README 与 docs.elizaos.ai，本文不臆造。

七、启动、后台常驻与开机自启

7.1 前台启动

cd eliza
bun run dev

7.2 后台常驻（systemd，仅 API host）

[Unit]
Description=Eliza Agent Host
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/eliza
ExecStart=/home/ubuntu/.bun/bin/bun run start
Restart=on-failure

[Install]
WantedBy=multi-user.target

7.3 开机自启

sudo systemctl daemon-reload && sudo systemctl enable --now eliza

7.4 修改端口

官方 README 未在根文档给出固定端口；端口由 packages/app 与各 host 配置决定，改完后 bun run start 起 API，用 curl http://127.0.0.1:<端口> 验证。

八、功能实操教程

第 1 步：装 Bun，按 5.1 克隆仓库并 bun install。第 2 步：bun run dev:local 启动带 runtime chooser 的开发栈。第 3 步：在 UI 里选本地 agent 或填你自己的 OpenAI/Anthropic key。第 4 步：新建一个智能体，给它起名字、写性格（bio）。第 5 步：在聊天窗里跟它对话，观察它有记忆、能跨会话记住上下文。第 6 步：从 plugins/ 里挑一个官方插件（如消息连接器）装上，让它去 Discord 说话。第 7 步（可选）：启用本地推理插件，切到 2B/4B 模型，断网测试。

九、全套报错故障排查

报错：bun install 卡在 libelizainference。原因：宿主机缺构建依赖。解决：官方说 bun install 会自动装宿主机依赖；若失败按报错提示补 build-essential / Xcode CLI。
报错：bun: command not found。原因：没装 Bun 或版本不对。解决：按 https://bun.sh 装官方版本；仓库 pin 的版本以 package.json 为准。
报错：本地推理启动失败。原因：硬件不支持 27B/9B 模型。解决：切到更小的 2B/4B，或直接路由到云端 provider。
报错：插件装了不生效。原因：没在 agent 配置里启用插件。解决：读 plugins/<name>/README.md，按它的配置注册。
报错：bun run dev 端口被占。原因：本机 3000/5173 之类已被占。解决：关掉占用进程，或在 apps 配置里改端口。

十、升级、回滚与卸载

升级：git pull && bun install && bun run build。
回滚：git checkout <tag> 后 bun install。
卸载：删仓库目录；本地模型缓存清 ~/.eliza 之类目录。

十一、商用许可与合规风险提示

elizaOS 采用 MIT License（README 末尾明确），商用友好。

注意：

官方不再接受第三方插件注册：README 明确"we no longer accept third-party plugins or registry items"，第三方插件别想上架官方 registry。
Eliza Cloud 是商业服务：账号、模型路由、远程连接是付费云能力；本地运行是 first-class path。
加密钱包能力：非托管钱包操作有审批边界，生产用务必仔细配权限，别把私钥泄露给模型。
贡献规则严格：PR 必须提 issue、走 PRD、写 ASD-STE100 英语，不要乱提 PR。

十二、进阶：本地推理与插件开发

12.1 启用本地推理（Eliza-1）

官方 README 说明：插件 @elizaos/plugin-local-inference 提供 on-device 路径，当前 Eliza-1 registry 含 2B、4B、9B、27B 四个文本档位（基于 Gemma 4），外加本地 embedding、语音、视觉、图像生成资产。硬件检测与模型路由会自动选择支持的后端；资产下载完后，符合条件的操作可以离线运行。

实际部署时建议：

机器显存 ≥ 16GB 再考虑 9B；≥ 48GB 再考虑 27B；
第一次启动会下载 embedding GGUF，慢的话提前下好放到缓存目录；
用 bun run dev:local 启动后，在 runtime chooser 里把对应模型能力切到 local。

12.2 插件开发最小契约

官方 README：一个插件就是一个 Plugin 对象，可以注册 actions / providers / evaluators / services / model handlers / routes / events / tests / app views。第一步读 https://docs.elizaos.ai/plugins/components，再到 plugins/ 下挑一个官方插件照抄结构。

12.3 把整个设备跑成 elizaOS

官方 packages/os/ 提供可启动的 Linux 与 AOSP 发行版、安装器、release manifest 与 OS 工具链。树莓派、旧笔记本、单臂小主机都可以刷成 elizaOS，把它变成一个常年在线的个人 agent 设备。详细构建要求按 packages/os/README.md。

参考链接

官方 README：https://github.com/elizaOS/eliza
官方文档：https://docs.elizaos.ai/
插件组件指南：https://docs.elizaos.ai/plugins/components
elizaOS 发行版：https://github.com/elizaOS/eliza/tree/main/packages/os