新手必看！OpenClaw AI助手零基础安装指南

教程 OpenClaw AI 安装指南
AI教程
发布日期:   2026-03-11
文章字数:   3.6k

面向刚接触 OpenClaw 的开发者/折腾党：从安装、配置、渠道接入，到 Skills、Workspace、常见问题排查，尽量一次讲清楚。

一、OpenClaw 是什么？

OpenClaw 是一个本地优先（local-first）的个人 AI 助手网关。

它的核心价值，不只是“和 AI 聊天”，而是把下面几件事整合在一起：

  • 多渠道接入：Telegram、Discord、Slack、Signal、iMessage、Google Chat、WhatsApp、WebChat 等
  • 本地工作区：把提示词、记忆、人格、技能放在你自己的机器里
  • 工具能力：文件读写、命令执行、浏览器控制、网页抓取、Canvas、多会话等
  • 可扩展技能系统：通过 Skills 给助手增加联网搜索、图像生成、GitHub 操作等专门能力

如果你熟悉一些概念，可以把它类比成：

  • 一个长期运行的 AI Gateway
  • 一个带工作区和记忆系统的 Agent Runtime
  • 一个能接到聊天软件里的本地 AI 基础设施

一句话概括：

OpenClaw 不是一个“单独的聊天界面”，而是一套能让 AI 助手长期运行、持续记忆、可扩展能力、可接入现实渠道的系统。

二、OpenClaw 的基本架构

从使用角度看，OpenClaw 的架构可以拆成 4 层：

  1. Channels（输入输出）
  2. Gateway（核心控制平面）
  3. Agent Runtime（会话与工具执行）
  4. Workspace / Skills（上下文与能力扩展）

2.1 Channels：消息从哪里来、回到哪里去

OpenClaw 可以接入多个渠道，例如：

  • Telegram
  • Discord
  • Slack
  • Signal
  • iMessage
  • Google Chat
  • Web 控制台
  • CLI

你给 bot 发消息，本质上是渠道把事件交给 Gateway；Gateway 再决定把这条消息路由给哪个 agent、哪个 session、是否允许执行、是否触发工具。

2.2 Gateway：整个系统的大脑

Gateway 是 OpenClaw 的核心。

它负责：

  • 读取 openclaw.json
  • 装载 agent 配置
  • 装载 workspace 与 skills
  • 管理各渠道连接
  • 做权限控制与配对（pairing）
  • 路由会话
  • 驱动工具调用

最常用的 Gateway 管理命令：

openclaw gateway status
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

如果你要调试问题，这四个命令基本天天会用。

2.3 Agent Runtime：实际回复与执行发生的地方

当一条消息进入系统后，OpenClaw 会把它交给某个 agent 的运行上下文。

这里会涉及：

  • 当前模型
  • 当前 session 历史
  • workspace 上下文
  • 已加载 skills
  • 可调用工具
  • 安全边界（比如 sandbox）

所以 OpenClaw 的“回答质量”，本质上并不只取决于模型，还取决于：

  • 工作区写得好不好
  • 会话策略是否合理
  • 技能是否干净
  • 安全策略是否挡住了错误行为

2.4 Workspace / Skills：长期可持续使用的关键

OpenClaw 最有意思的地方，在于它把“长期上下文”做成了文件系统的一部分。

常见工作区路径：

~/.openclaw/workspace

而 Skills 则是对能力边界的扩展。

所以可以这样理解：

  • Workspace 决定它像不像“你的助手”
  • Skills 决定它会不会做“更多事情”

三、安装 OpenClaw

3.1 环境要求

至少准备好：

  • Node.js 22+
  • macOS / Linux / Windows（通常推荐 WSL2）

3.2 安装方式

方式一：官方安装脚本

macOS / Linux

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

Windows PowerShell

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

方式二：npm 全局安装

npm install -g openclaw@latest

如果你本身就是 Node 用户，这种方式通常最直观。

四、第一次启动：推荐走 onboard

新手最推荐的入口不是直接手改配置，而是先跑官方引导：

openclaw onboard

如果你想把守护进程一起装好：

openclaw onboard --install-daemon

根据官方 onboard 文档，这个向导会处理：

  • 本地 / 远程 Gateway 模式
  • 模型认证
  • workspace 目录
  • 渠道接入
  • 安全选项
  • 守护进程安装

为什么先跑 onboard？

因为 OpenClaw 的配置校验是严格模式。

这意味着：

  • 未知字段可能直接导致启动失败
  • 字段类型不对会失败
  • 某些安全策略缺参数也会失败

所以最稳妥的方式是：

  1. 先 openclaw onboard
  2. 跑通一套最小可用配置
  3. 再按需改 openclaw.json

五、核心配置文件：openclaw.json

OpenClaw 的主配置文件一般在：

~/.openclaw/openclaw.json

它使用 JSON5，所以支持：

  • 注释
  • 尾随逗号

5.1 一个最小配置示例

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing"
    }
  }
}

5.2 你最常会改的几个配置块

Agent 默认配置

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      }
    }
  }
}

Session 配置

{
  session: {
    dmScope: "per-channel-peer",
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120
    }
  }
}

Telegram 渠道配置

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: {
        "*": {
          requireMention: true
        }
      }
    }
  }
}

5.3 配置读写命令

官方 CLI 提供了直接操作配置的命令：

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey

如果只是改几个值，这种方式比手工打开 JSON 稳一点。

六、Workspace：OpenClaw 的长期上下文系统

如果你只把 OpenClaw 当命令行工具用，那你会低估它。

它真正强的地方，在于 Workspace。

6.1 典型目录结构

~/.openclaw/
├── openclaw.json
├── workspace/
│   ├── AGENTS.md
│   ├── SOUL.md
│   ├── USER.md
│   ├── TOOLS.md
│   ├── IDENTITY.md
│   ├── MEMORY.md
│   └── skills/
├── skills/
└── credentials/

6.2 这些文件分别干什么

AGENTS.md

描述行为约束、连续性规则、记忆策略、边界条件。

SOUL.md

定义风格、人格、语气、做事方式。

USER.md

记录用户信息与长期偏好，比如：

  • 称呼
  • 时区
  • 项目背景
  • 习惯与禁忌

TOOLS.md

存一些本地环境相关信息，比如：

  • 设备名
  • SSH 别名
  • 目录习惯
  • 常用命令说明

MEMORY.md

长期记忆，适合放“跨会话仍然重要”的事实。

6.3 为什么这套设计很关键？

因为这决定了你的助手会不会越来越“像你的人”。

很多 AI 产品的问题在于：

  • 每次都是新开始
  • 项目背景要反复解释
  • 风格没有连续性

而 Workspace 本质上是把这些长期上下文外化到了文件系统。

对开发者来说，这很友好：

  • 可版本管理
  • 可审阅
  • 可编辑
  • 可迁移

七、最实用的启动路径：先本地，再接渠道

我建议新手按这个顺序来，不容易迷路。

第一步：检查 Gateway 状态

openclaw gateway status

第二步：打开 Dashboard

openclaw dashboard

Dashboard 是非常适合做第一轮验证的。

因为如果 Dashboard 都打不开，你就别急着怀疑 Telegram token 了——大概率基础服务就没起来。

第三步：用 CLI 直接发一条消息

openclaw agent --message "帮我整理今天待办"

如果这一步能正常跑，说明：

  • Gateway 基础通路没大问题
  • 模型认证大概率可用
  • agent 基本配置可用

第四步：再接 Telegram / Discord

这是更稳的方式。

八、Telegram 接入实战

Telegram 是 OpenClaw 最适合个人用户的入口之一。

8.1 创建 Bot

在 Telegram 里联系 @BotFather：

  • /newbot
  • 按提示创建 bot
  • 保存 token

8.2 配置 Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: {
        "*": {
          requireMention: true
        }
      }
    }
  }
}

8.3 启动 Gateway

openclaw gateway start

8.4 批准首个 DM

官方文档中的典型流程：

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

8.5 Telegram 常见坑

坑 1：bot token 配好了，但机器人没反应

优先排查：

  1. Gateway 是否启动
  2. dmPolicy 是否允许
  3. pairing 是否已经通过
  4. token 是否填对

坑 2：群消息收不到

官方文档提到 Telegram 默认有 Privacy Mode。

如果你希望 bot 在群里看见更多消息，可以：

  • 通过 BotFather 调整 /setprivacy
  • 或把 bot 设置为群管理员

并且改完后，通常需要移出群再重新加入。

坑 3：为了省事把 dmPolicy 改成 open

这在公网环境里风险很高。

更稳妥的顺序是：

  • 开发阶段：pairing
  • 自己稳定使用后：考虑 allowlist
  • 没特殊需求：别开 open

九、Skills：怎么给 OpenClaw 增加能力

9.1 Skills 的本质

OpenClaw 的 Skills 兼容 AgentSkills 规范。

一个 Skill 通常就是一个目录，至少包含：

my-skill/
└── SKILL.md

SKILL.md 里会描述：

  • 这个技能做什么
  • 什么时候用
  • 需要哪些依赖
  • 要怎么调用脚本或工具

9.2 Skills 的加载位置与优先级

官方文档给出的优先级：

  1. <workspace>/skills
  2. ~/.openclaw/skills
  3. bundled skills

即：

<workspace>/skills > ~/.openclaw/skills > bundled

这意味着：

  • 当前 agent 的 workspace 技能可以覆盖全局技能
  • 全局技能适合多 agent 共享
  • 你可以做非常灵活的隔离

9.3 技能为什么有时“装了但不可用”？

因为 Skills 不是“只要目录存在就一定加载”。

官方文档说明，技能可能会因以下条件被过滤：

  • 缺少必须的命令行依赖（requires.bins）
  • 缺少环境变量（requires.env）
  • 缺少配置项（requires.config）
  • 操作系统不匹配（os）

9.4 技能配置示例

官方文档支持在 openclaw.json 里给技能注入 env 和 apiKey：

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE"
        }
      }
    }
  }
}

9.5 安全提醒

这一点官方文档写得很明白：

把第三方技能当成不受信任代码。

换句话说，安装技能之前至少要看：

  • 来源是谁
  • 版本是什么
  • 需要哪些 env
  • 是否会运行脚本
  • 是否会做对外写操作

这不是矫情，这是正常的安全卫生习惯。

十、沙盒与安全边界

OpenClaw 的能力越强，越要注意安全。

10.1 最基本的安全建议

1）别随便开放私聊入口

优先：

  • pairing
  • allowlist

谨慎：

  • open

2）别把 API Key 直接塞进聊天上下文

更推荐：

  • 放环境变量
  • 放技能配置注入
  • 放受控配置项

3）第三方 Skills 先读再用

不要看到“能联网”“能自动发消息”就直接开。

10.2 启用沙盒

官方配置里支持 sandbox，例如：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "agent"
      }
    }
  }
}

这类配置在你开始让助手执行复杂命令、处理不可信输入时非常有价值。

一个实用原则：

当你让 AI 动手做事时，隔离通常比信任更重要。

十一、常用 CLI 命令速查

11.1 Gateway 管理

openclaw gateway status
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

11.2 配置与诊断

openclaw onboard
openclaw configure
openclaw doctor
openclaw logs --follow

11.3 配置读写

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.model.primary "openai/gpt-5.2"
openclaw config unset tools.web.search.apiKey

11.4 Dashboard

openclaw dashboard

11.5 直接发一条 agent 消息

openclaw agent --message "帮我总结今天会议"

十二、常见问题排查

问题 1：Gateway 启动失败

先跑：

openclaw doctor

再看日志：

openclaw logs --follow

通常是配置问题，而不是“系统坏了”。

问题 2：Bot 没回复

按这个顺序排查：

  1. openclaw gateway status
  2. token 是否正确
  3. dmPolicy 是否挡住了
  4. pairing 是否已批准
  5. 群组策略 / mention 要求是否挡住了

问题 3：技能装了却看不到

检查：

  • 目录位置是否正确
  • SKILL.md 是否存在
  • skill 名称是否冲突
  • 依赖的 env / bin 是否满足

问题 4：配置改了没生效

先确认：

  • 文件是不是 ~/.openclaw/openclaw.json
  • JSON5 格式是否有效
  • Gateway 是否热重载成功

不确定时，直接：

openclaw gateway restart

比空猜快得多。

十三、推荐的新手实践路径

如果你是第一次接触 OpenClaw，我建议用 4 个阶段来上手。

阶段 1：跑通基础服务

目标：本地能正常对话

步骤：

  1. 安装 OpenClaw
  2. openclaw onboard
  3. openclaw gateway status
  4. openclaw dashboard
  5. openclaw agent --message "hello"

阶段 2：接入一个消息渠道

目标：让它在 Telegram 或 Discord 里工作

步骤：

  1. 创建 bot
  2. 写最小配置
  3. 用 pairing 接入
  4. 验证私聊可用

阶段 3：经营 Workspace

目标：让它真正变成“长期助手”

步骤：

  • 完善 USER.md
  • 完善 SOUL.md
  • 补 TOOLS.md
  • 慢慢整理 MEMORY.md

阶段 4：按需加 Skills

目标：联网、自动化、第三方工具增强

步骤：

  • 先装 1~2 个高频技能
  • 看 SKILL.md
  • 配环境变量
  • 验证加载成功

十四、一个最小可运行示例

下面给一个相对保守、适合新手起步的配置：

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: []
      }
    }
  },
  session: {
    dmScope: "per-channel-peer"
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: {
        "*": {
          requireMention: true
        }
      }
    }
  }
}

这份配置的思路很明确：

  • 使用默认 workspace
  • 一个主模型
  • 每个私聊对象独立 session
  • Telegram 开启
  • DM 用 pairing
  • 群里默认要求 mention

适合做第一阶段验证。

十五、我对 OpenClaw 的真实建议

如果你准备认真用 OpenClaw，有三件事值得优先投入精力：

1. 把 Workspace 当产品来维护

别把 USER.md、SOUL.md、MEMORY.md 当摆设。

它们决定了这个助手是不是“可长期使用”。

2. 先把安全边界建好

尤其是：

  • DM policy
  • allowlist
  • 第三方 skills
  • API Key 管理
  • sandbox

这些一开始偷懒，后面都要补课。

3. Skills 少而精

不要上来装十几个“看起来很厉害”的技能。

更好的节奏是：

  • 先明确需求
  • 先验证效果
  • 再长期保留

一个干净、稳定、可信的技能集，比一堆失控的花活有用得多。

十六、参考资源

十七、结语

从工程视角看，OpenClaw 最有价值的地方不在于“它能接多少渠道”，而在于它把这些东西统一到了一个可控系统里：

  • 可配置
  • 可扩展
  • 可审查
  • 可长期维护

如果你只是想临时问几句话，普通聊天机器人就够了。

但如果你想要的是一个：

  • 跑在自己设备上
  • 有长期记忆
  • 能接真实渠道
  • 能逐步长成你自己工作流一部分的 AI 助手

那 OpenClaw 这条路，确实值得折腾。

关键词建议

  • OpenClaw 安装指南
  • OpenClaw 教程
  • OpenClaw 配置
  • OpenClaw Telegram 接入
  • OpenClaw Skills

摘要建议

这是一篇面向新手的 OpenClaw 安装与上手指南，覆盖安装、onboard、workspace、skills、Telegram 接入与常见问题排查，帮助你更快把 OpenClaw 跑起来并形成可长期使用的个人 AI 助手系统。

文章作者: 左哥
文章链接: https://zuoyy.com/2026/03/11/openclaw-install-guide/
版权声明: 本博客所有文章除特別声明外，均采用 CC BY 4.0 许可协议。转载请注明来源 左哥 !
教程 OpenClaw AI 安装指南
赏
  目录