OpenClaw 部署指南 -

2026-02-23 约 1100 字预计阅读 5 分钟 - 次阅读

快速安装（推荐）

使用官方安装脚本，无需科学上网也能完成，配置代理后速度更快。

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）

推荐通过 nvm 管理 Node.js 版本，避免权限问题。

安装 nvm：

1

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

装完后关闭终端重新打开，或执行 source ~/.zshrc。

安装 Node.js 22：

1

nvm install 22

验证：

1
2


node -v
# 应输出 v22.x.x

配置 GitHub SSH 密钥

OpenClaw 的依赖包 libsignal-node 在安装时会通过 SSH 克隆 GitHub 仓库，所以需要提前配好 SSH。

安装 Git

通过 Homebrew 安装：

1
2
3
4
5


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

# 卸载 Homebrew（备用）
/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/HomebrewUninstall.sh)"

1
2
3


brew install git
git --version
# 应输出 git version 2.xx.x

生成 SSH 密钥

把 your_email@example.com 替换成你的 GitHub 注册邮箱：

1

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

-t ed25519：加密类型，macOS 推荐。
-C：注释，通常填邮箱。

系统会问两个问题：

保存路径：直接回车，用默认路径 /Users/你的用户名/.ssh/id_ed25519。
密码：直接回车两次，留空。否则 OpenClaw 安装时会卡住要求输密码。

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

启动 SSH 代理并添加密钥

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 在后台运行。向导会引导你配置模型（Anthropic/Claude 或 OpenAI）、工作区路径等。没有 API 密钥的话可以先跳过。

对接飞书

插件配置

应用配置：批量导入权限

安装飞书插件

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

需要手动修改 extensions/feishu/package.json，将 "devDependencies": { "openclaw": "workspace:*" } 改为 "devDependencies": { "openclaw": "../../" }，然后执行：

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


cd ~/.openclaw/extensions/feishu

# 手动装依赖
npm install @sinclair/typebox --save
npm install

# 重新加载插件
openclaw plugins install ./

# 验证
openclaw plugins list | grep feishu
# 应输出: feishu | loaded

# 如果没加载成功，看日志
openclaw channels logs | grep feishu

# 重启网关
openclaw gateway restart

# 再跑一次向导配置飞书
openclaw onboard

事件回调

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

事件配置选择"长连接"，添加事件时把"消息与群组"全部勾上。

聊天配置

启动网关：

1

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.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 修改配置时，系统会先把当前配置存为 .bak，旧的 .bak 依次后移，最多保留 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 浏览器

托管模式

在终端依次执行：

1
2
3
4
5
6
7
8


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

# 设为有界面模式（能看到 Chrome 窗口），不需要看窗口就设为 true
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 对同一条消息重复回复两次。可能原因是设备配对状态异常导致消息重复处理。

诊断

执行 openclaw status 输出 Service config issue: Gateway service uses Node from a version manager; it can break after upgrades.

根本原因：用 nvm 管理的 Node.js 运行 OpenClaw 服务时，环境变量没有正确传递，导致配置文件未被读取。

修复步骤

生成令牌：

1
2


openssl rand -base64 32
# 假设输出: xJ4uQbZ8v7R3kL2pNqY9wE0aS1dF2gH3...

写入配置文件：

1

nano ~/.openclaw/openclaw.json

添加（替换为你的实际令牌）：

修复服务环境配置（这步是关键）：

因为 nvm 的 Node 服务不会自动读取 ~/.openclaw/openclaw.json，需要通过 LaunchAgent 显式注入令牌。

1
2
3
4
5


# 创建环境配置
echo 'export OPENCLAW_GATEWAY_TOKEN="你的令牌"' > ~/.openclaw/gateway.env

# 编辑 LaunchAgent
sudo nano /Users/avocado/Library/LaunchAgents/ai.openclaw.gateway.plist

在 plist 的 <key>EnvironmentVariables</key> 部分添加：

1
2


<key>OPENCLAW_GATEWAY_TOKEN</key>
<string>你的令牌</string>

重启并验证：

1
2
3


openclaw gateway stop
openclaw gateway start
openclaw devices list

验证逻辑：Gateway 服务通过环境变量 OPENCLAW_GATEWAY_TOKEN 获取预期令牌，客户端 CLI 通过配置文件 gateway.remote.token 获取发送的令牌，两者必须一致。

避免后续问题

如果不想折腾 nvm 的环境变量问题，可以改用系统 Node：

1

brew install node

然后移除 openclaw.json 中的 gateway.remote.token，系统 Node 会自动处理。

进阶使用

联网搜索

装好 mcporter 后，把 API KEY 发给 openclaw，让它自己完成配置。备选方案：博查 MCP。

Skill

jina-reader(自建)

把下面这段话发给 openclaw，让它据此生成 skill（需要先有 skill-creator）：

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


网页抓取：jina.ai Reader

OpenClaw 自带的网页抓取用的是 Readability，但存在几个问题：
1. 不加载 JavaScript，有些网页抓到的是空白页。
2. 翻页做得不好，多页内容抓不全。
3. 拿到的信息有时缺少结构化的元数据（标题、作者、发布时间）。

替代方案是 jina.ai Reader，几个优点：
1. 能绕过部分付费墙，抓取需要登录的文章。
2. 能抓取 X（推特）上的推文。
3. 返回干净的 Markdown 格式。
4. 不需要 API key，免费。

用法：在目标网址前加 `https://r.jina.ai/` 前缀。

示例：
- 原网址：`https://example.com/article`
- 抓取地址：`https://r.jina.ai/https://example.com/article`

Humanizer-zh：用于去除文本中的 AI 生成痕迹，让内容读起来更自然。让 openclaw 自己访问该仓库页面下载 skill。

agent-browser-cli(自建)：装了 agent-browser 之后 openclaw 不一定会用。让它访问 https://github.com/vercel-labs/agent-browser，根据文档生成对应的 skill。

weibo-poster(自建)：用 agent-browser-cli skill 演示一遍微博从登录到发帖的完整流程，让 openclaw 据此创建 skill。

Proactive Agent：将 AI 智能体从任务执行者转变为能预见需求、持续优化的主动伙伴，作者 halthelobster

Find Skills：帮助用户发现并安装 skills，作者 JimLiuxinghai

self-improving-agent：记录学习心得、错误与修正，推动持续改进，作者 pskoett

Ontology：为结构化智能体记忆与可组合技能构建的类型化知识图谱，作者 oswalpalash

ClawHub

1
2
3
4
5


npm install -g clawhub
clawhub login --token <token>
clawhub install xxx
clawhub logout
clawhub whoami

定时任务

1
2
3
4
5


创建一个备份所有配置文件和记忆文件的定时任务：
触发条件：距离上一次备份超过24小时。或者文件的大小变化超过10K。
备份方式：本地备份（指定文件路径）+远程备份（我用的iCloud）。
文件存储方式：从周一到周日创建7个文件夹，把对应星期日期的文件存进去。
同时准备一份手动回复指南说明文档和一个自动恢复脚本。

代理浏览器

agent-browser

全局安装原生 Rust 二进制文件：

1
2


npm install -g agent-browser
agent-browser install  # 下载 Chromium

直接通过原生 Rust CLI 执行命令，解析开销在亚毫秒级。

如果只是试用，不想全局安装，可以用 npx：

1
2


npx agent-browser install   # 首次需要下载 Chromium
npx agent-browser open example.com

npx 会先经过 Node.js 再调用 Rust CLI，比全局安装慢不少。日常使用建议全局安装。

EvoMap

地址：https://evomap.ai/

接入你的 AI

1

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

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

优质资产

📡 网络与错误处理

HTTP 重试机制（GDI 66）

功能：处理超时、连接重置、429 错误
场景：所有 HTTP API 调用

Agent 全局内省调试框架（GDI 65.65）

功能：全局错误捕获、根因自动分析
价值：减少调试时间 80%

HATEOAS 通用 HTTP 重试（GDI 64.6）

功能：指数退避、连接池、断路器
场景：所有网络请求
价值：提升 API 成功率 30%

🔧 平台集成

飞书消息传递（GDI 64.35）

功能：卡片模式切换、避免沉默失败
场景：Feishu API 集成

Feishu URL 类型检测（GDI 62.9）

功能：自动识别 Doc/Sheet/Base 类型
价值：避免 400 错误

🐳 DevOps 与容器

Kubernetes OOMKilled 修复（GDI 64.35）

功能：动态堆大小、容器内存监控
场景：K8s 环境部署

ArgoCD 自动愈合（GDI 64.6）

功能：集群状态自动同步、Pod 故障修复
场景：CI/CD 流水线

📝 编程工具

Python CJK 正则修复（GDI 62.9）

功能：中文/日文/韩文字符边界检测
价值：修复文字处理 bug