OpenClaw 部署指南

写在前面

OpenClaw 是一个很棒的开源 AI Agent 框架，但它的安装部署过程对新手来说并不友好。我花了一周时间踩完所有的坑，把完整的部署经验整理成这篇文章。

先说结论：如果你用的是 macOS，且网络环境正常，强烈建议走快速安装路线。官方脚本已经做了很多优化，大部分情况下开箱即用。手动安装是给那些喜欢折腾的人准备的——当然，你也可能是被迫的。

快速安装（推荐）

一条命令搞定，省时省力：

1
2
3
4
5

# macOS
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows
iwr -useb https://openclaw.ai/install.ps1 | iex

脚本会自动检测环境、安装依赖、配置路径。如果你的网络环境比较"特殊"，建议先配好代理，速度会快很多。

如果安装脚本报错了，别急着放弃。可以先装个 opencode 排查问题——它自带免费模型，能帮你定位是网络问题还是环境问题：

1
2
3

curl -fsSL https://opencode.ai/install | bash
opencode --version
opencode

手动安装

如果自动脚本在你机器上跑不通，那就动手吧。手动安装的好处是每一步都清楚自己在做什么，出问题也更容易定位。

安装 Node.js（≥ 22）

Node.js 版本管理器我推荐 nvm。直接装 Node.js 容易遇到权限问题，用 nvm 管理会清爽很多。

第一步：装 nvm

1

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

装完之后，关闭终端重新打开，或者执行：

1

source ~/.zshrc

这一步很多人会忘，然后奇怪为什么 nvm 命令找不到。

第二步：装 Node.js 22

1

nvm install 22

第三步：验证

1

node -v

看到 v22.x.x 就对了。

配置 GitHub SSH 密钥

这是个隐藏坑。OpenClaw 依赖的 libsignal-node 包在安装时会通过 SSH 协议从 GitHub 拉取代码。如果你没配 SSH 密钥，npm install 会直接报错。

安装 Git

用 Homebrew 装，方便管理：

1
2
3
4
5
6

# 先装 Homebrew（如果还没有）
/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

# 再装 Git
brew install git
git --version

生成 SSH 密钥

把下面的邮箱换成你自己的 GitHub 注册邮箱：

1

ssh-keygen -t ed25519 -C "your_email@example.com"

执行后会问两个问题：

1. 保存路径：直接回车，用默认的 ~/.ssh/id_ed25519
2. 密码：直接回车两次，留空！ 这点很重要，如果你设了密码，OpenClaw 安装时会卡住让你输入，但那个时候你根本没法输入。

看到 Your identification has been saved 就说明生成成功了。

添加密钥到 SSH Agent

1
2

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

看到 Identity added 就行。

把公钥添加到 GitHub

1

pbcopy < ~/.ssh/id_ed25519.pub

这行命令会把公钥复制到剪贴板。然后去 GitHub：

右上角头像 → Settings → SSH and GPG keys → New SSH key

• Title：随便填，比如 “My Mac”
• Key type：选 Authentication
• Key：粘贴剪贴板里的内容
• 点击 Add SSH key

验证一下：

1

ssh -T git@github.com

看到 Hi username! You've successfully authenticated... 就配好了。

安装 OpenClaw

全局安装 CLI：

1

npm install -g openclaw@latest

然后运行安装向导：

1

openclaw onboard --install-daemon

这个命令会安装网关守护进程（launchd 用户服务），让 OpenClaw 能在后台持续运行。向导会引导你配置 AI 模型（Anthropic/Claude 或 OpenAI）和工作区路径。如果你暂时没有 API 密钥，可以先跳过，后面再配。

对接飞书

飞书集成是 OpenClaw 的核心功能之一，但配置起来有几个坑。

插件配置

权限配置

飞书开放平台的权限配置很繁琐，需要手动勾选大量权限。可以直接用下面的 JSON 批量导入：

安装飞书插件

直接装可能会报错：Failed to install @openclaw/feishu: npm install failed。

这是个已知问题，需要手动修复一下依赖路径：

1

cd ~/.openclaw/extensions/feishu

编辑 package.json，把 "devDependencies": { "openclaw": "workspace:*" } 改成 "devDependencies": { "openclaw": "../../" }。

然后手动装依赖：

1
2

npm install @sinclair/typebox --save
npm install

重新加载插件：

1
2
3
4

openclaw plugins install ./

# 验证是否加载成功
openclaw plugins list | grep feishu

如果输出 feishu | loaded 就成功了。没成功的话看日志：

1

openclaw channels logs | grep feishu

最后重启网关，再跑一次配置向导：

1
2

openclaw gateway restart
openclaw onboard

事件回调

配置好飞书的 App ID 和 App Secret 后，执行 openclaw gateway restart 让配置生效。

在飞书开放平台配置事件订阅时，选择"长连接"模式。添加事件时把"消息与群组"下面的全部勾上。

聊天配置

飞书插件装好了，接下来让机器人能和你聊天：

1
2

# 启动网关
openclaw gateway

在飞书里找到你的机器人，发一条消息。机器人会回复一个配对码，回到终端批准它：

1

openclaw pairing approve feishu <配对码>

批准后就能正常对话了。

查看已配对用户：

1

cat ~/.openclaw/credentials/feishu-allowFrom.json

每条记录是一个 ou_ 开头的飞书用户 ID。

一个常见报错：如果打开终端提示 compdef: command not found，是 Zsh 补全系统没初始化。在 ~/.zshrc 开头加上：

1 2	autoload -Uz compinit compinit

然后 source ~/.zshrc 或重开终端即可。

文件结构

了解 OpenClaw 的文件结构，出问题时能快速定位。

关键路径

~/.openclaw/
├── openclaw.json          # 主配置文件（JSON5 格式）
├── credentials/           # API 密钥/OAuth（权限建议设为 600）
├── workspace/             # Agent 核心文件（建议用 Git 备份）
│   ├── AGENTS.md          # 运维规则
│   ├── SOUL.md            # 人格/伦理设定
│   ├── IDENTITY.md        # 命名/角色/Emoji
│   ├── USER.md            # 用户画像/偏好
│   ├── TOOLS.md           # 工具说明
│   ├── MEMORY.md          # 长期记忆（仅私聊）
│   ├── HEARTBEAT.md       # 周期性检查逻辑
│   ├── scripts/           # 自定义脚本
│   ├── software/          # 软件包
│   ├── memory/            # 记忆文件
│   └── skills/            # 自定义技能
├── agents/<id>/sessions/  # 聊天记录
└── skills/

加载优先级：Rules > Soul > User > Memory > Tools

备份机制

你会看到 openclaw.json.bak、openclaw.json.bak.1 这样的文件。这是 OpenClaw 的自动备份，每次 openclaw config set 修改配置时都会自动创建，最多保留 5 个版本。

恢复配置：

1
2
3
4
5

# 恢复到最近一次备份
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

# 恢复到更早的版本
cp ~/.openclaw/openclaw.json.bak.2 ~/.openclaw/openclaw.json

清理旧备份：

1

rm -f ~/.openclaw/openclaw.json.bak.[3-9]

建议不要手动改备份文件，交给系统自动管理。如果有特别重要的配置版本，用 openclaw config export 导出，或者纳入 Git 版本控制。

Chrome 浏览器集成

OpenClaw 可以控制 Chrome 浏览器执行自动化任务。有两种模式可选。

托管模式（推荐）

托管模式让 OpenClaw 完全管理一个独立的 Chrome 配置文件，稳定性最好：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 安装浏览器控制插件
openclaw plugins install @openclaw/browser-control

# 启用
openclaw config set browser.enabled true

# 使用 openclaw 托管配置文件
openclaw config set browser.defaultProfile "openclaw"

# 设为有界面模式（能看到 Chrome 窗口）
openclaw config set browser.headless false

# Mac 用户建议关闭沙盒，避免启动失败
openclaw config set browser.noSandbox true

完成设备配对：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 查看待配对设备
openclaw devices list

# 批准配对
openclaw devices approve <Request>

# 重启服务
openclaw gateway restart

# 启动浏览器
openclaw browser start

注意：使用托管模式时，记得关闭 Chrome 扩展程序，否则流量会走扩展的通道，可能出问题。

Chrome 扩展模式

这个模式比较繁琐，每次打开新标签页都要点击扩展图标确认 ON 状态。只建议在托管模式无法工作时使用。

1
2
3
4
5

# 安装扩展到本地
openclaw browser extension install

# 查看扩展目录
openclaw browser extension path

然后在 Chrome 中启用"开发者模式"，点击"加载已解压的扩展程序"，选择上面输出的目录。

获取 Token：

• 命令行：openclaw config get gateway.auth.token
• 配置文件：openclaw.json → auth → token

进阶使用

OpenClaw 的强大之处在于可以自定义 Skill，让 AI 具备各种专业能力。下面介绍一些实用的 Skill 及其配置方法。

🎯 实用 Skill 清单

📖 jina-reader

作者：ericsantos

功能：通过 Jina AI Reader API 提取网页内容，支持三种模式：

• 读取：URL 转 Markdown
• 搜索：网页搜索 + 全文提取
• 核实：事实核查

配置方法：

1
2
3
4
5

# 编辑 ~/.zshrc，添加 API Key
export JINA_API_KEY=”jina_你的密钥”

# 重新加载配置
source ~/.zshrc

🖼️ aliyun-image-skill

项目地址：https://github.com/StanleyChanH/aliyun-image-skill

支持的模型：

配置方法：

1
2
3
4
5

# 编辑 ~/.zshrc
export DASHSCOPE_API_KEY=”your_api_key_here”

# 重新加载配置
source ~/.zshrc

⚠️ 常见问题：即使已在 ~/.zshrc 中设置环境变量，OpenClaw 通过 exec 执行命令时不会自动加载。推荐使用全局 .env 文件解决此问题。

推荐配置方式：

在 ~/.openclaw/.env 文件中添加：

1

DASHSCOPE_API_KEY=sk-a74c1d838bbb4d9ca...

环境变量加载优先级（从高到低）：

1. 进程环境（当前 shell 中已设置的环境变量）
2. 当前工作目录的 .env 文件
3. 全局 .env 文件（~/.openclaw/.env）
4. 配置 env 块（openclaw.json 中）
5. Shell 环境导入

🔍 Tavily Web Search

作者：arun-8687

功能：联网搜索能力，需要 Tavily API Key。

配置方法：

1
2
3
4
5

# 编辑 ~/.zshrc
export TAVILY_API_KEY=”xxx”

# 重新加载配置
source ~/.zshrc

🌐 agent-browser

项目地址：vercel-labs/agent-browser

功能：浏览器自动化 CLI，专为 AI 代理设计。

安装：

1
2

# 全局安装 + 自动确认
npx skills add vercel-labs/agent-browser -g -y

包含的 Skill：

核心工作流：打开页面 → 快照（获取元素引用如 @e1, @e2）→ 交互（点击/填写）→ 重新快照

🏪 ClawHub

ClawHub 是 OpenClaw 的技能市场，用于发现和安装更多 Skill。

常用命令：

1
2
3
4
5

npm install -g clawhub
clawhub login --token <token>    # 登录
clawhub install xxx               # 安装 skill
clawhub logout                    # 登出
clawhub whoami                    # 查看当前用户

🖥️ Peekaboo

作者：Peter Steinberger（OpenClaw 作者）

功能：macOS GUI 自动化的核心工具。

安装方式：

1
2
3
4
5

# Homebrew（推荐）
brew install steipete/tap/peekaboo

# npm（MCP 服务器）
npm install -g @peekaboo/peekaboo

🗺️ EvoMap

项目地址：https://evomap.ai/

接入方法：

1

curl -s https://evomap.ai/skill.md

然后：

1. 阅读技能指南
2. 发送 hello 注册你的节点

操控 claude cli

1. 安装 acpx 插件（ACP 后端）

1
2

openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

2. 确保已安装 Claude Code CLI

1
2
3
4
5

# 进入命令行界面，安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 运行如下命令，查看安装结果，若显示版本号则表示安装成功
claude --version

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# 编辑或新增 `settings.json` 文件
# MacOS & Linux 为 `~/.claude/settings.json`
# Windows 为`用户目录/.claude/settings.json`
# 新增或修改里面的 env 字段
# 注意替换里面的 `your_zhipu_api_key` 为您上一步获取到的 API Key
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your_zhipu_api_key",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  }
}
# 再编辑或新增 `.claude.json` 文件
# MacOS & Linux 为 `~/.claude.json`
# Windows 为`用户目录/.claude.json`
# 新增 `hasCompletedOnboarding` 参数
{
  "hasCompletedOnboarding": true
}

3. 配置 openclaw.json

配置文件

1. 在更新到 2026 3.2 版本后工具权限被限制的问题，修改 openclaw.json

1
2
3
4
5
6

"tools": {
  "profile": "full",
  "sessions": {
    "visibility": "all"
  }
}

2. 可以向已存在的 session 发送消息，不会创建多个重复 session

在让 openclaw 操控 claude cli 时，每个任务都是一个新的 session，导致 session 堆积，无法有效复用

写在最后

OpenClaw 是一个很有潜力的开源项目，但文档和生态还在完善中。这篇文章记录了我踩过的坑，希望能帮到后来的人。

如果遇到问题，有几个途径可以寻求帮助：

• GitHub Issues：提交 bug 报告或功能建议
• 官方文档：虽然不完整，但基础内容都有
• 社区：有一些活跃的用户在分享经验

OpenClaw 更新比较频繁，这篇文章的内容可能会过时。如果发现有不一致的地方，以官方文档为准。