第 1 章：OpenClaw 基础介绍与安装

难度: ⭐ 入门

预计阅读: 15 分钟

前置章节: 无

📑 本章目录

• 1.1 OpenClaw 简介
• 1.2 环境准备
• 1.3 OpenClaw 安装步骤
• 1.4 初始化与基本配置
• 1.5 目录结构简介
• 1.6 实操练习
• 1.7 常见问题 (FAQ)
• 参考链接
• 本章小结

本章适合初学者，从零开始了解 OpenClaw 基本概念和安装流程。阅读完本章后，你将能够在本地完成 OpenClaw 的安装、初始化，并理解其核心目录结构和配置方式。

1.1 OpenClaw 简介

OpenClaw 是一套开源的多智能体自动化平台，具备 AI 执行、技能扩展和多通道连接能力。用户可通过指令、代码或技能扩展来定制自己的数字助手。它的设计理念是 “让 AI 真正替你干活”——不只是对话问答，而是能主动执行文件操作、调用 API、调度定时任务、管理多智能体协作等复杂工作流。

• 官网：https://OpenClaw.ai
• 文档：https://docs.OpenClaw.ai
• GitHub：https://github.com/OpenClaw/OpenClaw
• 社区 Discord：https://discord.gg/OpenClaw

核心特点

• 自动化任务执行与多智能体协作
• Skills 插件体系，功能可无限扩展
• 支持飞书、Slack、Discord 等多通道消息连接
• 支持本地部署与云端服务
• 内置长期记忆（Memory）与人格设定（SOUL）
• 开源、社区活跃

OpenClaw 与传统自动化工具对比

1.2 环境准备

在安装 OpenClaw 之前，请确保你的操作系统及基础依赖满足以下要求。OpenClaw 运行在 Node.js 之上，依赖 npm 进行包管理；同时需要 git 来处理版本控制和技能安装，curl 用于网络请求，jq 用于 JSON 配置文件的读写操作。如果在国内网络环境下安装，建议提前配置好 npm 镜像或代理。

系统要求

依赖安装示例（以 Ubuntu/Linux 为例）

sudo apt update
sudo apt install -y curl git jq

# 推荐使用 nvm 管理 node 版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "$XDG_CONFIG_HOME/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install 22
nvm use 22

macOS 用户快速安装依赖

# 使用 Homebrew 安装
brew install node@22 git curl jq

# Apple Silicon (M1/M2/M3) 用户需确认 Homebrew 路径已加载
eval "$(/opt/homebrew/bin/brew shellenv)"

# 确保 node@22 已链接到 PATH
brew link node@22 --force --overwrite

[!TIP] 如果你之前通过其他方式（如官网 .pkg 安装包）安装过 Node.js，建议先卸载旧版本再使用 Homebrew 安装，避免版本冲突。Apple Silicon Mac 的 Homebrew 默认安装路径为 /opt/homebrew/，与 Intel Mac 的 /usr/local/ 不同，确保你的 Shell 配置文件（~/.zshrc）中已加载 Homebrew 环境变量。如果 brew link 报冲突，可加 --overwrite 强制覆盖。

验证依赖版本

安装完成后，运行以下命令确认环境就绪：

node -v   # 应输出 v22.x.x
npm -v    # 应输出 10.x.x+
git --version
curl --version
jq --version

如果某项版本不符合要求，按以下方式处理：

[!TIP] 使用 nvm 管理 Node.js 版本时，每次打开新终端需要确保 nvm 环境已加载。如果发现 node 命令消失，执行 source ~/.bashrc（或 ~/.zshrc）重新加载即可。建议运行 nvm alias default 22 将 v22 设置为默认版本，这样新终端自动使用正确版本。

1.3 OpenClaw 安装步骤

安装方式对比

方式一：一键安装脚本（推荐）

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

脚本会自动检测系统环境、安装依赖并完成初始化。安装日志保存在 /tmp/openclaw-install.log。

方式二：手动 npm 全局安装

npm install -g openclaw@latest

[!TIP] 如果遇到权限问题，不推荐使用 sudo npm install -g，而应配置 npm 全局路径：

bash npm config set prefix ~/.npm-global export PATH="$HOME/.npm-global/bin:$PATH" text

方式三：源代码部署（开发/贡献用）

适用于需要修改 OpenClaw 源码、贡献 PR 或调试内部行为的开发者。源码部署可以方便地加断点、查看运行时状态，但需要手动管理依赖更新和构建流程。

# 1. 克隆仓库（建议 fork 后克隆自己的仓库）
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 2. 安装依赖（包括开发依赖）
npm install

# 3. 编译 TypeScript 源码
npm run build

# 4. 将本地构建链接为全局命令
npm link

构建完成后可通过 openclaw --version 验证。后续修改源码后只需重新执行 npm run build，无需重复安装。如需实时编译（开发模式），可使用：

npm run dev  # 启动 TypeScript watch 模式，保存即编译

[!TIP] 源码部署时建议同时安装 typescript 和 ts-node 作为全局工具，方便直接运行 .ts 脚本进行调试：npm install -g typescript ts-node。提交 PR 前请运行 npm run lint && npm test 确保代码规范和测试通过。

Docker 部署（可选）

# docker-compose.yml 示例
version: "3.8"
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ~/.openclaw:/root/.openclaw
    environment:
      - NODE_ENV=production

启动容器：

docker compose up -d

验证容器是否启动成功：

docker ps | grep openclaw           # 应显示 Up 状态
docker logs openclaw --tail 20      # 查看最近 20 行日志，确认无报错
curl -s http://localhost:3000/health # 健康检查接口应返回 OK

[!TIP] Docker 部署时，如果宿主机位于中国大陆，拉取镜像可能较慢。可以配置 Docker 镜像加速器（如阿里云 ACR、DaoCloud 等），在 /etc/docker/daemon.json 中添加 "registry-mirrors": ["https://your-mirror.com"] 后执行 sudo systemctl restart docker。另外，挂载的 ~/.openclaw 目录权限需确保容器内进程可读写。

如需更多容器化配置选项，请见 官方 Docker 文档。

1.4 初始化与基本配置

安装后首先执行初始化命令，该命令会创建工作区目录（~/.openclaw/workspace/）、生成默认配置文件（openclaw.json）、注册系统守护进程并自动启动 Gateway 服务。初始化是一次性操作，后续升级 OpenClaw 不需要重新执行。

如果你需要在无交互环境（如 CI/CD）中运行初始化，可以加 --yes 标志跳过所有确认提示：

openclaw onboard --install-daemon --yes

常见检查与启动命令

openclaw status        # 查看主服务状态
openclaw doctor        # 系统依赖和配置检测
openclaw dashboard     # 打开本地仪表盘（Web UI）
openclaw gateway start # 手动启动主服务

如因全局 npm 路径未加入 PATH，需额外设置：

export PATH="$(npm prefix -g)/bin:$PATH"
# 建议写入 ~/.bashrc 或 ~/.zshrc 使其持久生效
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

主配置文件详解

配置文件位于 ~/.openclaw/openclaw.json，采用标准 JSON 格式，可自定义 AI 提供商及模型、网关端口、网络代理和消息通道等参数。每次修改配置后需重启 Gateway 服务（openclaw gateway restart）才能生效。以下是一份包含常见字段的典型配置示例及字段说明：

{
  "ai": {
    "provider": "openai",
    "model": "gpt-4o",
    "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "gateway": {
    "port": 3000,
    "autoStart": true
  },
  "proxy": {
    "http": "http://127.0.0.1:7890",
    "https": "http://127.0.0.1:7890"
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxx",
      "appSecret": "xxxxxxxx"

    }
  },
  "memory": {
    "autoSync": true,
    "retentionDays": 90
  }
}

[!WARNING] openclaw.json 包含 API 密钥等敏感信息，务必确保文件权限设置为仅当前用户可读：

bash chmod 600 ~/.OpenClaw/OpenClaw.json text

1.5 目录结构简介

OpenClaw 安装后核心目录结构：

~/.openclaw/
├── workspace/                # 工作区目录
│   ├── AGENTS.md             # 多智能体协作模式
│   ├── SOUL.md               # 行为规范与人格设定
│   ├── TOOLS.md              # 工具配置
│   ├── MEMORY.md             # 长期记忆规则
│   ├── USER.md               # 用户个人信息
│   ├── IDENTITY.md           # 身份与认证配置
│   ├── config/               # 额外配置目录
│   │   └── mcporter.json
│   ├── memory/               # 日志记忆文件
│   │   └── YYYY-MM-DD-*.md
│   └── skills/               # 工作区级技能
│       └── <skill-name>/
│           └── SKILL.md
├── skills/                   # 全局已安装技能
│   └── <skill-name>/
│       └── SKILL.md
├── hooks/                    # 自定义钩子

│   └── <hook-name>/
│       └── HOOK.md
├── cron/                     # 定时任务配置
│   ├── jobs.json
│   └── runs/                 # 执行记录
├── credentials/              # 凭证存储
├── openclaw.json             # 主配置文件
└── logs/                     # 运行日志
    └── config-audit.jsonl

关键文件说明

进阶：OpenClaw 架构原理

深入理解 OpenClaw 的整体架构有助于后续章节的学习和高级场景的应用：

• Gateway 层：负责接收外部消息（飞书、API 等），解析意图后路由到对应 Agent 实例，是整个系统的入口和调度中心。
• Agent 核心引擎：每个 Agent 维护独立的上下文窗口和 Memory，通过 Prompt 编排、工具调用链和多轮对话管理实现智能交互。
• Skills 插件系统：采用声明式注册机制，通过 manifest.json 描述触发条件、参数和执行脚本，Gateway 在收到请求时自动匹配并调度。
• 配置热加载：openclaw.json 支持运行时热更新，修改配置后无需重启 Gateway 即可生效，底层通过文件系统 watch 实现。
• 事件驱动架构：所有消息处理采用异步事件队列，支持高并发场景下的消息有序处理和失败重试。

注意事项与常见错误

初次安装和配置 OpenClaw 时，以下是最容易遇到的问题和需要特别注意的事项：

⚠️ 特别提醒：不要在 root 用户下直接运行 npm install -g，建议使用 nvm 管理 Node.js 版本以避免权限问题。安装完成后务必运行 openclaw doctor 确认所有检查项通过。

1.6 实操练习

完成以下步骤，验证你的 OpenClaw 环境已正确安装并可正常运行。

步骤一：环境检查

运行 doctor 命令，确认所有依赖项通过检测：

openclaw doctor

期望输出应包含类似内容：

✔ Node.js v22.x detected
✔ npm v10.x detected
✔ git available
✔ openclaw.json found
✔ Gateway reachable
All checks passed!

如有红色 ✘ 项，请根据提示修复后重新运行。

步骤二：查看并修改主配置

用以下命令查看当前配置，并尝试通过 jq 格式化输出：

cat ~/.openclaw/openclaw.json | jq .

尝试修改一个非敏感字段（如 gateway 端口），然后重启服务验证：

# 备份配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

# 使用 jq 修改端口（示例）
jq '.gateway.port = 3001' ~/.openclaw/openclaw.json > /tmp/oc-tmp.json \
  && mv /tmp/oc-tmp.json ~/.openclaw/openclaw.json

# 重启 gateway 使配置生效
openclaw gateway restart
openclaw status

步骤三：体验首次对话

启动 OpenClaw 交互式终端，发送一条测试消息来验证 AI 连接正常。openclaw chat 会建立一个本地会话，连接你在配置文件中指定的 AI 模型进行对话。会话中 OpenClaw 可以调用已安装的 Skills 来执行实际操作：

openclaw chat

在交互界面中输入：

你好，请告诉我当前的系统状态。

OpenClaw 会调用内置工具返回状态信息。输入 exit 或按 Ctrl+C 退出对话。

步骤四（可选）：查看记忆目录

对话结束后，检查是否自动生成了记忆文件：

ls -la ~/.openclaw/workspace/memory/

你应该能看到以当天日期命名的 .md 文件，这是 OpenClaw 的长期记忆机制在工作。

进阶：OpenClaw 架构原理

理解其通信机制有助于诊断问题。OpenClaw 采用 Gateway + Agent 分层架构：

注意事项与常见错误

初学者常见错误：

1.7 常见问题 (FAQ)

以下是安装和初始化阶段最常见的问题。如果你的问题不在此列，可运行 openclaw doctor 获取自动诊断建议，或查看 官方 FAQ 页面。

Q1：安装后执行 openclaw 提示 “command not found”

原因：npm 全局 bin 目录未加入系统 PATH。

解决方法：

# 查看 npm 全局 bin 路径
npm prefix -g

# 将路径加入 PATH（以 bash 为例）
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 验证
which openclaw

Q2：Node.js 版本过低，如何升级？

原因：OpenClaw 依赖 Node.js v20 及以上版本的 ES Module 和 Fetch API 支持。低版本（如 v16、v18）可能导致启动失败或运行异常。

解决方法：推荐使用 nvm（Node Version Manager）管理版本，这样可以在多个 Node 版本间一键切换而不影响系统全局环境：

nvm install 22
nvm alias default 22
node -v  # 确认输出 v22.x.x

Q3：openclaw gateway start 启动失败，端口被占用

解决方法：

# 检查端口占用情况
lsof -i :3000

# 方法 A：杀掉占用进程
kill -9 <PID>

# 方法 B：修改 openclaw 端口配置
jq '.gateway.port = 3001' ~/.openclaw/openclaw.json > /tmp/oc.json \
  && mv /tmp/oc.json ~/.openclaw/openclaw.json
openclaw gateway start

Q4：国内网络安装 npm 包很慢，怎么办？

解决方法：国内网络环境下 npm 默认源（registry.npmjs.org）速度较慢甚至超时，推荐以下几种加速方案：

方案一：永久切换 npm 镜像源（推荐）

# 设置淘宝镜像为默认源
npm config set registry https://registry.npmmirror.com

# 验证镜像是否生效
npm config get registry
# 应输出：https://registry.npmmirror.com

# 测试连通性
npm ping

方案二：使用 cnpm 替代

# 安装 cnpm 客户端
npm install -g cnpm --registry=https://registry.npmmirror.com

# 之后用 cnpm 替代 npm
cnpm install -g openclaw@latest

方案三：使用 yarn 或 pnpm 替代

# yarn 方式
npm install -g yarn
yarn config set registry https://registry.npmmirror.com
yarn global add openclaw@latest

# pnpm 方式（性能更优，节省磁盘空间）
npm install -g pnpm
pnpm config set registry https://registry.npmmirror.com
pnpm add -g openclaw@latest

💡 提示：如果只需临时使用镜像而不想修改全局配置，可在安装命令后附加 --registry=https://registry.npmmirror.com 参数。切换回官方源使用 npm config set registry https://registry.npmjs.org。

Q5：如何完全卸载 OpenClaw？

完全卸载需要依次清理全局包、配置数据、systemd 服务以及残留缓存。请按以下步骤操作：

# 步骤 1：停止运行中的服务
openclaw daemon stop

# 步骤 2：如果配置了 systemd 服务，先禁用并删除
systemctl --user stop openclaw-gateway 2>/dev/null
systemctl --user disable openclaw-gateway 2>/dev/null
rm -f ~/.config/systemd/user/openclaw-gateway.service
systemctl --user daemon-reload

# 步骤 3：卸载全局 npm 包
npm uninstall -g openclaw

# 步骤 4：删除配置与数据目录（⚠️ 谨慎操作，会清除所有数据和日志）
rm -rf ~/.openclaw

# 步骤 5：清理 npm 缓存中的残留
npm cache clean --force

# 步骤 6：验证卸载是否完成
which openclaw        # 应提示 command not found
ls ~/.openclaw 2>&1   # 应提示 No such file or directory
systemctl --user status openclaw-gateway 2>&1  # 应提示 Unit not found

⚠️ 注意：如果你在 ~/.bashrc 或 ~/.zshrc 中添加过 OpenClaw 相关的环境变量或 PATH 配置，也需要手动移除相关行并执行 source ~/.bashrc 使更改生效。

快速排查参考表

安装或启动过程中遇到常见问题时，可按照此表快速定位原因并执行对应的修复命令。更复杂的故障排查流程请参考 第 9 章：故障排查与日志分析。

参考链接

• OpenClaw 官方文档 — 完整 API 参考与使用指南
• OpenClaw GitHub 仓库 — 源码、Issue 与 Roadmap
• nvm 安装指南 — Node.js 版本管理工具
• npm 镜像配置 — 国内用户加速 npm 安装
• Docker Compose 文档 — 容器化部署参考

本章小结

• OpenClaw 是开源多智能体平台，支持 AI 自动化与技能扩展，与传统自动化工具相比具备 AI 原生决策与插件生态优势。
• 安装前确保 Node.js v22+、git、curl 等依赖就绪，推荐使用 nvm 管理 Node 版本。
• 安装推荐使用一键脚本或 npm 全局安装，开发者可选源码部署或 Docker。
• 安装后通过 openclaw onboard --install-daemon 完成初始化。
• 主配置文件 ~/.openclaw/openclaw.json 以 JSON 格式存储 AI、网关、代理、通道等配置。
• 常用命令：status、doctor、dashboard、gateway start、chat。
• 遇到问题时优先使用 openclaw doctor 做自动检测。