macOS OpenClaw 指南

yeye19891224

240人浏览 · 2026-05-16 13:49:19

yeye19891224 · 2026-05-16 13:49:19 发布

作为一名在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"
    }
  }
}