龙虾的安装与初始化

Posted on In
详细介绍如何在 Mac 上安装和配置 OpenClaw，通过八个步骤快速上手这位 AI 工作搭档。

系列目录

龙虾的安装与初始化

前言

这个系列，我想认真聊聊 OpenClaw 这个工具——不是那种泛泛而谈的”AI助手推荐”，而是实打实的、怎么用它干活的记录。

用了一段时间下来，我越来越觉得，把 OpenClaw 叫做”助手”其实不太准确。它更像是你办公桌上那个永远在线的搭档——能读写你的文件、能帮你跑命令行、能记住项目上下文。它不是来回答”今天天气怎么样”的，它是来帮你把事情往前推进的。

好了，直接进入正题，这篇先从安装说起。

一、什么是 OpenClaw

简单说，OpenClaw 是一个跑在终端里的 AI 助手框架。几个核心能力：

  • 直接操控电脑 — 读写文件、执行命令、管代码仓库
  • 持久记忆 — 知道你是谁、你的偏好、你的项目进展
  • 技能扩展 — 装个 Skill 就能解锁新能力
  • 多平台 — macOS 体验最好，Linux 也能跑

把它想象成一个从不摸鱼、从不健忘的工作搭档，就差不多了。

二、装好之后能用它做什么？

2.1 使用场景举例

  • 管项目 — 帮你创建项目结构、写代码、做 Git 提交推送、跑 CI/CD
  • 写文章 — 帮你列大纲、写正文、维护系列文章、推送到飞书知识库
  • 做调研 — 帮你搜资料、读文档、总结要点、整理成报告
  • 管知识 — 帮你维护 MEMORY.md、更新项目变更日志、同步到飞书
  • 自动化日常 — 帮你设置定时任务、自动汇报、监控项目状态

2.2 管项目 — 具体交付结果

  • 项目文档体系 — 自动生成 0001_项目设计.md、0002_技术设计.md、0003_变更日志.md，带序号和规范模板
  • Git 双端同步 — 配置 Gitee + GitHub 双平台推送，一句 git pushall 同时推两边
  • 飞书知识库同步 — 文档自动同步到飞书，对应节点链接实时可查
  • 模块化代码结构 — 按设计文档自动创建项目目录结构，模块划分清晰
  • CI/CD 流水线 — GitHub Actions 自动部署，状态实时可查
  • 变更日志追踪 — 每次变更即时记录，附带时间戳和变更内容摘要

2.3 它能帮到谁？

  • 独立开发者 — 一个人管项目，环境重建、分支管理、部署发布全链路覆盖
  • 写作者 — 管理系列文章、保持上下文一致、跨平台同步（Hexo + 飞书）
  • 研究者 — 调研整理、回测分析、文档归档，过程全留痕
  • 项目负责人 — 用双区工作流管理临时需求和长期项目，变更不遗漏

三、怎么用好它？

3.1 Agent的工作区基础结构

OpenClaw 官方建议把 ~/.openclaw/workspace/ 目录推到远端 Git 来管理你的「记忆」和「配置」。这个目录里装的是：

  • 协作文档 — 定义你和 AI 的协作方式（SOUL.md、AGENTS.md）
  • 项目文档 — 各个项目的设计、日志、变更记录
  • 记忆文件 — 每日会话记录、长期记忆（MEMORY.md）

推送到远端后，换机器或重装时能一键恢复，不用从头配置。

3.2 OpenClaw系统架构拓扑图（可跳过阅读，有需要再回来看）

3.2.1 核心层

  • Gateway — 路由层，接收请求、分发处理
  • Agent — 推理层，调用 Skills、读写 Workspace、管理 Subagents

3.2.2 Agent 交互对象

  • Skills — feishu-doc/wiki/drive、github、weather、taskflow 等
  • Workspace — ~/.openclaw/workspace/
  • Subagents — 任务执行单元（异步并行）
  • Memory — 记忆系统：MEMORY.md、每日 memory/

3.2.3 Workspace 内容

  • MEMORY.md — 长期记忆
  • AGENTS.md — 协作规范
  • SOUL.md — 角色定义 + 协作规则
  • IDENTITY.md — 身份标识
  • USER.md — 用户信息
  • TOOLS.md — 工具配置
  • HEARTBEAT.md — 心跳追踪
  • projects/ — 扩展工作区（ai-blog、news-recommendation-system等）

3.2.4 外部集成

  • Feishu — 消息通道
  • GitHub / Gitee — 代码托管

3.2.5 主数据流

1
2
3
4
5
6
7
Feishu 消息 → Gateway → Agent
 ├→ Skills（能力调用）
 ├→ Workspace（文件/记忆读写）
 ├→ Subagents（任务派生）
 └→ Memory（记忆系统）

Agent → 处理结果 → Gateway → Feishu/外部

3.2.6 Git CI/CD 流程

1
2
3
4
5
6
7
8
GitHub/Gitee push
     ↓
GitHub Actions
  ├→ 语法检查/测试
  ├→ 构建
  └→ 部署（FTP/SFTP）→ 生产环境/云服务器
     ↓
触发通知 → Feishu/Email

3.2.7 飞书文档知识库归档流程

1
2
3
4
5
6
7
本地文档更新
     ↓
feishu_doc/write → feishu_wiki/sync
     ↓
写入飞书知识库对应节点 → 返回文档链接
     ↓
记录到 MEMORY.md / 变更日志

四、我的安装环境

说一下我自己的配置，不是什么标准答案，纯粹是给大家一个参考。

我的配置：

  • 系统：macOS（Apple Silicon M系列）
  • 包管理：Homebrew
  • Node 版本：Node.js 24（官方推荐 v24）
  • Git：Homebrew 安装的最新版

为什么这样选：

Homebrew 就不说了，macOS 上装工具基本靠它，省心。Node 选 LTS 是因为稳定，我不想在工具本身上折腾。Git 也是通过 Homebrew 装，比系统自带的版本新，而且路径干净。

五、安装步骤

整个流程三步，按顺序来就行。

5.1 装 Homebrew

macOS 上没有 Homebrew 就像厨房没有锅，先把它搞定。

国内用户推荐用这个脚本，镜像源速度很快：

1
/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

运行之后按提示选「中科大」镜像，一路确认就行。

海外用户直接用官方源：

1
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

装完验证一下：

1
brew --version

看到 Homebrew 4.x.x 之类的版本号就 OK 了。

5.2 装 Node.js

OpenClaw 是跑在 Node.js 上的，所以这个必须装。

直接去 nodejs.org/dist/下载安装就行，官网推荐装 v24 版本，我实际装的也是 v24。去官网首页，选适合自己系统的版本点下载，装完就行，不需要额外配置。

国内用户建议顺手把 npm 镜像切换一下，否则后面装东西慢得让人怀疑人生：

1
npm config set registry https://registry.npmmirror.com

验证：

1
2
node -v
npm -v

两个命令都有输出就说明装好了。

5.3 装 OpenClaw

终于到了主角登场。

方式一：官方安装脚本（很慢）

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

方式二：npm 全局安装（推荐）

1
sudo npm install -g openclaw@latest

验证：

1
openclaw --version

有版本号输出就说明装好了。

六、初始化配置

装好了还不行，得跑一个初始化流程把它配置好。

6.1 启动服务

1
openclaw start

6.2 进入初始化向导

1
openclaw onboard

向导会带着你完成几件事：设置语言时区、连上 AI 模型、填一些基本参数。

这里会需要你提供 API Key，务必保管好，不要随手发到网上去。配置文件中可以用 [你的API密钥] 这种占位符代替。

6.3 让配置生效

1
openclaw gateway restart

6.4 接入飞书（高版本这一步现在支持在onbord配置时直接飞书扫码配置了，提前创建好机器人和分配权限即可）

如果你日常用飞书沟通，可以把 OpenClaw 直接接进飞书频道，这样就能在飞书里和它对话了。整个过程分四步：

6.4.1 创建机器人

去飞书开放平台（https://open.feishu.cn/app），点「创建企业自建应用」，填好名称和描述，创建完成之后进入应用详情页。

6.4.2 配置权限

在「应用功能」→「权限管理」里，添加以下权限（按需增减，要用到知识库、文档的话增加对应的权限即可）：

  • im:message — 发送消息
  • im:message.receive_v1 — 接收消息
  • im:message.group_at_msg — 接收群聊@消息
  • im:message.p2p_msg — 接收单聊消息
  • im:chat — 获取群组信息

权限越少越安全，建议只加你实际用到的。

6.4.3 获取凭证

在「凭证与基础信息」页面，找到你的 App ID 和 App Secret。

⚠️ App Secret 是敏感信息，不要发到网上或截图分享。

6.4.4 连接到 OpenClaw（高版本这一步现在支持在onbord配置时直接飞书扫码配置，可忽略）

在 OpenClaw 的配置文件里，找到飞书相关的配置项，填入你的应用凭证：

1
2
3
feishu:
  app_id: [你的 App ID]
  app_secret: [你的 App Secret]

填好之后重启网关让配置生效：

1
openclaw gateway restart

重启成功的话，就能在飞书里找到你的 OpenClaw 机器人，给它发消息了。后续还可以在飞书开放平台配置机器人的名称、图标，让它看起来更正式。

七、验证安装 + 版本化管理工作区

7.1 验证安装

访问下面的地址，出现正常的web管理后台证明安装成功了

1
http://127.0.0.1:18789/

7.2 验证消息通道

最后通过飞书发个消息确认一下一切正常。

输入：

1
你好，简单介绍一下你自己。另外介绍下当前的状态和skill有哪些？

正常回复的话，恭喜你，安装成功了！

7.3 装 Git远程版本化管理你的工作区（可以让小龙虾帮你装）

Git 是 OpenClaw 管理项目会用到的工具，版本管理必备：

1
brew install git

装完验证：

1
git --version

如果你经常从 GitHub 拉代码，推荐设一个全局配置，省得每次都要配 SSH：

1
git config --global url."https://github.com/".insteadOf ssh://git@github.com/

这样 Git 会自动把 SSH 地址转成 HTTPS，省心。

7.3.1 进阶：配置双端推送（Gitee + GitHub）

OpenClaw 官方文档里专门提到，Workspace 目录（~/.openclaw/workspace/）值得推送到远端 Git 仓库来管理。原因很简单：这个目录里装的是你的「记忆」和「配置」——

  • 协作文档 — SOUL.md、AGENTS.md、MEMORY.md 这些定义了你和 AI 的协作方式
  • 项目文档 — 各个项目的设计、日志、变更记录
  • 记忆文件 — 每日会话记录、长期记忆

推送到远端后，换机器或者重装时能快速恢复环境，不用从头配置。

如果你想同时推两个平台，可以这样配置：

1
2
3
4
5
6
7
8
# 查看当前 remote
git remote -v

# 添加 Gitee（如果还没有）
git remote add gitee https://gitee.com/你的用户名/仓库名.git

# 配置别名方便推送
git config --global alias.pushall '!f() { git push origin master && git push gitee master; }; f'

之后用 git pushall 就能同时推两个平台了。

⚠️ 安全建议：Token 不要放在 URL 里

配置 Git 认证时，Token 不要直接写在 remote URL 里（如 https://token@github.com/...），容易被 git log 或 ps aux 暴露。

推荐做法：用上面的 url.insteadof 配合 GitHub Personal Access Token（PAT）存储在 git credential store 里。

7.3.2 安装 GitHub CLI（可以让小龙虾帮你装）

如果你需要管理 GitHub 仓库（比如创建仓库、查看 CI 状态），可以装一下 GitHub 官方 CLI：

1
brew install gh

验证：

1
gh --version

登录认证：

1
gh auth login

选 GitHub.com → HTTPS → 登录即可。登录后用 gh repo create 等命令操作仓库就很方便。

后面的项目管理也需要用到仓库创建的权限，所以希望自动在github创建仓储，可以安装下gh，并配置对应的token权限，这些配置工作可以让小龙虾去做，你只用去github个人账号管理页面创建对应的token即可。

八、下一步

安装搞定了，接下来该了解怎么用它了。下一篇会聊：

  • OpenClaw 的角色定位 — 它不是搜索引擎，是执行者
  • 双区工作方式 — 临时区和项目区怎么选
  • 三阶执行流程 — 规划、执行、沉淀怎么走
  • 协作话术示例 — 怎么说需求，龙虾才能听懂

有问题欢迎留言，我们下篇见。