安装 OpenClaw CLI 并配置 Nylas 插件

本指南涵盖的内容

OpenClaw 是一个开源 CLI 框架，用于构建 AI 驱动的消息助手。它通过插件系统连接邮件、WhatsApp、iMessage 等渠道，目前在 npm 上有超过 40 个社区维护的插件包。你只需全局安装 CLI，添加所需集成的插件，然后通过 JSON 配置文件进行配置。本指南的目标是完成 OpenClaw 的安装，并准备好运行 Nylas 邮件、日历和联系人插件。

Nylas 用户快速上手

在已安装 Node.js 的机器上，只需 7 个步骤、不到 3 分钟即可在 OpenClaw 中运行 Nylas。这些步骤包括安装 CLI、添加 Nylas 插件、为 agent 会话授权，以及通过邮箱账户测试连接。

以下每个步骤运行一条命令。config set 调用会写入 OpenClaw 的 JSON 配置文件 ~/.openclaw/config.json，gateway 重启后会加载这些更改，且不会丢失已有会话。

如果你还没有 Nylas API 密钥，请在步骤 5 之前 创建 Nylas 账户，然后将 API 密钥复制到 OpenClaw 插件配置中。

# 1. 安装 OpenClaw
npm install -g openclaw

# 2. 验证二进制文件是否在 PATH 中
openclaw --version

# 3. 安装 Nylas 插件
openclaw plugins install @nylas/openclaw-nylas-plugin

# 4. 信任插件并将其工具暴露给 agent 会话
openclaw config set 'plugins.allow' '["nylas"]'
openclaw config set 'tools.alsoAllow' '["nylas"]'

# 5. 配置 Nylas API 密钥
openclaw config set 'plugins.entries.nylas.config.apiKey' 'YOUR_NYLAS_API_KEY'

# 6. 重启 gateway 以重新加载插件配置
openclaw gateway restart

# 7. 验证集成
openclaw plugins list
openclaw run "List my connected email accounts" --plugin nylas

后续章节将详细说明每个安装步骤，介绍常见环境下的 PATH 修复方法，并针对 macOS/Linux 和 Windows 提供故障排除指南。

OpenClaw 的 npm 包名是什么？

OpenClaw CLI 以非作用域包名 openclaw 发布在 npm 上。核心 CLI 二进制文件没有 @openclaw/ 作用域前缀。插件使用不同的命名约定，采用作用域名称如 @nylas/openclaw-nylas-plugin，但 CLI 本身从顶级 openclaw 包安装。该包自 2025 年初上线 npm，截至 2026 年 5 月，周下载量超过 12,000 次。

运行 npm install -g openclaw 会将 openclaw 二进制文件放置在 npm 全局 bin 目录中，通常位于 $(npm config get prefix)/bin/。

# npm 包名为 "openclaw"
npm install -g openclaw

安装 OpenClaw CLI

安装 OpenClaw CLI 需要 Node.js 22.12.0 或更高版本，以及一条 npm install -g 命令。全局安装会将 openclaw 二进制文件添加到系统 PATH 中，使其在每个终端会话中都可用。在典型宽带连接下，完整安装在 60 秒内完成，下载约 45 MB 的依赖项。

首先检查 Node.js 版本。OpenClaw 使用原生 ES 模块和 Node.js 内置测试运行器，两者都要求 Node.js 22.12.0 作为最低版本。旧版本启动时会报语法错误。

# 检查 Node.js 版本（必须为 22.12.0+）
node --version

# 全局安装 OpenClaw CLI
npm install -g openclaw

# 验证安装
openclaw --version

如果看到版本号，说明安装成功。出现 "command not found" 错误表示 npm 全局 bin 目录不在 PATH 中 — 后续的 PATH 修复故障排除章节会直接解决这个问题。

如果你使用 nvm 管理 Node.js，请确保在运行安装前将活动版本切换到 22.12.0 或更高：

# 使用 nvm 切换到 Node.js 22
nvm install 22
nvm use 22

# 然后安装 openclaw
npm install -g openclaw

系统要求是什么？

OpenClaw 可在 macOS（Intel 和 Apple Silicon）、Linux（x64 和 arm64）以及 Windows 10 或更高版本上运行。唯一的硬性依赖是 Node.js 22.12.0+，它本身需要约 80 MB 磁盘空间。OpenClaw 在此基础上额外增加约 45 MB 的依赖项。由于 CLI 是纯 JavaScript，没有原生插件，因此不需要本地编译工具链。

安装 OpenClaw 插件

OpenClaw 插件是 npm 包，用于向 CLI 注册新的工具、集成和命令。内置的插件管理器负责下载、版本解析和工具注册。截至 2026 年 5 月，OpenClaw 生态系统已有超过 40 个已发布的插件，涵盖邮件、消息、CRM 和开发者工具。每个插件安装仅需几秒钟，gateway 重启后即可激活。

openclaw plugins 子命令管理插件的完整生命周期：安装、列表、更新和卸载。安装插件或更改插件配置后，运行 openclaw gateway restart 以让 gateway 进程加载新的插件状态。

# 安装插件
openclaw plugins install <package-name>

# 示例：安装 Nylas 邮件、日历和联系人插件
openclaw plugins install @nylas/openclaw-nylas-plugin

# 验证是否已安装
openclaw plugins list

# 重启 gateway 以加载新插件
openclaw gateway restart

插件管理命令参考

列出已安装的插件

openclaw plugins list 命令会列出每个已安装的插件及其版本号和启用/停用状态。输出为三列表格，显示 NAME、VERSION 和 STATUS。添加 --json 标志可生成机器可读的 JSON 输出，方便通过 jq 管道处理或在脚本中解析 — 适用于 CI 中在部署 agent 前验证所需插件集的场景。

插件显示 "active" 表示其工具已加载并可用于 agent 会话。状态为 "inactive" 表示插件已安装但在配置中被禁用，或在上次 gateway 启动时初始化失败。

# 列出所有已安装的插件
openclaw plugins list

# 示例输出：
# NAME                              VERSION  STATUS
# @nylas/openclaw-nylas-plugin      1.2.0    active
# openclaw-whatsapp-bridge          0.9.1    active
# openclaw-imsg                     0.8.3    active

# JSON 格式输出，适合脚本处理
openclaw plugins list --json

卸载插件

openclaw plugins uninstall 命令会一步完成插件移除和所有工具的注销。与安装不同，卸载无需重启 gateway 即可立即生效。插件的 npm 包会从本地 ~/.openclaw/plugins/ 目录中删除，释放其占用的磁盘空间 — 每个插件通常为 5-15 MB，取决于依赖项。

请传入安装时使用的完整 npm 包名。之后运行 openclaw plugins list 确认插件已不再列出。

# 卸载插件
openclaw plugins uninstall @nylas/openclaw-nylas-plugin

# 验证是否已移除
openclaw plugins list

在 Windows 上安装 OpenClaw

OpenClaw 通过 PowerShell 5.1+ 在 Windows 10 及更高版本上原生运行。Windows 的安装路径与 macOS 和 Linux 相同：安装 Node.js 22.12.0 或更高版本，然后运行 npm install -g openclaw。根据 Node.js Foundation 的说明，nodejs.org 的 Windows .msi 安装程序会自动将 Node.js 和 npm 添加到系统 PATH，因此大多数情况下无需手动编辑 PATH 即可使用 OpenClaw。

# Windows PowerShell 安装步骤
# 1. 从 https://nodejs.org 安装 Node.js 22+（使用 LTS 安装程序）

# 2. 打开 PowerShell 并验证 Node.js
node --version

# 3. 全局安装 OpenClaw
npm install -g openclaw

# 4. 验证
openclaw --version

# 5. 如果遇到 EACCES 或权限错误，请以管理员身份运行 PowerShell：
# 右键点击 PowerShell → "以管理员身份运行"
# 然后重新执行：npm install -g openclaw

在 Windows 上，OpenClaw 的配置目录为 %USERPROFILE%\.openclaw\。插件和配置文件存放在该目录中。请确保 PATH 包含 npm 全局 bin 目录，Node.js 安装程序通常会自动设置。

可选：iMessage CLI 路径配置

openclaw-imsg 插件将 OpenClaw 连接到 macOS 上的 iMessage。由于 macOS 的应用沙箱机制限制了二进制文件的存放位置，该插件无法自动检测 iMessage CLI 二进制文件 — 你需要通过 openclaw config set imsg.cliPath 手动设置路径。这个额外步骤大约需要 30 秒，且每台机器只需执行一次。

iMessage CLI 二进制文件 (imsg-cli) 是一个独立的开源工具。如果你通过 Homebrew 安装，二进制文件位于 $(brew --prefix)/bin/ 下。手动安装通常放在 /usr/local/bin/imsg-cli。

# 安装 iMessage 插件
openclaw plugins install openclaw-imsg

# 设置 iMessage CLI 二进制文件路径
openclaw config set imsg.cliPath "/usr/local/bin/imsg-cli"

# 如果通过 Homebrew 安装了 imsg-cli：
openclaw config set imsg.cliPath "$(brew --prefix)/bin/imsg-cli"

# 验证路径已设置
openclaw config get imsg.cliPath

# 测试 iMessage 连接
openclaw imsg status

imsg.cliPath 配置值必须指向实际的二进制文件。如果插件报 "command not found" 错误，说明路径错误或该位置不存在二进制文件。使用 which imsg-cli 查找系统上的正确路径。

可选：WhatsApp 集成

openclaw-whatsapp-bridge 插件将 OpenClaw 连接到 WhatsApp Business API。根据 Meta 2025 年财报，WhatsApp 拥有超过 20 亿月活跃用户。该插件通过 Meta Cloud API 处理消息发送、接收和 Webhook 注册。你需要一个 WhatsApp Business 账户和来自 Meta 开发者控制台的访问令牌。准备好凭据后，配置大约需要 5 分钟。

需要设置三个配置值：访问令牌、电话号码 ID 和商业账户 ID。这三项均可在 Meta Developer Portal 的 WhatsApp 应用设置中找到。

# 安装 WhatsApp bridge 插件
openclaw plugins install openclaw-whatsapp-bridge

# 配置 WhatsApp Business 凭据
openclaw config set whatsapp.accessToken "YOUR_ACCESS_TOKEN"
openclaw config set whatsapp.phoneNumberId "YOUR_PHONE_NUMBER_ID"
openclaw config set whatsapp.businessAccountId "YOUR_BUSINESS_ACCOUNT_ID"

# 验证配置
openclaw whatsapp status

# 发送测试消息
openclaw whatsapp send --to "+1234567890" --message "Hello from OpenClaw"

电话号码 ID 标识代表你的 agent 发送消息的 WhatsApp 号码。在 Meta Developer Portal 中生成的访问令牌 24 小时后过期，除非你通过 Business Settings 中的 System Users 页面创建永久令牌。生产环境部署建议使用永久令牌以避免认证失败。

可选：配置 exec-approvals.json

OpenClaw 的执行审批系统控制插件可以在你的机器上运行哪些 shell 命令。exec-approvals.json 文件定义基于模式匹配的规则，支持 3 种操作：allow、deny 或 ask（执行前提示确认）。如果没有此文件，OpenClaw 默认对每个 shell 命令都进行提示，这意味着插件无法静默运行任何命令，除非你明确批准。

配置文件在 macOS 和 Linux 上位于 ~/.openclaw/exec-approvals.json，在 Windows 上位于 %USERPROFILE%\.openclaw\exec-approvals.json。规则从上到下依次匹配，第一个匹配的模式生效。以下示例展示了一个典型配置，包含 3 条规则，分别覆盖 Nylas CLI、curl 和文件删除。

// 示例 exec-approvals.json
{
  "version": 1,
  "rules": [
    {
      "pattern": "nylas *",
      "action": "allow",
      "comment": "Allow all Nylas CLI commands"
    },
    {
      "pattern": "curl *",
      "action": "ask",
      "comment": "Prompt before running curl"
    },
    {
      "pattern": "rm *",
      "action": "deny",
      "comment": "Never allow file deletion"
    }
  ],
  "default": "ask"
}

default 字段控制没有规则匹配时的行为。设为 "ask" 表示遇到未知命令时提示确认，"deny" 表示阻止所有未明确允许的命令，"allow" 表示完全信任所有插件。对于大多数用户，"ask" 是最安全的默认值。

你可以使用 cat 查看当前配置，也可以重置为 OpenClaw 的默认设置。重置命令会恢复出厂的 exec-approvals.json，默认操作为 ask，不包含自定义规则。

# 查看当前执行审批配置
cat ~/.openclaw/exec-approvals.json

# 重置为默认值
openclaw config reset exec-approvals

添加 Nylas 插件

@nylas/openclaw-nylas-plugin 为 OpenClaw 添加原生邮件、日历和联系人工具。Nylas 插件通过统一 API 支持 6 个邮件服务商 — Gmail、Outlook、Exchange、Yahoo、iCloud 和 IMAP。它在 OpenClaw 中注册了超过 20 个工具，涵盖消息 CRUD、日历事件管理、联系人搜索和附件处理。

安装需要 npm 包名、Nylas API 密钥（来自 dashboard.nylas.com）以及 gateway 重启。API 密钥存储在 OpenClaw 的本地配置文件中，不会离开你的机器。

# 安装 Nylas 插件
openclaw plugins install @nylas/openclaw-nylas-plugin

# 配置 Nylas API 密钥
openclaw config set 'plugins.entries.nylas.config.apiKey' 'YOUR_NYLAS_API_KEY'

# 重启 gateway 以重新加载插件配置
openclaw gateway restart

# 验证插件能看到你已连接的账户
openclaw run "List my connected email accounts" --plugin nylas

关于多账户配置、完整工具参考表及服务商专属故障排除，请参阅 安装 OpenClaw Nylas 插件 指南。

故障排除：npm install -g 后提示 "command not found"

npm install -g openclaw 后出现 "command not found" 错误，说明 npm 全局 bin 目录不在 shell 的 PATH 中。这是安装后最常见的问题，在通过 nvm 或手动解压安装 Node.js 的 Linux 和 macOS 用户中约有五分之一会遇到。修复方法是找到 npm prefix 目录，并将其 bin/ 子目录追加到 shell 配置文件中。

运行 npm config get prefix 查看该目录。在默认 nvm 安装中，prefix 通常为 ~/.nvm/versions/node/v22.x.x。openclaw 二进制文件位于 <prefix>/bin/openclaw。

# 查找 npm 全局二进制文件的安装位置
npm config get prefix

# 二进制文件位于 <prefix>/bin/openclaw
# 将 bin 目录添加到 PATH

# bash 用户（~/.bashrc）：
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# zsh 用户（~/.zshrc）：
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证是否生效
openclaw --version

如果你使用 nvm，切换 Node 版本时全局 prefix 会改变。请确保在日常使用的 Node 版本下安装 OpenClaw。运行 nvm use 22 && npm install -g openclaw 可确保 Node 22 激活时二进制文件始终可用。

故障排除：插件安装失败

openclaw plugins install 的安装失败分为 3 类：npm 版本不匹配、网络/代理错误和文件权限错误。最常见的原因是使用 npm 9 或更早版本，这些版本缺少 OpenClaw 插件所依赖的依赖解析功能。npm 10+ 默认随 Node.js 22 一起发布。以下步骤按可能性从高到低依次排查各种失败情况。

首先验证 Node.js 和 npm 版本。如果两者都是最新的，请清除 npm 缓存并重试。企业代理和文件所有权问题不太常见，但根据 OpenClaw GitHub issues 的反馈，约占安装失败的 15%。

# 1. 检查 Node.js 和 npm 版本
node --version   # 必须为 22.12.0+
npm --version    # 必须为 10+

# 2. 清除 npm 缓存
npm cache clean --force

# 3. 重新安装
openclaw plugins install @nylas/openclaw-nylas-plugin

# 4. 如果在企业代理后面，配置 npm 代理
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# 5. 如果 macOS/Linux 上出现权限错误，修复 npm prefix 目录的所有权
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

故障排除：插件已安装但未加载

当 openclaw plugins list 显示插件为 "active" 但其工具或命令在 agent 会话中不可用时，说明插件可能在启动时初始化失败。这可能发生在插件的必需配置值缺失，或依赖冲突导致插件入口点无法加载时。--debug 标志会将详细的初始化日志输出到 stderr，包括失败插件的确切错误信息。

重新安装插件会强制重新下载并重新向 OpenClaw 注册工具。卸载 + 安装的循环在大多数连接下不到 10 秒即可完成。

# 检查调试日志中的插件错误
openclaw --debug 2>&1 | grep -i plugin

# 重新安装有问题的插件
openclaw plugins uninstall <package-name>
openclaw plugins install <package-name>

# 验证是否正确加载
openclaw plugins list

后续步骤

OpenClaw 安装完成且 Nylas 插件注册后，CLI 即可用于邮件、日历和联系人自动化。以下指南详细介绍了插件配置、agent 构建模式以及常见 OpenClaw 问题的解决方法。

• 安装 OpenClaw Nylas 插件 — 添加带有类型化 schema 和自动发现功能的邮件、日历和联系人工具
• 使用 Nylas CLI 和 OpenClaw 构建个人助手 — 基于 exec 的方式，直接使用 shell 命令
• 保护 OpenClaw 邮件访问安全 — 锁定插件允许列表、凭据、策略和发送审批
• AI Agent 邮件和日历 CLI — 为自定义 agent 构建基于子进程的邮件和日历工具
• 修复 OpenClaw CLI 错误 — 排查 PATH、npm 权限、Node.js 版本和 Windows 安装问题
• Nylas CLI 命令参考 — 所有命令、标志和选项的完整参考