elie222/rakazo · 上手攻略
- 仓库：elie222/rakazo
- 链接：https://github.com/elie222/rakazo
- 分类：engineering / agent（自托管 AI 助手全栈 · TypeScript）
- 作者：spark
- 更新：2026-11-04
一、它是什么
Rakazo 是一个开源、自托管的 AI agent 平台，用 TypeScript 写的完整全栈应用。它同时是两种东西：
- 持久化机器人（persistent bots）——每个 bot 有自己的会话、记忆、routine（例行任务）和历史记录，机器人之间还能互相委派（delegate to peer bots），或派发短命 subagent。
- 自托管 AI 助手——跑在你自己的机器上，模型凭据和"电脑"（沙箱）都自己选。
官方定位是 "Open-source Grok Bot alternative"，README 里同时列了它对标的多个产品：Grok Bot、Meta Muse、OpenAI Dots、Instinct、OpenClaw、Hermes Agent、Claude Duet。
形态非常全：Web 版、Electron 桌面版、iPhone（App Store）和 Android（Google Play）都有客户端，全部是同一套 Rakazo API 的前端。
技术栈： - 前端：React 19 + Vite + Tailwind CSS - 客户端：Electron（桌面）+ Expo（移动） - 服务端：Hono + oRPC - 数据：PostgreSQL + Prisma - 认证：Better Auth - 异步任务：Graphile Worker - 模型接入：Pi（bring-your-own-model credentials） - 沙箱：Docker、E2B、Daytona、CreateOS、Boat、以及本机可信电脑 - 集成：Composio、Pipedream Connect、远程 MCP、OpenAPI 工具源
许可与版本：Apache-2.0；最新 release v0.5.0（仓库 package.json 里版本还是 0.1.0，以 release tag 为准）。README 明确标注处于 beta 阶段（"Rakazo is in beta"），卡片里 maturity 标为 production——这个差异需要注意：产品形态完整，但仍在 beta。最近提交 2026-11-03，Stars 约 6.8k。
二、它解决什么问题
核心痛点：主流 AI 助手（ChatGPT、Claude、Grok）把模型、算力沙箱、工具集成全部锁在厂商云端里。你无法做到：
- 自己选模型（要 BYOK 走 OpenRouter 或本地模型）
- 自己选"agent 在哪台电脑上干活"（本地 Docker / E2B / Daytona / CreateOS / Boat / Railway）
- 数据不出自己的机器
- 账号、记忆、历史全部自持
Rakazo 把这些打包成一个可 docker compose 起来的完整产品：
| 能力 | 说明 |
|---|---|
| 持久化 bot | 每个 bot 独立会话 + 记忆 + routine + 历史，关掉前端也在跑 |
| 语音模式 | 说回复、口述、打电话给 bot；自带 ElevenLabs / OpenAI / Cartesia / Fish Audio key，或用 Mac 服务器上已装的 voice |
| 共享 Team Computer + 隔离的 Private computer | 团队共享算力 vs 每个 bot 独占沙箱 |
| 浏览器 / 终端 / 文件 / 图形桌面访问 | agent 能真的操作 GUI，不只是调 API |
| Bot 互相委派 | bot 之间可以派活，也可以派短命 subagent |
| 模型凭据自带 | 通过 Pi 接入任意支持模型 |
| 应用集成 | Composio / Pipedream Connect，外加用户自装的 Treg、远程 MCP、OpenAPI 工具源 |
| 多端客户端 | Web / Electron / iOS / Android，同一套 API |
三、快速安装
路径 A：发布镜像（无需 clone，最省事）
前置：Docker Engine 26+（需要 API 1.45+ 以支持 bot home volume 子路径）、Compose 插件、curl、OpenSSL。
mkdir -p rakazo && cd rakazo &&
curl -fsSLO https://raw.githubusercontent.com/elie222/rakazo/main/infra/compose/install-images.sh &&
bash install-images.sh
安装脚本会：下载 docker-compose.images.yml 与 .env.images.example → 生成含随机密钥的 .env → 拉取镜像并启动。重跑时会保留已有的 .env。
然后打开 http://127.0.0.1:5173，注册账号，连接模型。
镜像 tag 说明：默认是
edge（main 分支构建），多架构（linux/amd64 + linux/arm64）。在有稳定 release 之前不要假设latest存在——官方原话是 "Do not assumelatestis present until a stable release exists"。
受限网络环境（下载被墙/被拦）：
export RAKAZO_DOWNLOAD_BASE="https://your-mirror.example.com/rakazo"
bash install-images.sh --local # 跳过已存在的 Compose 文件
# 或 RAKAZO_DOWNLOAD_SKIP_EXISTING=1
# 也可自行镜像 bootstrap 脚本 URL
先准备配置再启动：
bash install-images.sh --prepare-only
# 编辑 .env：SANDBOX_PROVIDER=boat（或 e2b / daytona / createos）及其 API key、RAKAZO_HOST=your.domain
bash install-images.sh
路径 B：源码 checkout（要改代码时）
前置：Node.js 22.22.2+（22.x 线）/ 24.x / 26+、pnpm 9、Docker。⚠️ Node 23.x 和 25.x 不支持。package.json 里 "packageManager": "pnpm@9.15.0"。
git clone https://github.com/elie222/rakazo.git
cd rakazo
cp .env.example .env
.env 关键项（每个密钥必须独立、长随机、互不复用）：
# 两个不同的密码
POSTGRES_PASSWORD=$(openssl rand -hex 16)
POSTGRES_APP_PASSWORD=$(openssl rand -hex 16)
# 分别填入
DATABASE_URL=postgresql://...
DATABASE_MIGRATION_URL=postgresql://...
BETTER_AUTH_SECRET=<独立长随机值>
ENCRYPTION_KEY=<64 hex，独立>
SCREEN_PROXY_SECRET=<独立长随机值>
SANDBOX_SUPERVISOR_TOKEN=<Docker 沙箱专用，独立>
# 模型
OPENROUTER_API_KEY=sk-... # 可选，也可以在 onboarding 时连接模型提供商
数据库角色设计值得注意：应用以自己的 rakazo_app login 连接（受行级安全 RLS 保护），迁移以 owner 身份运行。
开发模式（Docker Desktop）额外设：
SANDBOX_CONTROL_VIA_LOOPBACK=true # 让 supervisor 自动发现 Docker Desktop 的 user socket
pnpm install
pnpm sandbox:build
pnpm dev
pnpm dev 会优先用 DATABASE_URL 里的 Postgres；连不上就用 Docker 起一个本地 rakazo-dev-postgres 容器（所有 checkout 复用同一个），自动应用迁移并生成 Prisma client。端口被占时自动往下一个空闲块并打印 URL，可用 WEB_PORT / API_PORT 手动指定。
开发期跑 Postgres 而不用 Compose：
docker compose --env-file .env \
-f infra/compose/docker-compose.yml \
-f infra/compose/docker-compose.postgres-host.yml \
up postgres -d # 发布在 127.0.0.1:5433
路径 C：Electron 桌面端
pnpm --filter @rakazo/desktop dev
首次运行会问：在这台电脑上运行 Rakazo，还是连接到已有服务器。选 "This computer" 会用 Docker Compose 装并跑发布镜像（放在 app data 目录，默认端口 45173，可以和 pnpm dev 的 5173 并存）。选 "Existing instance" 则填已有地址（如 http://127.0.0.1:5173）。
路径 D：VPS / 生产
同一套 install-images.sh 装在 VPS 上，然后在桌面/移动端/浏览器里连。前面挂 HTTPS（Caddy），并把三个公开 origin 都设成该 HTTPS URL：BETTER_AUTH_URL、WEB_ORIGIN、API_URL，以及 RAKAZO_HOST 设成主机名。
app.example.com {
reverse_proxy 127.0.0.1:5173
}
⚠️ 公开服务器必须用 HTTPS；HTTP 只接受 loopback 和私有 LAN 地址（不接受 link-local）。
Railway 有一键模板：https://railway.com/new/template/rakazo-template
四、核心用法
4.1 沙箱提供方（agent 在哪干活）
默认 SANDBOX_PROVIDER=docker（本机 Docker 沙箱，注册即用，不需要 E2B 账号）。可切换：
| Provider | 必填配置 | 默认值 / 备注 |
|---|---|---|
docker |
无 | 本机，默认 |
e2b |
E2B_API_KEY |
|
novita |
对应 API key | |
daytona |
对应 API key | |
createos |
CREATEOS_SANDBOX_API_KEY |
base https://api.sb.createos.sh，shape s-2vcpu-2gb，rootfs desktop:1 |
boat |
对应 API key | |
railway |
RAILWAY_API_TOKEN + RAILWAY_ENVIRONMENT_ID（API 和 worker 都要） |
见下方注意 |
| 本机可信电脑 | — | 桌面端 "This computer" |
⚠️ 发布镜像的 Compose 栈对所有 provider 都强制要求 SANDBOX_SUPERVISOR_TOKEN，留空会 fail closed（compose up 直接失败）。
Railway 细节：需要 PRIVATE 网络，Railway 公开域名才能提供屏幕。用最窄的 API token——优先 project token，该 provider 目前用 bearer 认证，所以要用 team/workspace token 而非个人账号 token。建议给沙箱单独开一个 Railway project（或至少独立 environment），与 app、数据库分开。新电脑起在 Railway 默认区域，用 RAILWAY_SANDBOX_REGION（如 asia-southeast1-eqsg3a）拉近 API 位置。工作区导出拒绝超过 64 MiB 的文件且不截断，用 RAILWAY_MAX_WORKSPACE_FILE_BYTES 调整。
4.2 模型接入
OPENROUTER_API_KEY 一填就能用，或在 onboarding 界面里连接支持的模型提供商（含本地模型、自建模型服务器，详见 docs/self-host-models.md）。模型凭据通过 Pi 接入。
4.3 集成与工具源
COMPOSIO_API_KEY=<key> # Composio 应用目录
PIPEDREAM_CLIENT_ID=<id>
PIPEDREAM_CLIENT_SECRET=<secret>
PIPEDREAM_PROJECT_ID=<id> # Pipedream Connect 三件套
托管应用目录是可选的。不启用任何一个目录，用户依然可以在 Integrations 里添加 HTTPS MCP 服务器、Treg endpoint 或 OpenAPI JSON 文档。
⚠️ Treg 是按量计费的：自托管者自带自己的 Treg token；如果运营方把 Treg 嵌进自己的托管产品，需要审查 Treg 的集成条款（要求书面协议才允许托管转售）。
连接器凭据在服务端加密，永不通过 API 返回。
4.4 常用检查命令
pnpm lint
pnpm check
pnpm test
pnpm test:integration
pnpm test:e2e
更多运维文档：docs/self-host-configuration.md（配置分发、运行限额、数据库、出站代理）、docs/self-host-secrets.md（密钥清单）、docs/self-host-observability.md（日志、错误报告、trace、安全事件、告警）、docs/self-host-audit-log.md（谁在哪个组织做了什么、保留期、导出、SIEM 转发）、docs/fleet-management.md（管理 bot 的 bot）。
4.5 客户端与多语言
Electron 和 Expo 应用都是同一套 Rakazo API 的客户端。Web / Electron 支持 English、Deutsch、한국어、Türkçe、हिन्दी、Português (Brasil)、简体中文、繁體中文、Español、Русский、Français、עברית、Nederlands、日本語（Settings → Language）。Expo 应用内含其中 7 种。
桌面端的常用环境变量：RAKAZO_WEB_URL（开发自动化用，把 shell 指到别处而不改已保存的实例）、RAKAZO_FORCE_SETUP=1（重跑 setup）、RAKAZO_DOCKER_BINARY（指定其它兼容 Docker 的 CLI 路径）。
五、典型适用场景
- 数据不能出内网的团队：模型走 OpenRouter（甚至自建模型服务器），agent 的浏览器/终端/桌面在本地 Docker 沙箱里跑，历史和记忆全在自己的 Postgres。
- 要"持久化同事"而不是一次性问答：每个 bot 有 routine 和记忆，可以常驻；bot 之间能互相委派，等价于一个小型 agent 组织。
- 多端无缝：在办公室用桌面端，在路上用手机看 bot 状态和回复，同一个账号同一套历史。
- 要 GUI 级操作能力：bot 能打开浏览器、点终端、动图形桌面——比纯 API tool 调用更适合"跑流程型任务"（比如登录系统填表导出报表）。
- 替代闭源 SaaS：Grok Bot / Muse / Dots / Instinct / OpenClaw / Hermes Agent 的开源替代，Apache-2.0。
- 需要审计合规：内置 audit log，可导出、可转发到 SIEM。
六、坑与注意
坑 1：Node 版本线卡得很死
现象：engines 要求 ^22.22.2 || ^24.0.0 || >=26.0.0。
影响：用 Node 23.x 或 25.x（都是奇数号非 LTS 线）会不被支持，行为未定义。
修复：用 22.22.2 以上的 22.x，或 24.x，或 26+。pnpm 版本按 packageManager 字段锁 9.15.0。
坑 2：Postgres 密码里不能有 URL 特殊字符
现象：官方示例用 openssl rand -hex 16，而不是 openssl rand -base64。
影响：@ : / ? # % 这些字符会撑破 Compose 里插值出来的 DATABASE_URL。
修复：一律用 openssl rand -hex 16。
坑 3：Postgres 数据卷的凭据只在首次初始化时写入
现象：官方 Postgres 镜像只在首次卷初始化时设置 user / password / database。
影响：改了 .env 里的密码后，重启容器连不上，误以为是配置写错。
修复：要么保留 .env 里的原值，要么用 ALTER ROLE / rename 就地改。重建卷只在备份之后做（或者数据可弃时）——⚠️ docker compose down -v 会删除全部 Postgres 状态。
坑 4：ENCRYPTION_KEY 换掉就解不开存量凭据
现象：连接器凭据在服务端加密存储。
影响：改了 ENCRYPTION_KEY 之后，之前存的模型/连接器凭据无法解密。
修复：保留已有的 ENCRYPTION_KEY。这是升级时最容易被忽略的一条。同时 BETTER_AUTH_SECRET、SCREEN_PROXY_SECRET、SANDBOX_SUPERVISOR_TOKEN 必须各自独立、不能复用。
坑 5：Railway 上必须显式选 sandbox environment
现象：Railway 的自动环境 ID 指向托管应用自己的环境。
影响：沙箱和你的 app / 数据库混在同一个 environment 里，既不安全也容易撞资源。
修复：显式设 RAILWAY_ENVIRONMENT_ID。另外 Railway 沙箱是按量计费的。
坑 6：Railway 的电脑首次启动后才装桌面
现象：桌面是在首次启动时安装的。 影响：停止一台电脑会保存其 portable home 但销毁沙箱；下次启动会在新沙箱里恢复 home。第一次用的用户会感觉"数据丢了"，其实是换了沙箱。 修复：预期到这一点；需要真正持久化的东西别只放在沙箱 home 里。
坑 7：Linux 桌面端 AppImage 需要 FUSE 2
现象：Linux 上的 AppImage 需要 libfuse.so.2（FUSE 2）。
影响：只装了 FUSE 3 的发行版（Fedora Silverblue、Ubuntu 24.04）报 dlopen(): error loading libfuse.so.2，应用起不来。
修复：装 FUSE 2 库（Fedora 用 fuse-libs，Ubuntu 24.04 用 libfuse2t64，旧版 Ubuntu/Debian 用 libfuse2），或者绕过 FUSE：chmod +x Rakazo-*.AppImage && ./Rakazo-*.AppImage --appimage-extract-and-run。
坑 8：桌面端只认 docker CLI，不认 Podman
现象：本地电脑功能会去找 docker CLI，不检测 Podman。
影响：只用 Podman 的机器上，"This computer" 装不起来。
修复：用兼容 docker compose 的其它 CLI 时，启动应用前设 RAKAZO_DOCKER_BINARY=<路径>。
坑 9：安装脚本会拉取并运行远程 shell
现象：curl -fsSLO .../install-images.sh && bash install-images.sh 直接执行远端脚本。
影响：在受管环境里这违反大多数安全策略；受限网络下也根本拉不下来。
修复：先把脚本下载下来审阅再执行；受限网络用 RAKAZO_DOWNLOAD_BASE + --local 走镜像源。仓库也提供了 SETUP_PROMPT.md 供 agent 辅助安装。
坑 10：发布镜像的 Compose 默认只绑 loopback
现象：images Compose 把 web 绑在 127.0.0.1:5173。
影响：想直接暴露 5173 到公网是错的，也违背设计。
修复：在宿主机终止 TLS 再反代（Caddy）；把 BETTER_AUTH_URL / WEB_ORIGIN / API_URL 都设成同一个 HTTPS origin，RAKAZO_HOST 设成主机名。⚠️ 不要暴露 :3100（Vite preview 的 same-origin 代理 /api 和 /rpc）。
坑 11：Windows 上的 CRLF 会让沙箱启动卡死
现象：老 clone 设了 core.autocrlf=true，电脑面板启动时卡住（sandbox 日志里出现 bash\r）。
影响：沙箱起不来，界面看起来是"挂住"。
修复：从干净 worktree 出发执行：git config core.autocrlf false → git add --renormalize . && git checkout -- . → 重新 pnpm sandbox:build。
坑 12：开发期 Postgres 的两个角色要分清
现象：DATABASE_URL 与 DATABASE_MIGRATION_URL 是两个不同的连接串。
影响：都指向同一库但用错角色，会绕过或破坏 RLS 边界。
修复：应用连接用 rakazo_app（受行级安全保护），迁移用 owner。宿主机侧客户端（pnpm db:migrate、GUI 工具）需要加 docker-compose.postgres-host.yml overlay 把 Postgres 发布到 loopback 5433——不要发布到公网接口。
坑 13：注册账号永远拿不到服务器管理权限
现象：文档反复强调 "Signup never grants server-administration permissions"。
影响：误以为注册后能管服务器的用户会卡住。
修复：服务器管理是独立配置项（见 docs/self-host-configuration.md），走管理员路径设置。
坑 14：Treg 转售有额外条款
现象：Treg 是按量计费的，自托管者自带 token。 影响：把 Treg 嵌进自己的托管产品转售，需要与 Treg 的书面协议，否则违规。 修复：做托管产品前先读 https://treg.to/integrate.md 并取得书面许可。
坑 15：项目仍在 beta，且 package.json 版本落后
现象：README 标 "Rakazo is in beta"，最新 release 是 v0.5.0，而 package.json 里 "version": "0.1.0"。
影响：用 package.json 判断版本会误判；生产部署按"稳定工具"预期会失望。
修复：以 release tag 为准，⚠️ 本文版本信息抓取于 2026-11-04，实际以 gh release / docker pull 到的 tag 为准。
七、与同类对比
| 维度 | elie222/rakazo | Grok Bot / Muse / Dots（闭源 SaaS） | OpenClaw / Hermes Agent（同类开源） | 自建 LangGraph / CrewAI 应用 |
|---|---|---|---|---|
| 部署 | 自托管 docker compose / 源码 | 厂商托管 | 自托管 | 自建 |
| 模型 | BYOK，OpenRouter / 本地 / 自建 | 厂商模型 | 多模型 | 需自己接 |
| 沙箱 | Docker / E2B / Daytona / CreateOS / Boat / Railway / 本机 | 厂商侧 | 部分支持 | 需自己接 |
| 持久化 bot + 记忆 | ✅ 核心设计 | ✅ | 部分 | 需自建 |
| 移动端 | ✅ iOS + Android | ✅ | 部分 | 无 |
| 语音 | ✅ 多家 TTS key | ✅ | 部分 | 需自建 |
| GUI 级操作 | ✅ 浏览器/终端/文件/图形桌面 | 部分 | 部分 | 需自建 |
| 成熟度 | beta（形态完整） | 稳定 | 各自不一 | 看你自己 |
| 运维成本 | 需自己管 Postgres/证书/备份 | 零 | 中 | 高 |
| 审计日志 | ✅ 内置，可接 SIEM | 闭源 | 各自不一 | 需自建 |
选型建议：想要"装完就有完整产品"（含移动端、语音、bot 编排、审计）又必须自托管，Rakazo 值得试；如果只是要跑一个 agent 流程，LangGraph/CrewAI 这类库 + 几行胶水更轻；如果不在乎数据出网，闭源 SaaS 省心得多。
八、一句话推荐
如果你需要一个"自己的 Grok Bot"——自托管、模型和沙箱都自己选、带移动端、语音和持久化记忆的完整 agent 平台——Rakazo 是目前开源里形态最全的一个，install-images.sh 三行命令就能跑起来；但它还在 beta（v0.5.0），生产部署请务必固定镜像 tag、锁住 ENCRYPTION_KEY、用 openssl rand -hex 16 生成数据库密码，并且按上面第 1、3、4 条坑核对 Node 版本与 Postgres 初始化行为。