很多人第一次做 OpenClaw Mac Mini 部署 时，会默认认为“Docker 更专业，原生安装只是临时测试”。这个判断并不总是成立：OpenClaw 需要长期运行 Gateway、访问配置文件，甚至可能调用本机文件、命令行工具和消息渠道，容器隔离反而可能增加权限与路径配置。
真正影响稳定性的，通常不是“有没有用 Docker”，而是你是否提前想清楚 3 件事：Agent 要访问哪些本地资源、重启后能否自动恢复、以后升级或迁移时能否完整带走状态。下面不只讲安装命令，而是把两种方案放到长期运维场景里比较。
Mac Mini 作为 AI Agent 主机
OpenClaw 的核心并不是一个打开网页才工作的聊天页面，而是持续运行的 Gateway。官方入门流程会在本机启动服务，并监听 18789 端口，控制界面通常通过 http://localhost:18789 或 http://127.0.0.1:18789 访问。(docs.openclaw.ai)
这使 Mac Mini 适合承担常驻 AI Agent 主机的角色：
- ✅ 长时间保持 Gateway 在线，不依赖个人电脑是否合盖或关机；
- ✅ 可以把工作目录、脚本、日志和 Agent 配置放在本地磁盘；
- ✅ 方便连接消息渠道、自动化脚本、代码仓库和本机开发工具；
- ✅ macOS 环境对需要 Apple 平台工具链的团队更友好。
但“常驻运行”也会带来隐性成本。第一，API 密钥、消息渠道凭证和 Agent 状态都需要妥善保护；第二，Mac Mini 重启后，服务不一定自动恢复；第三，如果 Agent 需要访问桌面文件、命令行工具或浏览器，权限边界会比普通 Web 应用复杂。
因此，Mac Mini AI Agent 搭建的第一步不是直接复制安装命令，而是先画出访问边界：哪些目录可以读写，哪些命令允许执行，哪些服务只能通过本机回环地址访问。
原生安装与 Docker 的核心差异
原生安装的优势
原生方式直接运行在 macOS 用户环境中，OpenClaw 可以更自然地访问用户目录、Shell 环境和本机已安装的工具。对于需要连接 Homebrew、脚本、浏览器或其他 macOS 应用的个人开发者，排查问题也更直观。
它的主要缺点是环境耦合。Node、系统权限、全局依赖和用户目录发生变化，都可能影响 Gateway；如果你频繁切换版本，升级失败后回滚也更依赖自己的备份。
Docker 的优势
Docker 会把 Gateway 和依赖放进容器，便于固定运行环境，也更适合小团队复制相同配置。官方容器方案使用 Docker Compose 管理服务，并支持通过卷保存 /home/node 等状态目录。官方文档还说明，Docker 部署至少需要 2 GB 内存用于构建镜像，内存过低时可能出现构建进程被系统终止。(docs.openclaw.ai)
Docker 的代价也很明确：
- ❌ 容器内的
127.0.0.1指向容器自身，不是 Mac 主机； - ❌ 容器默认没有 Homebrew，部分依赖需要自行制作镜像或手动安装；
- ❌ 本机目录、密钥目录和浏览器能力都要显式挂载；
- ⚠️ 只重建容器、不保留卷，可能导致 Agent 配置和认证状态丢失。
所以，“OpenClaw 原生安装还是 Docker”不能只看隔离性。需要调用大量 macOS 本地能力时，原生更省事；需要环境复制、版本固定和多人协作时，Docker 更容易管理。
原生安装流程
如果你的目标是先验证模型、消息渠道和 Agent 工作流，原生安装通常是最快的路径。
1．准备独立用户与目录
不要直接用日常管理员账户运行长期 Agent。建议创建一个专用 macOS 用户，并规划以下目录：
mkdir -p "$HOME/.openclaw-backup"
mkdir -p "$HOME/Library/Logs/OpenClaw"
专用账户可以减少 Agent 误读个人文件、SSH 密钥和浏览器数据的风险。若必须访问项目目录，优先授予单独工作目录，而不是开放整个用户主目录。
2．执行官方安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash
安装完成后，按向导填写模型服务所需的 API 密钥，并确认 Gateway 是否成功启动。官方流程会提示 Gateway 监听端口；默认控制界面通常是：
http://localhost:18789
安装脚本来自远程地址，生产环境不建议盲目长期重复执行。团队部署前，应该先固定版本、保存脚本校验结果，并在测试用户下验证。
3．确认服务状态与控制界面
先检查端口：
curl -I http://127.0.0.1:18789
lsof -nP -iTCP:18789 -sTCP:LISTEN
如果浏览器打不开，先不要急着改成公网监听。确认服务确实存在、端口没有被其他程序占用，再检查配置文件和 macOS 防火墙。
4．备份配置与密钥
至少备份以下内容：
- OpenClaw 主配置；
- API 密钥和认证配置；
- 消息渠道配对信息；
- Agent 工作目录；
- 自定义脚本与启动文件。
备份时不要把明文密钥直接提交到 Git 仓库。可以使用权限为 600 的本地文件，并把备份存放在加密磁盘或受控密码管理系统中。
5．配置 OpenClaw 开机自启设置
原生安装可以使用 launchd。建议创建用户级 plist，而不是把服务放在系统级目录：
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>local.openclaw.gateway</string>
<key>ProgramArguments</key>
<array>
<string>/完整路径/openclaw</string>
<string>gateway</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>/Users/你的用户名/Library/Logs/OpenClaw/gateway.log</string>
<key>StandardErrorPath</key>
<string>/Users/你的用户名/Library/Logs/OpenClaw/gateway-error.log</string>
</dict>
</plist>
保存后加载：
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/local.openclaw.gateway.plist
launchctl kickstart -k gui/$(id -u)/local.openclaw.gateway
如果你使用 PM2，也要明确 PM2 管理的是哪个用户、Node 路径和工作目录。很多“重启后 Agent 离线”问题，根源不是 OpenClaw 本身，而是自启服务找不到交互式 Shell 中才存在的环境变量。
Docker Compose 部署流程
Docker 方案适合需要环境复制、快速回滚，或者不希望直接污染 macOS 全局 Node 环境的团队。官方 Docker 文档建议从项目目录运行设置脚本，并通过 Compose 启动 Gateway。(docs.openclaw.ai)
1．安装 Docker Desktop 与 Compose
先确认命令可用：
docker version
docker compose version
如果构建期间出现 ResourceExhausted、cannot allocate memory 或 exit 137，先提高 Docker 的构建内存，再重新执行，而不是反复重启 Compose。官方文档给出的典型排查方向是调整 Node 构建堆大小或 Docker Builder 内存。(docs.openclaw.ai)
2．准备项目目录与环境变量
mkdir -p ~/openclaw-docker
cd ~/openclaw-docker
使用官方项目提供的 Docker 设置脚本时，先检查 .env 是否包含正确的镜像、端口和认证参数。不要把 .env 直接上传到代码仓库。
3．执行容器设置
官方流程会完成镜像构建或拉取、初始化向导、Token 写入和 Compose 启动。示例形式如下：
./scripts/docker/setup.sh
如果使用预构建镜像，需要固定到已验证的版本标签，不建议生产环境长期依赖不断变化的 latest。首次部署完成后，打开：
http://127.0.0.1:18789/
然后把 .env 中的 Gateway Token 填入控制界面。(docs.openclaw.ai)
4．设置状态持久化
OpenClaw Docker 部署教程中最容易被忽略的是卷。容器删除后，容器内未挂载的数据不会自动保留。Compose 的命名卷可以在服务重建后继续使用，但如果你手动删除卷，数据也会随之消失。(docs.docker.com)
可以采用类似结构：
services:
openclaw-gateway:
restart: unless-stopped
volumes:
- openclaw-state:/home/node/.openclaw
- ./workspace:/workspace
volumes:
openclaw-state:
同时备份 Compose 文件、.env、挂载目录和卷清单。只备份工作目录而不备份状态卷，迁移后可能出现 Agent 重新要求认证、渠道配对丢失等问题。
5．设置容器自动恢复
Compose 支持 restart: unless-stopped，适合主机重启后自动恢复服务；on-failure 则更适合只在异常退出时重启。Docker 官方文档明确区分了这些策略，docker compose restart 本身只是重启服务，不会自动应用你刚修改的环境变量。(docs.docker.com)
修改环境变量后，应使用：
docker compose up -d
必要时强制重建：
docker compose up -d --force-recreate
不要把 docker compose restart 当作配置更新命令，否则你可能以为新 Token 或端口已经生效，实际容器仍在使用旧环境。
远程访问与安全边界
OpenClaw 远程访问最稳妥的思路，是让 Gateway 继续绑定本机或受控网络，再通过加密组网访问，而不是直接把 18789 暴露到公网。
localhost 绑定
原生安装时优先使用 localhost 或 127.0.0.1。Docker 场景需要区分容器内回环地址与主机端口映射：容器内部的 127.0.0.1 不代表 Mac 主机。官方文档还说明，容器访问主机服务时，macOS Docker 环境通常需要使用 host.docker.internal。(docs.openclaw.ai)
Tailscale 远程连接
如果需要从外部访问，先在 Mac 上安装并登录组网客户端，再通过 SSH 隧道或受控网络访问本地端口。当前 macOS 客户端要求系统至少为 macOS Monterey 12.0。(tailscale.com)
例如使用 SSH 本地转发：
ssh -N -L 18789:127.0.0.1:18789 用户名@你的Mac地址
然后在本地浏览器打开：
http://127.0.0.1:18789
不要同时开放公网端口、关闭认证，再把 Token 放进聊天记录。对于小团队，至少要做到：限制访问成员、启用 Gateway 认证、单独保存密钥、记录登录来源，并定期检查 Agent 工作目录中的敏感文件。
常见故障排查
服务无法启动
先查看端口和日志：
lsof -nP -iTCP:18789 -sTCP:LISTEN
tail -n 100 ~/Library/Logs/OpenClaw/gateway-error.log
Docker 则使用：
docker compose ps
docker compose logs --tail=100 openclaw-gateway
如果是原生安装，重点检查 Node 路径、用户权限和环境变量；如果是容器，重点检查镜像、挂载目录和 .env。
控制界面打不开
确认访问地址是否写成 localhost:18789，并检查服务是否只绑定在容器内部。Docker 官方 OpenClaw 镜像提供 /healthz 和 /readyz 探针，可用以下命令判断服务是未启动，还是已经启动但认证失败：
curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz
重启后配置消失
原生方案检查是否使用了错误的用户目录；Docker 方案检查卷是否挂载到正确位置。尤其不要只执行 docker compose down -v 后再重建，因为 -v 会连同命名卷一起删除。
Agent 能启动但无法执行任务
这通常是权限边界，而不是模型问题。检查工作目录是否挂载、命令是否存在、macOS 是否弹出了文件访问授权，以及 Docker 内是否缺少必要依赖。容器中没有 Homebrew 时，依赖安装方式也和原生 macOS 不同。(docs.openclaw.ai)
部署方案决策表
| 场景 | 更适合的方案 | 主要原因 | 需要提前防范的问题 |
|---|---|---|---|
| 个人开发者先验证模型与消息渠道 | 原生安装 | 上手快，调试路径短 | 用户权限、Node 环境污染 |
| 需要访问 macOS 文件、脚本和本地工具 | 原生安装 | 本机路径与权限更直接 | 备份和升级回滚 |
| 小团队复制相同运行环境 | Docker Compose | 配置、镜像和服务更容易复用 | 卷、.env 与挂载权限 |
| 需要频繁测试多个版本 | Docker Compose | 更容易固定镜像并回滚 | 镜像标签和卷兼容性 |
| 需要长期在线并自动恢复 | 两者均可 | 分别使用 launchd 或 restart |
日志、健康检查和告警 |
| 没有本地 Mac Mini，但要快速上线 | 云端 Mac | 无需等待硬件采购，可远程接入 | 密钥迁移、网络延迟和数据清理 |
本地 Mac Mini 与云端 Mac 迁移
如果你已经有本地 Mac Mini，迁移前先导出配置、状态目录、工作目录和消息渠道认证，再在新机器上逐项恢复。不要直接复制整个用户目录，否则可能把旧的 SSH 密钥、浏览器 Cookie 和个人文件一起带过去。
如果没有本地设备，OpenClaw 云端 Mac 部署可以先从短周期验证开始。SpinMac 当前提供独享的 Mac mini M4 物理机，页面列出的统一配置为 10 核 CPU、16 GB 统一内存、256 GB SSD、1 Gbps 独享带宽和独立公网 IPv4；支持 SSH、浏览器 VNC 与管理员 sudo 权限。(spinmac.com)
SpinMac 页面显示，云端 Mac 支持新加坡、东京、首尔、中国香港和美国东部节点，付款后库存充足时通常在 1 至 5 分钟内完成交付；当前页面展示的按天起租价格为 $21.2 / 天。具体可用节点、租期与扩容选项，应以云端 Mac 价格方案和下单页面为准。(spinmac.com)
迁移前建议按这个顺序检查：
- 确认新机器的 macOS 版本、磁盘空间和远程连接方式；
- 通过 SSH 或 VNC 登录，并创建专用 OpenClaw 用户；
- 重新生成或安全导入 API 密钥，不要把旧密钥散落在脚本中；
- 先恢复配置与状态，再恢复工作目录；
- 启动 Gateway 后验证
18789、健康检查、消息渠道和开机自启； - 确认运行稳定后，再撤销旧机器上的 Token 和 SSH 密钥。
对于需要固定公网地址、异地协作或快速测试的团队，云端 Mac 的交付速度和远程接入会比自行采购、初始化和配置硬件更省时间。你也可以先查看SpinMac 帮助中心，确认 SSH、VNC 和账单流程，再决定是否迁移。
该怎么做最终选择
如果你只是想在一台 Mac Mini 上运行一个 Agent，并且它需要频繁访问本地脚本、文件和 macOS 工具，先选原生安装，配合专用用户、launchd 和定期备份，维护路径通常更短。
如果你更在意环境隔离、团队复制、版本回滚和批量部署，Docker Compose 更合适，但必须把状态卷、工作目录、认证文件和健康检查一起设计。只部署容器而不设计持久化，表面上隔离了环境，实际上增加了数据丢失风险。
对没有本地设备的人来说，自行购买 Mac Mini 的缺点是前期采购成本高、到货和初始化周期不可控，还要自己处理公网访问、断电重启和异地维护；普通共享云主机则可能缺少完整 macOS 权限，无法覆盖需要本机工具链的 Agent 工作流。租用 SpinMac 的独享 Mac mini M4，可以直接获得完整 macOS、sudo、SSH / VNC 和固定远程主机，更适合先验证 OpenClaw，再决定是否长期购置硬件。你可以前往开始配置云端 Mac，按照实际运行时长和节点需求选择资源。