macOS OpenClaw 指南
本文详细介绍了在M系列Mac上配置OpenClaw AI框架的全流程指南。从安装前的系统检查到一键脚本安装，重点讲解了初始化配置、核心配置文件解析和模型管理方法。针对开发者常见问题，如文件修改失败、模型切换报错等，提供了具体解决方案和最佳实践建议。文章还分享了性能优化技巧和故障排查流程，帮助用户快速掌握OpenClaw的使用要点，充分发挥其灵活性和扩展性优势，构建高效的AI助手工作流。
作为一名在M系列Mac上深度使用OpenClaw（俗称“小龙虾”）的开发者，我曾经历过从安装到配置的各种坑，尤其是文件修改时“显示成功却内容未变”的诡异问题。这篇博客将基于官方文档与实战经验，带你完成从零到一的OpenClaw全流程配置，包括安装、基础配置、模型管理、文件操作与最佳实践，帮你避开99%的常见问题。
一、OpenClaw是什么？为什么选择它？
OpenClaw是一款开源的AI Agent框架，让你能快速构建、部署和管理自定义AI助手，支持接入OpenAI、Anthropic、火山引擎等主流大模型，具备强大的工具调用能力、记忆系统和多渠道接入特性。它特别适合：
- 开发者：快速构建AI驱动的自动化工作流
- 内容创作者：提升创作效率，实现多模型协作
- 企业用户：构建定制化AI助手，保护数据隐私
- AI爱好者：探索大模型应用边界，学习Agent技术
二、安装前准备：Mac环境检查与配置
1. 系统要求（官方推荐）
|
项目 |
最低要求 |
推荐配置 |
|
操作系统 |
macOS 12.0+ (Monterey) |
macOS 14.0+ (Sonoma) |
|
芯片 |
Intel / Apple Silicon |
Apple Silicon M2+ |
|
内存 |
8GB |
16GB+ |
|
存储空间 |
10GB可用 |
20GB+可用 |
|
Node.js |
v20.x |
v22.x LTS |
2. 终端准备（关键步骤）
在开始安装前，先开启终端的完全磁盘访问权限（后续文件操作的基础）：
- 打开「系统设置」→「隐私与安全性」→「完全磁盘访问权限」
- 点击左下角锁图标，输入密码解锁
- 点击「+」号，添加你使用的终端（终端.app/iTerm2）
- 完全退出终端，重新打开，否则权限不生效
三、Mac安装指南
一键脚本安装
这是官方文档最推荐的安装方式，自动检测并配置环境：
# 执行官方一键安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash脚本会自动完成：
- 检测操作系统和Node.js环境
- 安装或更新Node.js（确保≥v22）
- 全局安装OpenClaw最新版
- 启动初始化向导（onboard）
安装完成后，验证版本：
openclaw --version
# 输出示例：openclaw/2026.3.12 darwin-arm64 node-v22.2.0卸载
openclaw uninstall --all --yes --non-interactive
npm rm -g openclaw
- 停止网关服务
- 卸载 LaunchAgent 自启
- 删除
~/.openclaw全部配置 / 数据 - 移除全局 CLI
卸载服务
openclaw gateway uninstall 2>/dev/null
# 删除启动项文件
rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist
rm -f ~/Library/LaunchAgents/com.openclaw.gateway.plist
rm -f ~/Library/LaunchAgents/bot.molt.gateway.plist
# 主目录（必删）
rm -rf ~/.openclaw
# 旧版残留（可选但建议删）
rm -rf ~/.clawdbot
rm -rf ~/.moltbot
# 清理可能的二进制残留
rm -f ~/.local/bin/openclaw
rm -f /usr/local/bin/openclaw四、初始化配置：onboard向导详解
安装完成后，执行openclaw onboard启动官方初始化向导，这是配置OpenClaw的最快方式：
1. 向导流程（QuickStart模式推荐）
1. 选择模式：QuickStart（新手）/ Advanced（高级）
2. 配置AI模型：选择提供商（OpenAI/Anthropic/火山引擎等）
3. 输入API密钥：安全存储，支持环境变量引用
4. 配置聊天渠道：选择Control Center（Web UI）/ Slack等
5. 配置Skills：启用工具（文件操作/网络浏览/代码执行等）
6. 完成配置，启动Gateway服务2. 关键配置说明
- 模型选择：新手推荐从火山引擎或OpenAI开始，国内网络更稳定
- Skills启用：必须明确启用需要的工具，OpenClaw默认关闭所有工具权限
- Gateway服务：本地部署时选择默认端口，确保防火墙允许访问
五、核心配置：openclaw.json5详解
OpenClaw的主配置文件位于~/.openclaw/openclaw.json5，采用JSON5格式（支持注释和尾逗号）。这是自定义OpenClaw行为的核心入口。
1. 基础配置结构
{
"agents": {
"defaults": {
"workspace": "/Users/zwy/.openclaw/workspace",
"models": {
"deepseek/deepseek-chat": {
"alias": "DeepSeek"
},
"volcengine/doubao-seed-1-8-251228": {},
"volcengine/glm-4-7-251222": {},
"volcengine/kimi-k2-5-260127": {},
"volcengine/deepseek-v3-2-251201": {},
"volcengine/doubao-seed-2-0-pro-260215": {}
},
"model": {
"primary": "volcengine/doubao-seed-2-0-pro-260215",
"fallbacks": [
"deepseek/deepseek-chat",
"volcengine/doubao-seed-1-8-251228",
"volcengine/glm-4-7-251222",
"volcengine/kimi-k2-5-260127",
"volcengine/deepseek-v3-2-251201"
]
}
}
},
"gateway": {
"mode": "local",
"auth": {
"mode": "token",
"token": "xxxxxxxxxxxxxx"
},
"port": 18789,
"bind": "loopback",
"tailscale": {
"mode": "off",
"resetOnExit": false
},
"controlUi": {
"allowInsecureAuth": true
},
"nodes": {
"denyCommands": [
"camera.snap",
"camera.clip",
"screen.record",
"contacts.add",
"calendar.add",
"reminders.add",
"sms.send",
"sms.search"
]
}
},
"session": {
"dmScope": "per-channel-peer"
},
"tools": {
"profile": "coding"
},
"models": {
"mode": "merge",
"providers": {
"deepseek": {
"baseUrl": "https://api.deepseek.com",
"api": "openai-completions",
"models": [
{
"id": "deepseek-chat",
"name": "DeepSeek Chat",
"reasoning": false,
"input": [
"text"
],
"contextWindow": 131072,
"maxTokens": 8192,
"cost": {
"input": 0.28,
"output": 0.42,
"cacheRead": 0.028,
"cacheWrite": 0
},
"compat": {
"supportsUsageInStreaming": true
},
"api": "openai-completions"
},
{
"id": "deepseek-reasoner",
"name": "DeepSeek Reasoner",
"reasoning": true,
"input": [
"text"
],
"contextWindow": 131072,
"maxTokens": 65536,
"cost": {
"input": 0.28,
"output": 0.42,
"cacheRead": 0.028,
"cacheWrite": 0
},
"compat": {
"supportsUsageInStreaming": true
},
"api": "openai-completions"
}
]
}
}
},
"auth": {
"profiles": {
"deepseek:default": {
"provider": "deepseek",
"mode": "api_key"
},
"volcengine:default": {
"provider": "volcengine",
"mode": "api_key"
}
}
},
"hooks": {
"internal": {
"enabled": true,
"entries": {
"command-logger": {
"enabled": true
}
}
}
},
"wizard": {
"lastRunAt": "2026-04-13T15:54:47.796Z",
"lastRunVersion": "2026.4.12",
"lastRunCommand": "configure",
"lastRunMode": "local"
},
"meta": {
"lastTouchedVersion": "2026.4.12",
"lastTouchedAt": "2026-04-13T15:54:47.905Z"
},
"plugins": {
"entries": {
"deepseek": {
"enabled": true
},
"volcengine": {
"enabled": true
}
}
}
}
2. 配置生效方法
修改配置后，必须重启Gateway服务使变更生效：
openclaw gateway stop && sleep 3 && openclaw gateway start六、模型管理：models.json配置与修改
models.json是Agent专属的模型配置文件，位于~/.openclaw/agents/main/agent/models.json，用于定义特定Agent的模型和提供商信息。这是解决「切换火山引擎模型报错」的关键文件。
1. 官方规范格式
{
"models": {
"volcengine/glm-4-7-251222": {
"alias": "GLM-4",
"provider": "volcengine",
"parameters": {
"temperature": 0.7,
"max_tokens": 4096
}
}
},
"providers": {
"volcengine": {
"apiKey": "sk-xxxxxxxxxxxxxxxx",
"endpoint": "https://maas-api.volcengine.com"
}
}
}七、最佳实践：OpenClaw开发黄金法则
1. 文件操作安全三原则
- 备份先行：任何修改前必须备份原文件，防止配置损坏
- 路径绝对：始终使用完整绝对路径，禁止相对路径
- 分步验证：每步操作后验证结果，特别是JSON格式验证
2. 模型管理最佳实践
- 分层配置：全局配置通用提供商，agent配置专属模型
- 环境变量存储密钥：避免明文存储API密钥，使用
${VAR_NAME}引用 - 故障切换：配置fallbacks模型，提升系统稳定性
3. 性能优化建议
- 会话压缩：启用
compaction配置，减少Token消耗 - 模型选择：根据任务复杂度选择合适模型（轻量任务用GLM-4-7B，复杂任务用GPT-4o）
- 工具权限最小化：只启用必要工具，降低安全风险
4. 常见问题排查流程
- 文件写入失败：检查终端完全磁盘访问权限→检查openclaw.json5的fs配置→使用Shell命令法
- 模型切换报错：检查models.json格式→验证API密钥→确认网络连接→查看Gateway日志
- Agent无响应：检查Gateway服务状态→验证模型配置→检查工具权限→重启Gateway
九、总结与下一步
OpenClaw的强大之处在于其灵活性和可扩展性，但这也带来了一定的学习曲线。通过本文的全流程指南，你应该已经掌握了从安装到精通的核心技能，能够解决99%的常见问题，特别是文件操作和模型切换的难题。
下一步建议：
- 探索OpenClaw的Skill开发，扩展Agent能力
- 配置多模型协作，实现不同任务的模型自动选择
- 学习AGENTS.md编写，定义结构化的Agent行为
- 接入Slack/微信等渠道，实现多端AI助手访问
需要我根据你的具体路径和模型信息，生成一份可直接复制的models.json修改命令吗？只需告诉我你的用户目录（如/Users/xxx）和火山引擎API密钥即可。
有“AI”的1024 = 2048，欢迎大家加入2048 AI社区
更多推荐
8
0- 0
已为社区贡献13条内容
所有评论(0)