一、部署流程
1. 环境准备
确认 Node.js 版本不低于 v18，推荐 v20 LTS。macOS 用户需确保已安装 Xcode Command Line Tools。
2. 全局安装
npm install -g openclaw
openclaw config init
安装完成后，配置文件生成于 ~/.openclaw/openclaw.json，按需编辑即可。
3. Playwright 浏览器环境
export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright
npx playwright install
若暂时不需要浏览器功能，可在配置中将 browser.enabled 设为 false。
4. 系统权限（macOS）
在"系统设置 > 隐私与安全性"中完成以下授权：
完全磁盘访问权限：添加终端应用
辅助功能：供自动化控制使用
自动化：供 iMessage 技能控制 Messages.app 使用
5. 服务启动
openclaw gateway start
openclaw status
openclaw agents list二、踩坑记录
1. Playwright 网络超时
国内环境下 Chromium 和 WebKit 下载经常中断，设置镜像源后重试。
2. 配置文件格式问题
使用 Tab 缩进（必须使用空格）
models 数组不能为空
环境变量需先 export 再使用
${VAR}语法
3. 端口占用
默认 18789 端口若被占用，修改配置中的 gateway.port 后重启服务。
4. iMessage 通道配置问题
执行发送命令时报错 "channel not connected" 的常见原因：
目标地址格式错误：需使用
imessage:+86138xxxxxxxx格式，仅使用手机号而不加imessage:前缀会导致路由失败。联系人与地址簿不匹配：目标号码若未保存在本地通讯录，或保存格式与发送时不一致，发送会失败。
消息格式配置：iMessage 不支持 Markdown，需设置为纯文本格式，否则内容可能包含转义字符。
5. iMessage 数据库锁定
读取 ~/Library/Messages/chat.db 时，若 Messages.app 正在运行会报 "database is locked"。需完全退出 Messages（Command+Q）或执行 killall Messages 后再使用。
6. Apple ID 状态异常
若 Apple ID 长时间未登录或双因素认证过期，Messages.app 会要求重新验证。此时自动化调用会超时，需手动在 GUI 中完成认证流程。
7. 配置热重载
修改 openclaw.json 后必须执行 openclaw gateway restart 才能生效。validate 命令仅检查语法，通过不代表配置已加载。
8. 多用户隔离问题
当前 OpenClaw 架构下，所有用户共享同一份 MEMORY.md 和 memory/ 目录下的日志文件。即使配置多个 session 或 agent，长期记忆文件仍是全局共享状态。目前可行的方案是为每个用户单独部署 OpenClaw 实例，各自维护独立的 ~/.openclaw/ 目录。
9. 浏览器自动化问题
Chrome 扩展连接失败：使用
profile: "chrome"时需在浏览器中手动点击 OpenClaw 扩展图标建立连接，扩展徽章显示为 ON 后方可使用。Playwright 版本不兼容：系统已安装的其他版本 Playwright 可能与 OpenClaw 依赖冲突，表现为浏览器启动后立即崩溃。
无头模式限制：部分网站检测无头浏览器并拒绝访问，需关闭 headless 模式或添加反检测参数。
浏览器实例泄漏：异常退出可能导致 Chromium 进程残留，占用内存和端口，需手动清理或重启网关。
10. 模型添加与识别问题
默认模型不匹配：
defaultModel指定的模型 ID 必须在对应models数组中存在定义，否则服务启动时报 "model not found"。必填字段缺失：
models数组内的对象必须包含id、name、maxTokens字段。缺少maxTokens可能导致请求截断，缺少id则无法被引用。本地模型连接配置：使用 Ollama 等本地模型时，
baseUrl需指向正确的 API 端点（通常为http://localhost:11434或兼容的/v1路径），且type字段需与接口协议匹配。能力声明缺失：未显式设置
supportsStreaming: true或supportsVision: true等标志，会导致流式输出或多模态功能被禁用，即使模型本身支持。模型数组为空：
providers下models数组若为空，该 provider 将被视为无效，无法执行任何调用。