Mac OpenClaw 从零安装配置完全指南

适用于 macOS 12+ (Monterey 及更高版本)

一、OpenClaw 是什么？

OpenClaw 是一个开源的 AI 助手框架，可以连接多种通讯渠道（Telegram、Discord、WhatsApp、微信、企业微信、飞书等）和大语言模型，让你通过这些渠道直接与 AI 对话。

二、安装前准备

2.1 环境要求

操作系统: macOS 12.0+
内存: 推荐 4GB+
存储: 至少 2GB 可用空间
网络: 需要访问国际网络（用于模型 API 和部分渠道）

2.2 安装 Homebrew（如果没有）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2.3 安装 Node.js

OpenClaw 基于 Node.js 运行：

brew install node
node --version  # 确认版本 >= 18

三、安装 OpenClaw

3.1 全局安装

npm install -g openclaw

3.2 验证安装

openclaw --version
# 输出类似: OpenClaw 2026.3.13

3.3 初始化配置

openclaw setup

这会引导你创建基础配置文件。如果你想手动配置，请继续往下看。

四、配置文件详解

4.1 配置文件位置

配置文件位于 ~/.openclaw/openclaw.json（~ 代表你的 home 目录）。

可以用以下命令查看：

openclaw config file

4.2 完整配置文件结构

{
  "meta": {
    "lastTouchedVersion": "2026.3.13",
    "lastTouchedAt": "2026-03-17T07:11:40.493Z"
  },
  "browser": { ... },
  "models": { ... },
  "agents": { ... },
  "tools": { ... },
  "commands": { ... },
  "channels": { ... },
  "gateway": { ... },
  "plugins": { ... }
}

五、各配置项详细说明

5.1 meta — 元信息

"meta": {
  "lastTouchedVersion": "2026.3.13",
  "lastTouchedAt": "2026-03-17T07:11:40.493Z"
}

字段	说明
`lastTouchedVersion`	最后一次配置的 OpenClaw 版本
`lastTouchedAt`	最后修改时间（ISO 8601 格式）

作用: 用于记录配置文件何时被修改，辅助版本追踪。

5.2 browser — 浏览器设置

"browser": {
  "headless": true,
  "extraArgs": [
    "--window-size=1920,1080",
    "--force-device-scale-factor=1"
  ]
}

字段	说明	可选值
`headless`	是否使用无头模式（不显示浏览器窗口）	`true` / `false`
`extraArgs`	额外的 Chrome/Chromium 启动参数	字符串数组

常见 extraArgs 参数:

--window-size=1920,1080 — 设置浏览器窗口大小
--disable-gpu — 禁用 GPU 加速（某些 Mac 上需要）
--no-sandbox — 禁用沙箱（某些环境需要）

作用: OpenClaw 内置浏览器用于自动化操作，如网页登录、截图等。

5.3 models — 大模型配置（重点！）

这是最核心的配置之一，决定了你的 AI 使用什么模型。

5.3.1 基本结构

"models": {
  "providers": {
    "provider_name": {
      "baseUrl": "https://api.xxx.com",
      "apiKey": "your-api-key",
      "api": "openai-completions",
      "models": [
        {
          "id": "model-id",
          "name": "模型显示名称",
          ...
        }
      ]
    }
  }
}

5.3.2 字段说明

字段	必填	说明
`providers`	✅	模型提供者字典，可以配置多个 provider
`baseUrl`	✅	API 端点 URL
`apiKey`	✅	API 密钥
`api`	✅	API 格式类型，常用值: `openai-completions`
`models`	✅	模型列表

每个模型字段:

字段	说明
`id`	模型 ID（API 调用时使用）
`name`	显示名称
`api`	可选，覆盖 provider 级别的 api
`reasoning`	是否启用推理模式（如 DeepSeek R1）
`input`	输入类型，`["text"]` 或 `["text", "image"]`
`cost`	价格设置（输入/输出/缓存读写）
`contextWindow`	上下文窗口大小（token 数）
`maxTokens`	最大输出 token 数

六、以智谱 AI 为例：配置大模型

6.1 智谱 AI 简介

智谱 AI (Zhipu AI) 是清华大学技术团队出品的国产大模型厂商，提供 GLM 系列模型。

官网: https://open.bigmodel.cn

6.2 获取智谱 API Key

步骤 1: 注册账号

打开 https://open.bigmodel.cn
点击「注册/登录」，使用手机号或邮箱注册
完成实名认证（个人开发者免费）

步骤 2: 创建 API Key

登录后进入「控制台」
点击左侧「API 密钥」
点击「创建密钥」
复制生成的 API Key（只会显示一次，请妥善保存！）

⚠️ 注意: API Key 泄露风险 — 不要提交到公开仓库！

6.3 在 OpenClaw 中配置智谱

方式一：命令行配置

# 设置智谱的 baseUrl
openclaw config set models.providers.zhipu.baseUrl "https://open.bigmodel.cn/api/paas/v4"

# 设置智谱的 API Key
openclaw config set models.providers.zhipu.apiKey "你的智谱APIKey"

# 设置 API 格式
openclaw config set models.providers.zhipu.api "openai-completions"

# 添加模型
openclaw config set models.providers.zhipu.models '[{"id":"glm-4.5-air","name":"智谱 GLM-4.5-air","reasoning":false,"input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":128000,"maxTokens":8192}]'

方式二：直接编辑配置文件

打开 ~/.openclaw/openclaw.json，在 models.providers 下添加：

"models": {
  "providers": {
    "zhipu": {
      "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
      "apiKey": "你的智谱APIKey",
      "api": "openai-completions",
      "models": [
        {
          "id": "glm-4.5-air",
          "name": "智谱 GLM-4.5-air",
          "api": "openai-completions",
          "reasoning": false,
          "input": ["text"],
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          },
          "contextWindow": 128000,
          "maxTokens": 8192
        },
        {
          "id": "glm-4-flash",
          "name": "智谱 GLM-4-Flash",
          "api": "openai-completions",
          "reasoning": false,
          "input": ["text"],
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          },
          "contextWindow": 128000,
          "maxTokens": 8192
        }
      ]
    }
  }
}

6.4 设置默认模型

openclaw models set default zhipu/glm-4.5-air

或者在 agents 配置中指定：

"agents": {
  "defaults": {
    "model": {
      "primary": "zhipu/glm-4.5-air"
    }
  }
}

七、agents — Agent 行为配置

"agents": {
  "defaults": {
    "model": {
      "primary": "default/MiniMax-M2.1"
    },
    "imageModel": {
      "primary": "default/MiniMax-M2.1"
    },
    "workspace": "/root/.openclaw/workspace",
    "compaction": {
      "mode": "safeguard"
    },
    "sandbox": {
      "mode": "off"
    }
  }
}

字段	说明
`model.primary`	默认使用的文本模型
`imageModel.primary`	默认使用的图像模型
`workspace`	工作目录路径
`compaction.mode`	上下文压缩模式: `safeguard`（安全模式）/ `aggressive`
`sandbox.mode`	沙箱模式: `off` / `on` / `require`

八、tools — 工具权限配置

"tools": {
  "profile": "full",
  "sessions": {
    "visibility": "all"
  },
  "fs": {
    "workspaceOnly": true
  }
}

字段	说明
`profile`	工具配置集: `full`（完整）/ `minimal`（最小）
`sessions.visibility`	会话可见性: `all` / `self`
`fs.workspaceOnly`	文件系统访问是否限制在工作目录

九、commands — 命令行为配置

"commands": {
  "native": "auto",
  "nativeSkills": "auto",
  "restart": true,
  "ownerDisplay": "raw"
}

字段	说明
`native`	本地命令执行: `auto` / `on` / `off`
`nativeSkills`	本地技能执行
`restart`	Gateway 重启后是否自动恢复
`ownerDisplay`	所有者显示模式

十、gateway — 网关配置

"gateway": {
  "port": 18799,
  "mode": "local",
  "bind": "lan",
  "controlUi": {
    "allowedOrigins": ["*"],
    "allowInsecureAuth": true,
    "dangerouslyDisableDeviceAuth": true
  },
  "auth": {
    "mode": "token",
    "token": "zp114211"
  }
}

字段	说明
`port`	Gateway 监听端口
`mode`	运行模式: `local`（本地）/ `cloud`
`bind`	绑定地址: `lan`（局域网）/ `localhost`
`controlUi.*`	Web 控制面板设置
`auth.mode`	认证模式: `token` / `device`
`auth.token`	访问令牌

十一、channels — 通讯渠道配置

这里配置你希望连接的消息渠道。常见渠道：

11.1 Telegram

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "你的BotToken"
  }
}

获取 BotToken: @BotFather

11.2 Discord

"channels": {
  "discord": {
    "enabled": true,
    "botToken": "你的BotToken"
  }
}

11.3 配置渠道命令

# 登录 Telegram
openclaw channels login telegram

# 登录 Discord  
openclaw channels login discord

十二、plugins — 插件配置

"plugins": {
  "enabled": true,
  "allow": [
    "dingtalk-connector",
    "openclaw-qqbot",
    "wecom-openclaw-plugin",
    "feishu"
  ],
  "entries": {
    "dingtalk-connector": {
      "enabled": true
    },
    ...
  }
}

字段	说明
`enabled`	是否启用插件系统
`allow`	允许加载的插件列表
`entries`	各插件的具体配置

十三、启动 Gateway

配置完成后，启动 Gateway：

# 前台运行
openclaw gateway

# 或后台运行
openclaw gateway start

查看状态：

openclaw status

十四、访问 Control UI

Gateway 启动后，可以通过浏览器访问控制面板：

http://localhost:18799  (或你的局域网 IP:18799)

登录令牌（token）: 在配置文件的 gateway.auth.token 中设置。

十五、验证配置

检查模型是否配置成功：

openclaw models list

测试模型调用：

openclaw models status

十六、常见问题

Q1: 配置文件在哪？

A: ~/.openclaw/openclaw.json

Q2: 如何重置配置？

A: openclaw reset，然后重新运行 openclaw setup

Q3: API Key 安全吗？

A: OpenClaw 本地运行，API Key 存储在本地配置文件中，不要提交到 Git！

Q4: 模型连接失败怎么办？

A: 检查：

API Key 是否正确
baseUrl 是否正确
网络是否能访问（科学上网）
账户是否余额充足

Q5: 如何查看日志？

A: openclaw logs

十七、推荐模型清单

提供商	模型 ID	特点
智谱	glm-4.5-air	免费额度多，性价比高
智谱	glm-4-flash	速度快，便宜
MiniMax	MiniMax-M2.1	长上下文，适合复杂任务
DeepSeek	deepseek-chat	开源性价比高
OpenAI	gpt-4o	通用能力强

十八、总结

安装: npm install -g openclaw
配置模型: 在 models.providers 下添加智谱配置
配置渠道: 在 channels 下添加 Telegram/Discord 等
启动: openclaw gateway
访问: 浏览器打开 Control UI

有任何问题，欢迎随时提问！🐕

在MacBook上安装OpenClaw并接入智谱大模型完整指南