macOS Apple Silicon部署OpenClaw全栈指南：Homebrew、Python虚拟环境与launchd实战
1. 项目概述：这不是一次简单的“装软件”，而是一场 macOS 硬件适配的实战突围
第一次把 OpenClaw 部署在 Mac mini 上，我原以为就是照着 GitHub README 跑几条命令的事——毕竟 Homebrew 一键安装、SSH 远程管理、Docker 容器化，这些词在教程里都闪着光。结果现实狠狠给了我一记“苹果味”的耳光： openclaw: command not found 、 fatal: cannot change to '/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core' 、 SSH connection timed out ……这些报错不是孤立的错误提示，而是 macOS 系统底层逻辑、Apple Silicon 架构特性、Homebrew 包管理机制、OpenClaw 自身依赖链之间激烈碰撞后留下的弹坑。这台 Mac mini（我用的是 M2 芯片的 2023 款，但实测结论对 M1/M3 同样适用）不是 Windows 台式机，它没有传统意义上的“管理员权限”概念，它的 /usr/local 目录默认受 SIP（系统完整性保护）严密看守，它的终端 shell 默认是 zsh 而非 bash，它的网络栈对某些 SSH 隧道行为有更严格的连接复用策略。OpenClaw 本身又是个典型的“AI 工具链聚合体”，它不直接提供二进制可执行文件，而是依赖 Python 环境、特定版本的 pydantic 、 httpx 、 rich ，甚至需要调用系统级的 displayplacer （用于多显示器自动化）或 osascript （用于 macOS 原生交互）。所以，这次部署的本质，是一次对 macOS 生态规则的深度阅读与主动适配。它适合三类人：一是刚入手 Mac mini 想把它变成“家庭 AI 中枢”的极客，二是被公司配了 Mac 笔记本、想在本地复现生产环境的开发者，三是正在评估 OpenClaw 是否真能落地到 macOS 生产环境的技术决策者。你不需要是 macOS 内核专家，但必须愿意放下“Windows 思维”，去理解 brew install --cask 和 brew install 的根本区别，明白为什么 sudo chown -R $(whoami) /usr/local 在新系统上会失败，以及 SSH 连接超时背后，到底是防火墙、钥匙串、还是 ssh_config 里一个 ServerAliveInterval 参数没配对。这不是一份“复制粘贴就能跑”的速成指南，而是一份记录了所有真实断点、所有被忽略的隐含前提、所有必须亲手验证的细节的“战地日志”。
2. 整体设计思路：为什么必须放弃“直觉”，拥抱 macOS 的“约定俗成”
部署 OpenClaw 的核心矛盾，从来不是 OpenClaw 本身有多难，而是我们习惯性地用其他平台的经验去“硬套”macOS。我最初尝试的方案非常“直觉”：打开 Terminal， curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh | bash ，然后 brew install openclaw ，最后 openclaw start 。三分钟，搞定。结果呢？Homebrew 安装卡在 Cloning into '/opt/homebrew'... ，卡了整整 22 分钟，最后报错 Failed to download resource "openssl@3" ；好不容易用国内镜像源绕过去， brew install openclaw 却提示 No available formula or cask with the name "openclaw" ；退而求其次，用 pip3 install openclaw ，装完一运行， ModuleNotFoundError: No module named 'pydantic.v1' 。这一连串失败，逼着我彻底重构了整个部署逻辑。最终成型的方案，是一个分层、隔离、可审计的四步结构：
2.1 第一层：环境基石——Homebrew 的“非标准”安装路径与权限模型
在 macOS 上，Homebrew 的默认安装路径是 /opt/homebrew （Apple Silicon）或 /usr/local/Homebrew （Intel），这本身就暗示了它的设计哲学： 它不追求“侵入系统”，而追求“与系统共存”。 所以，任何试图用 sudo chown 去暴力接管 /usr/local 的做法，在 macOS Monterey 及以后的系统上都是徒劳且危险的。正确的起点，是接受并利用这个路径。我选择将 Homebrew 安装到用户目录下的 ~/homebrew ，这是一个完全由用户掌控、不受 SIP 干扰的“安全区”。命令是：
mkdir -p ~/homebrew && curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C ~/homebrew
然后，将 ~/homebrew/bin 加入 ~/.zshrc 的 PATH 最前面：
echo 'export PATH="$HOME/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
这样做的好处是：第一，彻底规避了 SIP 权限问题；第二， brew 命令的执行主体永远是当前用户，不会出现 Permission denied ；第三，卸载时只需 rm -rf ~/homebrew ，干净利落。这是整个部署的“地基”，地基不稳，后面所有操作都会在权限和路径上反复踩坑。
2.2 第二层：依赖隔离——Python 环境的“双保险”策略
OpenClaw 是 Python 项目，但它对依赖版本极其敏感。官方文档说“支持 Python 3.9+”，但实测发现， pydantic 的 v1 和 v2 版本 API 差异巨大，而 OpenClaw 的某个核心模块 openclaw.skill 显式依赖 pydantic<2.0.0 。如果直接用系统自带的 Python 或全局 pip 安装，很容易污染环境。我的方案是“双保险”：先用 Homebrew 安装一个纯净的 Python 3.11，再用 venv 创建一个专属虚拟环境。
# 安装 Python 3.11（Homebrew 会自动处理其所有依赖，如 openssl、readline）
brew install python@3.11
# 创建并激活虚拟环境
python3.11 -m venv ~/openclaw-venv
source ~/openclaw-venv/bin/activate
# 升级 pip 到最新版（避免旧版 pip 解析依赖出错）
pip install --upgrade pip
这个 ~/openclaw-venv 就是 OpenClaw 的“专属房间”，所有包都只在这个房间里生效，与系统和其他项目完全隔绝。这比 conda 更轻量，比全局 pip 更安全，是 macOS 上 Python 项目的黄金标准。
2.3 第三层：服务托管——从“前台命令”到“后台守护”的质变
在 Linux 上，我们习惯 nohup openclaw start & 或写个 systemd service。但在 macOS 上， nohup 不可靠， systemd 不存在。真正的 macOS 方式是 launchd ，它是 macOS 的原生服务管理器，能实现开机自启、崩溃自动重启、日志集中管理。我为 OpenClaw 编写了一个 com.openclaw.agent.plist 文件，放在 ~/Library/LaunchAgents/ 下：
<?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>com.openclaw.agent</string>
<key>ProgramArguments</key>
<array>
<string>/Users/yourusername/openclaw-venv/bin/python</string>
<string>-m</string>
<string>openclaw</string>
<string>start</string>
<string>--config</string>
<string>/Users/yourusername/.openclaw/config.yaml</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>/Users/yourusername/Library/Logs/openclaw.log</string>
<key>StandardErrorPath</key>
<string>/Users/yourusername/Library/Logs/openclaw-error.log</string>
<key>EnvironmentVariables</key>
<dict>
<key>PYTHONPATH</key>
<string>/Users/yourusername/openclaw-venv/lib/python3.11/site-packages</string>
</dict>
</dict>
</plist>
关键点在于 RunAtLoad （登录即启动）和 KeepAlive （进程退出后自动拉起），这保证了 OpenClaw 真正做到了“24/7 运行”。而 StandardOutPath 和 StandardErrorPath 则把所有日志导向一个固定位置，排查问题时再也不用 ps aux | grep openclaw 然后 tail -f 一堆进程了。
2.4 第四层：远程访问——SSH 的“穿透式”配置与安全加固
Mac mini 作为服务器，必然要远程管理。但 macOS 的 SSH 服务默认是关闭的，且其 sshd_config 对密钥认证、端口转发等有严格限制。我开启 SSH 的方式不是简单地在“系统设置”里勾选“远程登录”，而是手动编辑 /etc/ssh/sshd_config ：
# 允许密钥认证（禁用密码，更安全）
PubkeyAuthentication yes
PasswordAuthentication no
# 允许端口转发（为后续可能的 Web UI 访问做准备）
AllowTcpForwarding yes
GatewayPorts clientspecified
# 设置一个非标准端口（避开 22 端口的暴力扫描）
Port 2222
然后重启服务： sudo launchctl unload /System/Library/LaunchDaemons/ssh.plist && sudo launchctl load -w /System/Library/LaunchDaemons/ssh.plist 。接着，我在本地 Mac 或 Windows 电脑上，用 ssh -p 2222 -L 8080:localhost:8080 yourusername@macmini-ip 建立一个本地端口转发，这样就能通过 http://localhost:8080 安全地访问 OpenClaw 的 Web 控制台，而无需将 OpenClaw 的端口暴露在公网。这套组合拳，把 OpenClaw 从一个“能跑起来的命令行工具”，变成了一个“可管理、可监控、可恢复、可远程”的生产级服务。
3. 核心细节解析与实操要点：那些文档里绝不会写的“魔鬼细节”
部署过程中，最耗时间的往往不是大框架，而是那些藏在犄角旮旯里的“小细节”。它们看起来微不足道，却足以让整个流程卡死数小时。我把这些细节按发生顺序梳理出来，并附上我的实操心得。
3.1 Homebrew 安装阶段：国内镜像源的“正确打开方式”
Homebrew 的官方源 https://github.com/Homebrew/brew 在国内下载速度极慢，几乎无法完成。网上流传的“修改 HOMEBREW_BOTTLE_DOMAIN 环境变量”方法，在新版 Homebrew 上已经失效。真正有效的方法，是 在安装脚本执行前，就用 git 的 url.*.insteadOf 功能，全局替换所有 GitHub 地址 。具体操作如下：
# 1. 克隆 Homebrew 的核心仓库（brew）到本地
git clone https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git ~/homebrew
# 2. 进入该目录，配置 git，让所有对 github.com 的请求都重定向到清华镜像
cd ~/homebrew
git config --global url."https://mirrors.tuna.tsinghua.edu.cn/git/".insteadOf "https://github.com/"
git config --global url."https://mirrors.tuna.tsinghua.edu.cn/git/".insteadOf "git://github.com/"
# 3. 初始化并更新
git init && git remote add origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git
git fetch origin master
git reset --hard origin/master
提示：这里的关键是
git config --global url."xxx".insteadOf "yyy"。它不是改一个 URL，而是改了 git 的全局行为，让所有后续的git clone、git pull都自动走镜像。这比修改HOMEBREW_BOTTLE_DOMAIN或HOMEBREW_CORE_GIT_REMOTE更底层、更彻底。我试过中科大、阿里云、腾讯云的镜像，清华的tuna在 macOS 上的稳定性最高，brew update速度能从 15 分钟缩短到 30 秒内。
3.2 OpenClaw 安装阶段：“找不到命令”的终极解法
brew install openclaw 报错 No available formula ，是因为 OpenClaw 官方并未将其打包为 Homebrew Formula。它不是一个独立的 CLI 工具，而是一个 Python 库。所以， pip install openclaw 才是正解。但直接 pip install 会失败，原因有三：
-
pydantic版本冲突 ：OpenClaw 的setup.py里写的是pydantic>=1.10,<2.0，但 pip 默认会安装最新的pydantic2.x。解决方案是强制指定版本：pip install "pydantic<2.0" "httpx>=0.23.0" "rich>=13.0.0"，然后再pip install openclaw。 -
click命令行库的入口点缺失 ：OpenClaw 的pyproject.toml里定义了openclaw = "openclaw.cli:main"，但某些 pip 版本在安装时会忽略这个入口点。解决方案是手动创建一个openclaw脚本：
echo '#!/usr/bin/env python3.11
from openclaw.cli import main
if __name__ == "__main__":
main()' > ~/openclaw-venv/bin/openclaw
chmod +x ~/openclaw-venv/bin/openclaw
-
PATH环境变量未刷新 ：即使脚本创建成功，如果~/openclaw-venv/bin不在PATH里，终端依然找不到openclaw命令。解决方案是在~/.zshrc里追加：
echo 'export PATH="$HOME/openclaw-venv/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
注意：
source ~/.zshrc必须在当前终端窗口里执行，否则新开的终端才生效。很多新手在这里卡住，以为命令没装好，其实是环境没加载。
3.3 SSH 连接阶段：“Connection timed out”的五层排查法
ssh: connect to host xxx.xxx.xxx.xxx port 22: Connection timed out 这个错误，是 macOS 新手最常遇到的“拦路虎”。它不是单一问题，而是一个故障树。我总结了一套五层排查法，按顺序执行，99% 的情况都能定位：
- 物理层 ：确认 Mac mini 的网线/无线已连接，
ifconfig | grep "inet "能看到有效的 IP 地址（如192.168.1.100），且与你的本地电脑在同一网段。 - 服务层 ：在 Mac mini 上执行
sudo launchctl list | grep ssh，确认com.openssh.sshd进程正在运行。如果没有，说明 SSH 服务根本没启动。 - 防火墙层 ：macOS 的“防火墙”设置（在“系统设置”->“网络”->“防火墙”）默认会阻止所有入站连接。必须点击“防火墙选项”，勾选“允许远程登录的传入连接”。
- 端口层 ：如果你修改了
sshd_config的Port，那么连接时必须指定-p参数。例如，ssh -p 2222 user@ip。用nmap -p 2222 ip可以快速验证端口是否开放。 - 密钥层 ：
ssh-copy-id复制公钥后，检查 Mac mini 上~/.ssh/authorized_keys文件的权限是否为600（chmod 600 ~/.ssh/authorized_keys），且~/.ssh目录权限为700。权限过宽，sshd会直接拒绝登录。
3.4 OpenClaw 配置阶段： config.yaml 的“最小可行配置”
OpenClaw 的 config.yaml 文档写得非常详尽，但新手容易陷入“配置恐惧症”，不敢动。其实，一个能跑起来的最小配置，只需要三行：
# ~/.openclaw/config.yaml
llm:
provider: "openai"
api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
model: "gpt-4-turbo"
实操心得：
api_key必须是有效的 OpenAI API Key，不能是网页登录的账号密码。model名称必须与 OpenAI 官方文档一致，gpt-4-turbo是目前最稳定的选择。其他所有配置项，如skills、tools、webui，都可以先留空，等基础功能跑通后再逐步添加。我见过太多人因为一开始就想配置“完美”的skills，结果openclaw start报错KeyError: 'browser'，最后发现只是少了一个browser:的空行。
4. 实操过程与核心环节实现：从零开始，一步一截图（文字版）
现在，让我们把上面所有的思路和细节，整合成一份可逐行执行的、完整的实操手册。我会精确到每一个命令、每一个文件路径、每一个需要你手动输入的内容。请确保你有一台已联网的 Mac mini，并以管理员身份登录。
4.1 步骤一：初始化 Homebrew（约 5 分钟）
打开 Terminal（访达 -> 应用程序 -> 实用工具 -> 终端），依次执行以下命令。注意，每一条命令执行后，都要等待它完成（光标回到下一行，且没有 ^C 或 error 字样）再执行下一条。
# 1. 创建 homebrew 安装目录
mkdir -p ~/homebrew
# 2. 使用清华镜像源下载并解压 Homebrew 核心
curl -L https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew/archive/master.tar.gz | tar xz --strip 1 -C ~/homebrew
# 3. 配置 git 全局镜像（关键！）
cd ~/homebrew
git config --global url."https://mirrors.tuna.tsinghua.edu.cn/git/".insteadOf "https://github.com/"
git config --global url."https://mirrors.tuna.tsinghua.edu.cn/git/".insteadOf "git://github.com/"
# 4. 将 homebrew/bin 加入 PATH
echo 'export PATH="$HOME/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# 5. 验证安装
brew --version
# 正确输出应为类似：Homebrew 4.3.5-12-ga1b2c3d (git revision a1b2c3d; last commit 2024-05-20)
实操记录：执行第 2 步时，
curl命令会显示下载进度，大约 2MB，耗时 10-20 秒。第 4 步的source ~/.zshrc是必须的，否则brew --version会报command not found。我第一次漏掉了这一步，白白浪费了 15 分钟。
4.2 步骤二：构建 Python 环境（约 3 分钟）
# 1. 用 Homebrew 安装 Python 3.11
brew install python@3.11
# 2. 创建虚拟环境
python3.11 -m venv ~/openclaw-venv
# 3. 激活虚拟环境
source ~/openclaw-venv/bin/activate
# 4. 升级 pip
pip install --upgrade pip
# 5. 安装 OpenClaw 的核心依赖（解决 pydantic 版本问题）
pip install "pydantic<2.0" "httpx>=0.23.0" "rich>=13.0.0"
# 6. 安装 OpenClaw 本身
pip install openclaw
# 7. 手动创建 openclaw 命令入口（解决 pip 入口点丢失）
echo '#!/usr/bin/env python3.11
from openclaw.cli import main
if __name__ == "__main__":
main()' > ~/openclaw-venv/bin/openclaw
chmod +x ~/openclaw-venv/bin/openclaw
# 8. 将虚拟环境的 bin 目录加入 PATH（永久生效）
echo 'export PATH="$HOME/openclaw-venv/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# 9. 验证 openclaw 命令
openclaw --help
# 正确输出应为 openclaw 的帮助信息，包含 start, stop, status 等子命令
实操记录：第 5 步
pip install "pydantic<2.0"是最关键的。如果不加引号，shell 会把<当作重定向符号，导致命令失败。第 9 步openclaw --help是第一个里程碑，看到帮助信息，说明环境搭建成功。
4.3 步骤三：配置并启动 OpenClaw（约 2 分钟）
# 1. 创建 OpenClaw 的配置目录
mkdir -p ~/.openclaw
# 2. 创建最小配置文件（请将 YOUR_API_KEY 替换为你自己的 OpenAI Key）
cat > ~/.openclaw/config.yaml << 'EOF'
llm:
provider: "openai"
api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
model: "gpt-4-turbo"
EOF
# 3. 启动 OpenClaw（前台运行，用于首次测试）
openclaw start --config ~/.openclaw/config.yaml
# 4. 观察输出（你会看到类似以下的日志）
# INFO: Started server process [12345]
# INFO: Waiting for application startup.
# INFO: Application startup complete.
# INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
实操记录：第 2 步的
cat > ... << 'EOF'是一个安全的写入文件方法，能避免引号和特殊字符被 shell 解析。第 4 步启动后，不要按Ctrl+C！让它在前台运行 30 秒，观察日志里是否有Application startup complete.。如果有，说明 OpenClaw 的核心服务已经跑起来了。此时，你可以用curl http://localhost:8000/health测试，应该返回{"status":"ok"}。
4.4 步骤四：配置 launchd 守护进程（约 4 分钟）
# 1. 创建 launchd 的 plist 文件
cat > ~/Library/LaunchAgents/com.openclaw.agent.plist << 'EOF'
<?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>com.openclaw.agent</string>
<key>ProgramArguments</key>
<array>
<string>/Users/$(whoami)/openclaw-venv/bin/python</string>
<string>-m</string>
<string>openclaw</string>
<string>start</string>
<string>--config</string>
<string>/Users/$(whoami)/.openclaw/config.yaml</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>/Users/$(whoami)/Library/Logs/openclaw.log</string>
<key>StandardErrorPath</key>
<string>/Users/$(whoami)/Library/Logs/openclaw-error.log</string>
<key>EnvironmentVariables</key>
<dict>
<key>PYTHONPATH</key>
<string>/Users/$(whoami)/openclaw-venv/lib/python3.11/site-packages</string>
</dict>
</dict>
</plist>
EOF
# 2. 加载并启动该服务
launchctl load ~/Library/LaunchAgents/com.openclaw.agent.plist
launchctl start com.openclaw.agent
# 3. 检查服务状态
launchctl list | grep openclaw
# 正确输出应为：- 0 com.openclaw.agent （其中 0 表示正常运行）
# 4. 查看日志（确认无报错）
tail -f ~/Library/Logs/openclaw.log
# 按 Ctrl+C 退出日志查看
实操记录：第 1 步的
$(whoami)是一个 shell 变量，会自动替换成你的用户名，确保路径绝对正确。第 2 步的launchctl load和launchctl start是两步，缺一不可。load是注册服务，start是立即运行。第 3 步launchctl list | grep openclaw是验证服务是否真的在运行，而不是“假装”在运行。
4.5 步骤五：配置 SSH 远程访问（约 6 分钟）
# 1. 启用远程登录（图形界面操作）
# 打开“系统设置” -> “网络” -> “共享”
# 勾选“远程登录”，并确保下方的“允许访问”里包含了你的用户账户
# 2. 编辑 sshd_config（命令行操作）
sudo nano /etc/ssh/sshd_config
# 3. 在 nano 编辑器中，找到并修改以下几行（用方向键移动，按 i 进入编辑模式）：
# Port 2222
# PubkeyAuthentication yes
# PasswordAuthentication no
# AllowTcpForwarding yes
# GatewayPorts clientspecified
# # 注释掉或删除 PermitRootLogin yes 这一行（如果存在）
# 4. 保存并退出 nano：按 Ctrl+O 回车保存，按 Ctrl+X 退出
# 5. 重启 SSH 服务
sudo launchctl unload /System/Library/LaunchDaemons/ssh.plist
sudo launchctl load -w /System/Library/LaunchDaemons/ssh.plist
# 6. 在本地电脑上，生成 SSH 密钥对（如果还没有）
ssh-keygen -t ed25519 -C "your_email@example.com"
# 7. 将公钥复制到 Mac mini
ssh-copy-id -p 2222 your_username@macmini_ip_address
# 8. 测试连接
ssh -p 2222 your_username@macmini_ip_address
# 成功后，你应该看到 Mac mini 的终端提示符
实操记录：第 1 步的“图形界面操作”是必须的，它会自动配置一些基础的
sshd_config选项。第 3 步的nano编辑，一定要仔细核对每一行，特别是Port和PasswordAuthentication。第 7 步ssh-copy-id会提示你输入密码，输入后，你的公钥就上传成功了。第 8 步ssh -p 2222 ...是最终验证，如果能成功登录，恭喜，你的 Mac mini 已经成为一台真正的远程服务器。
5. 常见问题与排查技巧实录：那些让我凌晨三点还在 Terminal 里挣扎的 Bug
在部署 OpenClaw 的过程中，我遇到了超过 20 个大大小小的问题。下面列出最典型、最高频的 5 个，并附上我当时的真实排查过程和最终解决方案。这些问题，很可能就是你下一步会遇到的。
5.1 问题一： brew install python@3.11 报错 Error: Failed to download resource "python@3.11" ，且 brew update 也失败
我的排查过程 ：
首先，我 ping github.com ，发现能通，排除了网络不通。然后 brew update ，卡在 Fetching origin ，持续 5 分钟。我意识到是 GitHub 的 git 请求被阻断了。我尝试 git clone https://github.com/Homebrew/homebrew-core ，果然失败。于是，我执行了 git config --get-regexp url ，发现之前配置的 insteadOf 规则并没有生效。原来， git config --global 是针对当前用户的，但 brew 在执行 update 时，可能会以不同的用户上下文运行，导致规则失效。
最终解决方案 ：
不是改 --global ，而是改 --system ，让规则对整个系统生效：
sudo git config --system url."https://mirrors.tuna.tsinghua.edu.cn/git/".insteadOf "https://github.com/"
sudo git config --system url."https://mirrors.tuna.tsinghua.edu.cn/git/".insteadOf "git://github.com/"
然后， brew update 速度立刻恢复正常。这个教训是： --global 不够“全局”， --system 才是真正的系统级。
5.2 问题二： openclaw start 启动后， curl http://localhost:8000/health 返回 curl: (7) Failed to connect to localhost port 8000: Connection refused
我的排查过程 ：
我首先 ps aux | grep openclaw ，发现进程确实存在。然后 netstat -an | grep 8000 ，发现没有任何进程监听 8000 端口。这很奇怪。我重新运行 openclaw start --verbose ，日志里出现了 ERROR: Could not bind to address 127.0.0.1:8000 。原来，端口被占用了。我用 lsof -i :8000 查看，发现是另一个 Python 进程在用。
最终解决方案 ：
在 config.yaml 中，显式指定一个不常用的端口：
webui:
host: "0.0.0.0"
port: 8081
然后 openclaw start --config ~/.openclaw/config.yaml 。 0.0.0.0 表示监听所有网络接口，而不仅仅是 127.0.0.1 ，这为后续的远程访问打下了基础。
5.3 问题三： launchctl start com.openclaw.agent 后， launchctl list | grep openclaw 显示状态码是 -1 ，而不是 0
我的排查过程 ： -1 表示进程启动失败。我查看日志 tail -f ~/Library/Logs/openclaw-error.log ，里面全是 ImportError: No module named 'openclaw' 。这说明 launchd 启动的 Python 环境，找不到 openclaw 这个包。我检查了 plist 文件里的 ProgramArguments ，发现路径是绝对路径，没错。问题出在 PYTHONPATH 。 launchd 的环境变量是隔离的，它不知道 ~/openclaw-venv/lib/python3.11/site-packages 这个路径。
最终解决方案 ：
在 plist 文件的 <key>EnvironmentVariables</key> 字典里，不仅添加 PYTHONPATH ，还要添加 PATH ，确保 python3.11 命令也能被找到：
<key>EnvironmentVariables</key>
<dict>
<key>PYTHONPATH</key>
<string>/Users/yourusername/openclaw-venv/lib/python3.11/site-packages</string>
<key>PATH</key>
<string>/Users/yourusername/openclaw-venv/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>
然后 launchctl unload 再 load ，问题解决。
5.4 问题四：SSH 连接成功，但 ssh -p 2222 -L 8080:localhost:8081 user@ip 后， http://localhost:8080 无法访问
我的排查过程 ：
我确认了 OpenClaw 的 webui.port 是 8081 ，也确认了 ssh 命令没有报错。我尝试在 Mac mini 上 curl http://localhost:8081 ，可以访问。问题出在 ssh 的端口转发配置上。 ssh -L 的语法是 local_port:remote_host:remote_port ，其中 remote_host 如果写 localhost ，它指的是 Mac mini 本机。但 OpenClaw 的 webui.host 是 0.0.0.0 ，所以 localhost 是对的。那问题在哪？我执行 ssh -v -p 2222 -L 8080:localhost:8081 user@ip ，开启了详细日志，发现日志里有 debug1: Local forwarding listening on 127.0.0.1 port 8080 。哦！它只监听了 127.0.0.1 ，也就是只允许本机访问。而我想从其他设备访问，就需要它监听 0.0.0.0 。
最终解决方案 ：
在 ssh 命令里，加上 -o GatewayPorts=yes 参数，并且在 sshd_config 中确保 GatewayPorts clientspecified 已启用：
ssh -p 2222 -o GatewayPorts=yes -L *:8080:localhost:8081 user@ip
* 表示监听所有接口，这样 http://macmini-ip:8080 就可以从局域网内的任何设备访问了。
5.5 问题五：OpenClaw 启动后，
Agent 垂直技术社区，欢迎活跃、内容共建。
更多推荐
7
0- 0
已为社区贡献13条内容
所有评论(0)