片刻

OpenClaw入门文档

发表于 2026-03-17 分类于技术视野

1. 什么是 OpenClaw？

OpenClaw 是一个开源的多智能体 AI 助手框架，专为个人和团队设计。它是一个功能强大的 AI 代理平台，支持多通道通信、多模型集成、沙盒隔离和自动化功能。

简单来说就是 AI 模型（本地或远程） + 远程通信网关（服务器） + 本地执行引擎（本地）

核心特性

多通道支持：支持Telegram、飞书、QQ机器人、Google Chat、Mattermost、MS Teams 等
多模型集成：支持 OpenAI、Anthropic、Google 等主流 AI 模型，还可以使用自定义供应商
多智能体架构：支持同时运行多个独立的 AI 代理，使用 gateway 统一调度，纯通信层，只做 “消息搬运”
沙盒隔离：使用Docker 容器化运行，可以确保安全隔离
自动化功能：内置心跳检测、定时任务（cron，让 OpenClaw 能 “无人值守” 运行，还能自己监控状态、按计划干活，不用你手动触发。
网关实现会话管理：智能会话路由和身份识别，对接远程渠道（如 Telegram / 微信）时，能识别发送指令的用户身份
工具集成：丰富的内置工具和技能系统
可扩展架构：插件系统和自定义工具支持

2. 核心概念

2.1 智能体（Agent）

智能体是 OpenClaw 的核心运行单元，每个智能体都有：

独立的工作空间：包含文件、工具和配置
会话管理：独立的对话历史和上下文
模型配置：可配置不同的 AI 模型和参数
访问控制：细粒度的权限和安全策略

智能体在客户端运行

2.2 会话（Session）

会话管理对话的连续性和隔离性：

会话范围：支持 main（共享）、per-peer、per-channel-peer、per-account-channel-peer 等

会话范围	隔离粒度	核心特点	典型场景
`main`	无隔离（全局共享）	所有人 / 渠道共用上下文	单人自用、公共任务
`per-peer`	按用户隔离	认人不认渠道	家庭 / 小团队共用
`per-channel-peer`	按渠道 + 用户隔离	既认人也认渠道	多场景分渠道使用
`per-account-channel-peer`	按账号 + 渠道 + 用户隔离	最高级隔离，多租户适配	企业多部门 / 多客户

会话重置：支持按时间、空闲时间等条件自动重置
线程绑定：在 Discord 等平台支持线程级会话路由
身份链接：智能识别和链接用户身份

会话使用网关统一路由、管理

2.3 网关（Gateway）

Gateway 是 OpenClaw 的核心服务，负责：

会话路由：智能路由消息到对应的智能体
服务管理：启动、停止、重启等操作
API 提供：提供 REST API 和 WebSocket 接口
监控统计：提供健康检查、日志、统计等功能

核心功能是会话路由

2.4 工具系统（Tools）

OpenClaw 提供丰富的工具系统：

内置工具：文件操作、网络请求、代码执行等
技能系统：可配置的专用技能模块
自定义工具：支持开发自定义工具
安全策略：细粒度的工具访问控制

2.5 内存系统（Memory）

智能的记忆和上下文管理：

工作空间记忆：每个智能体独立的文件系统
会话记忆：对话历史和上下文保持
长期记忆：重要信息的持久化存储0
记忆检索：语义搜索和相关信息召回

3. 使用方法

3.1 安装部署

快速开始

# 克隆代码
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
npm install pnpm -g
pnpm install

# 两个终端分别调用 （便于临时使用）
pnpm openclaw gateway # 启动网关
pnpm openclaw onboard # 初始化，并打开网页管理界面（可选） --install-daemon启动 --install-daemon参数安装网关作为一个用户服务

详细步骤（集成系统服务）
详细安装视频参考：https://www.bilibili.com/video/BV1D4wcz6EVV/?vd_source=76f520a23546bf9301d4e80da6ec8043

安装 node 环境，Node ≥22 以上版本，推荐使用nvm进行安装，方便管理node环境
nvm项目地址：https://github.com/nvm-sh/nvm
nvm官方文档：https://www.nvmnode.com/zh/
步骤：
1. 官网下载windows 版本的安装包
2. 终端输入命令：nvm list available，查看可用版本
3. 终端输入命令：nvm install 22.21.1
4. 根据提示输入：nvm use 22.21.1 切换到对应版本
5. 输入 node -v，显示node版本则说明安装成功

安装pnpm

1 2	npm i -g pnpm pnpm setup # 执行完后重启终端

使用 pnpm 安装 openclaw

1 2	pnpm add -g openclaw@latest openclaw -v # 正确回显版本号说明安装成功

注册一个longcat 的账号，使用longcat的模型，每天500w token，直接使用qwen也可以+

初始化配置

1	openclaw onboard --install-daemon # 初始化配置并安装后台服务

登录Qwen

选择完后等待安装完成，会打开一个界面，显示

打开终端：输入openclaw gateway 开启网关服务

启动成功之后，再开一个终端输： openclaw dashboard 打开网页界面

启动成功：

到这里就可以正常使用

参考文档：https://ai.codefather.cn/library/2031710685934739457

卸载指令：

# Mac/Linux用户  执行以下命令
openclaw gateway stop
openclaw gateway uninstall
schtasks /Delete /F /TN "OpenClaw Gateway"
Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw"
Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd" -ErrorAction SilentlyContinue
npm rm -g openclaw
# 如果你是用 pnpm 安装的，改为执行：pnpm remove -g openclaw

# windows 用户执行以下指令
openclaw gateway stop
openclaw gateway uninstall
schtasks /Delete /F /TN "OpenClaw Gateway"
Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw"
Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd" -ErrorAction SilentlyContinue
npm rm -g openclaw
# 如果你是用 pnpm 安装的，改为执行：pnpm remove -g openclaw

3.2 基本配置

最小配置示例

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"]
    }
  }
}

模型配置

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-4"]
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-4": { alias: "GPT-4" }
      }
    }
  }
}

多智能体配置

{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        workspace: "~/.openclaw/workspace-home"
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work"
      }
    ]
  },
  bindings: [
    {
      agentId: "home",
      match: { channel: "whatsapp", accountId: "personal" }
    },
    {
      agentId: "work",
      match: { channel: "whatsapp", accountId: "biz" }
    }
  ]
}

3.3 高级功能

沙盒隔离

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent"     // session | agent | shared
      }
    }
  }
}

心跳检测

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last"
      }
    }
  }
}

定时任务（Cron）

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h"
  }
}

4. 实现原理与架构

4.1 整体架构

OpenClaw 采用模块化架构，主要组件包括：

4.2 核心组件详解

agent = 组装上下文、调用 AI 模型、执行工具操作、保存上下文。
gateway = 消息转发 + 会话路由 + 身份识别（只负责远程通信）

其他组件

控制界面：网页界面，命令行工具，移动端聊天工具
渠道适配器：把不同平台的消息翻译成统一格式

5. 应用场景

养殖系统运维

功能：

基础调节：根据养殖环境实时数据（温湿度、溶氧量、氨氮值、光照强度），自动调节温控设备、料塔、通风扇的运行参数‘
硬件故障联动：通过心跳检测感知硬件离线 / 异常（如投喂机卡壳），自动切换备用设备，同时通过微信 / 钉钉推送故障告警，触发 “临时手动调节模式”。
报表制作：OpenClaw 调用养殖平台 API、本地传感器数据库、硬件日志文件，无需人工汇总，定时（如每天凌晨 3 点）自动拉取数据并生成报表。如成本分析报表。

6. 常见问题

6.1 配置问题

Q: 配置文件修改后不生效？
A: 重启gateway和onboard

6.2 性能问题

Q: 响应速度慢？
A: 检查模型选择、网络连接和系统资源使用情况。

Q: 内存使用过高？
A: 调整会话重置策略，清理过期会话和缓存。

6.3 安全问题

Q: 如何确保工具安全？
A: 启用沙盒、限制工具权限、验证所有输入。

Q：提示词注入问题？
上下文隔离，用户消息、系统指令、工具结果各自带有来源标记，互相分开，不容易被混淆。
选用越强的模型，官方推荐能调用工具的 Agent 用最强的模型（如 Claude Opus 4.6），因为越强的模型越不容易被忽悠。如果用小模型省成本，就要配合更严格的沙箱和权限限制。

7. 参考资源

官方文档：https://docs.openclaw.ai
GitHub 仓库：https://github.com/openclaw/openclaw
https://deepwiki.com/openclaw/openclaw

片刻

闲言碎语

ban的小记