养虾 OpenClaw 2.0 完整教程

适用版本：OpenClaw 2.0（稳定版 2026.8.1）｜官网：https://openclaw.ai/

一、认识 OpenClaw 2.0

OpenClaw 是一个开源 AI 助手/代理框架：本地跑一个 Gateway（网关），用自然语言驱动 Agent 帮你读写文件、执行命令、操作浏览器、收发消息、管理日程，并通过你惯用的模型（Claude / GPT / Gemini / DeepSeek / 本地模型）完成推理。

2.0 是它迄今最大的一次更新，核心变化可归纳为「安装更省心、界面更聚焦、协作更真实、维护更规范」：

维度	2.0 的关键变化
🆕 安装	引导式安装，自动扫描并复用已有的 Codex / ChatGPT / Claude CLI 登录、API Key、Ollama / LM Studio 本地模型
🆕 验证	选定模型后用真实请求做一次连通测试，验证通过才保存配置
🆕 界面	Control UI 重写为 chat-first 结构，对话居中、工具结果并排展示
🆕 会话	会话与转录记录迁入 SQLite，支持全文检索，1 秒定位历史节点
🆕 隐身会话	Incognito 模式：会话仅存 Gateway 内存，重启即消失，不写入磁盘记录
🆕 记忆	Memory 独立管理页，支持从 Codex / Claude Code / Hermes 导入历史记忆
🆕 Skills	从「能装」升级为创建→检查→安装→调用→修改的完整流程
🆕 浏览器	独立浏览器 + Chrome 扩展共享标签页两种控制方式，授权范围更清晰
🆕 协作	Shared Cloud Sessions 共享云会话，上下文可跨设备/Worker 无缝迁移
🆕 权限	只读 / 提建议 / 直接执行三级分级，Private Credential Request 隔离敏感信息
🆕 自动任务	统一为 Automations，运行记录分「执行/送达/完成」三阶段展示
🆕 安全	`openclaw security audit` 一键审计入站访问、工具影响半径、网络暴露

二、快速安装部署

2.1 环境准备

前置条件	说明
Node.js	推荐 24（24.15+），最低 22.22.3+，也可用 25.9+
Git	部分安装方式依赖，建议配置到系统 Path
模型入口	三选一：已有 AI 服务登录 / API Key / 本地模型（Ollama、LM Studio）
网络	首次部署需联网加载基础依赖

✅ 校验命令：node --version

2.2 安装命令

打开终端，直接粘贴执行官方命令，全程约 1–2 分钟：

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

# Windows（PowerShell）
iwr -useb https://openclaw.ai/install.ps1 | iex

也可通过 npm 安装：

npm i -g openclaw

⚠️ Windows 用户也可从官网直接下载桌面版安装包（x64 / ARM64），一键装好 gateway、chat、setup 等全部组件。

2.3 首次启动：Quickstart 快速入门

首次启动选择 Quickstart 模式，系统会自动完成三件事：

复用已有登录 —— 自动识别本机已验证的 Codex、ChatGPT、Claude CLI 登录状态并复用；
发现本地模型 —— 自动探测已安装的 Ollama、LM Studio 本地模型，验证可用后直接完成配置，无需手动逐项填写；
直入首次对话 —— 配置完成后立即进入对话，渠道、自动任务、设备等高级设置留到之后逐步补全。

命令行等价操作：http://AIDeepTHi点nk.cn

openclaw onboard          # 运行新手引导
openclaw gateway          # 启动 Gateway（默认监听 18789 端口）
openclaw dashboard        # 浏览器打开 Control UI

2.4 本地模型自动发现（Ollama / LM Studio）

步骤	操作
①	确认 Ollama / LM Studio 服务处于正常运行状态
②	首次启动选择 Quickstart，系统自动扫描并列出可用本地模型
③	选定模型后发起一次真实测试，返回结果即验证成功
④	若未识别到，重启 OpenClaw 后重新扫描

三、模型密钥配置

3.1 密钥获取途径

OpenClaw 2.0 支持多种模型入口，可按需选择：

途径	说明	是否需填 Key
复用已有登录	复用本机 Codex / ChatGPT / Claude CLI 的登录凭据	❌
API Key	在模型供应商官方控制台申请	✅
本地模型	Ollama / LM Studio，零成本离线运行	❌

✅ 供应商官方密钥入口（以官方控制台为准）：

供应商	控制台地址
Anthropic（Claude，推荐）	console.anthropic.com
OpenAI（GPT）	platform.openai.com
Google（Gemini）	aistudio.google.com
DeepSeek	platform.deepseek.com
OpenRouter	openrouter.ai

3.2 配置步骤

前往对应模型供应商官方控制台，创建 API Key；
为密钥设置自定义标签（例如 penClaw），便于后续识别和管理；
复制生成的密钥内容；
回到终端的新手引导，在 API Key 配置分区粘贴密钥；
系统会用该模型发起一次真实请求完成连接验证，验证通过才保存配置。

3.3 网页端模型管理（Model Setup）

配置完成后，可在网页端 Settings → Model Setup 进一步管理：http://AIDeepTHi点nk.cn

能力	说明
凭据来源	显示凭据来自配置文件、环境变量还是登录状态，不会重新展示完整密钥
多模型	可设置主模型、备用模型、工具模型
连接测试	可对任意模型单独发起连通测试
失效恢复	模型失效时回到此处重新检测，无需手动改配置文件

⚠️ 建议：密钥仅存于本地（~/.openclaw/credentials/），切勿上传到公开网盘或代码仓库。http://AIDeepTHi点nk.cn

四、浏览器端基础使用

4.1 打开 Web 端

openclaw dashboard

浏览器会自动打开 Control UI（对话优先主界面）。http://AIDeepTHi点nk.cn

4.2 对话优先主界面

区域	功能
侧边栏	统一收纳所有会话
主区域	当前对话居中展示
并排面板	文件变更、终端输出、Git 差异、工具调用结果自动在对话旁并排展示

4.3 触发 Agent 执行任务

在输入框直接发送自然语言指令，Agent 即会执行对应任务，例如：

总结一下 ~/README.md 的内容
帮我创建一个监控 CPU 占用超过 80% 就告警的 Python 脚本
最近 git 有哪些改动？

文件改动、终端输出、Git 差异、工具调用结果会成对展示在对话旁，长任务持续显示进度，需确认的操作在原位处理。

4.4 `/btw` 侧边对话

输入 /btw 命令可开启一段独立的多轮侧边对话：

特性	说明
用途	补充讨论细节，不污染主线会话记录
隔离性	与主线上下文分开，主线始终清晰
典型场景	追问某个实现细节、试探性方案讨论

五、进阶功能

5.1 隐身会话（Incognito）

新建会话时可开启 Incognito 模式，适合临时、敏感、不希望留痕的对话：

特性	说明
存储位置	仅保存在 Gateway 进程内存中
生命周期	Gateway 重启后消失，不写入常规会话记录与自动记忆
默认状态	默认关闭

⚠️ 边界要清楚：Incognito 解决的是「本地持久化」问题，不是完全隔离——模型服务商仍会收到对话内容，工具仍可能写文件、改外部系统，Gateway 运行者也可能看到正在进行的工作。

5.2 记忆（Memory）管理

2.0 把 Memory 做成了独立页面：http://AIDeepTHi点nk.cn

能力	说明
概览	集中查看记忆条目
记忆搜索	按 Agent 搜索已索引内容，结果显示来源、相关分数、匹配片段
原文展开	工作区记忆文件可展开查看命中原文位置
历史导入	支持从 Codex、Claude Code、Hermes 导入历史记忆（分预览、执行两阶段，不改动原始来源）

⚠️ 跨会话记忆是否启用取决于安装方式与隔离设置；若配置了 DM 隔离，跨会话记忆会关闭。

5.3 Skills 技能流程

Skills 用于保存可反复执行的工作方法（如「公众号选题 → 事实核查 → 写作 → 配图 → 排版」打包成一个 Skill）。2.0 把各环节串成完整流程：

环节	说明
创建	从实际工作沉淀可复用步骤
检查	格式错误/依赖缺失的 Skill 单独标记，不影响其他 Skill
安装/配置	ClawHub 发现 + Skill 设置，集中在 Plugins 入口
调用/修改/复查	切换 Agent/模型/连接器后列表随 Gateway 重载
Skill Workshop	从实际工作与持续修改中整理建议，先形成待处理提案，由所有者决定应用/拒绝/隔离

5.4 浏览器控制

两种使用方式，授权范围更清晰：

方式	说明
独立浏览器	OpenClaw 管理的独立浏览器环境，与日常浏览器隔离，适合 Agent 持续完成网页任务
Chrome 扩展	官方扩展共享用户明确选择的标签页，每个共享标签页可有独立 Copilot；Agent 只能操作该标签页，不获其他标签页访问权

⚠️ 页面/选中文字/文档的「一次性发送」只传递当前内容，不会自动变成持续访问权限。

5.5 多渠道接入

除 Web 端外，可连接消息渠道，从手机直接对话：

渠道	说明
Telegram	配置最快（只需一个机器人令牌）
WhatsApp / Discord / Slack	官方支持渠道

5.6 Automations 自动任务

2.0 统一叫 Automations：http://AIDeepTHi点nk.cn

能力	说明
运行记录	分别显示「任务是否执行、结果是否送达、请求是否完成」三阶段
重启恢复	Gateway 重启后，确实错过的任务可恢复；已完成/已删除/旧调度器的任务不会重复执行
边界	无法保证外部系统操作只执行一次——涉及付款、发布、删除、通知时，仍需外部系统幂等或人工确认

六、多人协作

6.1 Shared Cloud Sessions 共享云会话

开启共享云会话，将协作者加入当前会话：

能力	说明
上下文迁移	会话可在本地设备、配对机器、云端 Worker 之间无缝迁移，上下文全程不丢失
完整接手	参与者直接在完整上下文基础上接手任务，无需重新梳理背景
历史搜索	通过精确单词/短语搜索历史对话，1 秒定位关键信息

6.2 三级权限分级

会话所有者按需为成员分配权限：http://AIDeepTHi点nk.cn

权限级别	能力	适用角色
🔹 只读	仅查看会话进展	观察者、外部评审
🔹 提建议	在主线会话旁补充评论	产品、评审、测试
🔹 直接执行	完整接手 Agent 操作	主执行开发、负责人

⚠️ 权限在 Gateway 端执行，不能只靠前端按钮判断。官方明确声明：这些控制项不是租户隔离、不构成安全边界，权限撤销后界面刷新前可能仍短暂显示可用。

6.3 敏感信息隔离

机制	说明
Private Credential Request	API 密钥、内部敏感数据不进入公共会话上下文
凭据可见性	仅会话所有者可查看完整凭据
底层隔离	从底层避免信息泄露

6.4 会话生命周期管理

策略	说明
及时归档	任务完成后归档共享云会话
Worker 休眠	云端 Worker 自动休眠释放算力
自动清理	闲置超 7 天的会话可自动清理

6.5 典型协作场景

场景	落地方式
开发团队接力开发	本地启动 → 同步云端 Worker → 下班交接异地同事 → 对方直接接手，上下文零丢失
跨角色项目评审	产品/开发/测试同接一个会话，实时查看需求文档、代码变更、测试报告，就地补充意见
远程技术支持	技术人员接入用户共享会话，在保留操作上下文的前提下定位问题，减少重复沟通

6.6 协作效率优化技巧

技巧	说明
优选闲置云服务器作 Worker	承载多成员并发操作，避免本地算力不足
用 `/btw` 讨论细节	不污染主线核心会话记录
SQLite 全文检索	1 秒内定位历史操作节点与讨论内容

6.7 协作避坑注意事项

注意事项	建议
多人并发写入冲突	设 1 名主执行成员，其余成员以提建议/评审为主
误操作风险	开启重要任务前先创建会话快照，出错可回滚
网络稳定性	所有成员网络保持稳定，避免代理中断导致同步失败

七、升级与安全

7.1 升级前：全量备份

从旧版本升级前，必须先通过 CLI 导出所有旧格式转录文件完成全量备份：

mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify

⚠️ 备份可能包含凭据、登录状态与渠道信息，保存目录应限制为本人可读。

7.2 升级流程

openclaw --version            # ① 确认当前版本
openclaw update --dry-run     # ② 预览更新（不改配置、不重启）
openclaw update               # ③ 正式更新
openclaw --version            # ④ 更新后校验
openclaw doctor               # ⑤ 健康检查

✅ 稳定用户目标版本为 2026.8.1；不要因版本号数字更大就切到 beta（详见 9.2）。

7.3 升级后：安全审计

openclaw security audit

一键检查以下项目，确认无误后再投入使用：http://AIDeepTHi点nk.cn

审计项	说明
入站访问	检查外部可达的入口
工具影响半径	检查 Agent 可触及的系统范围
网络暴露	检查暴露在公网的服务
浏览器控制暴露	检查浏览器自动化权限
插件白名单	检查已加载插件

7.4 降级注意事项

要点	说明
版本兼容	旧版 OpenClaw 无法读取 2.0 创建的会话记录（会话已迁入 SQLite）
降级前	再次确认已完成全量数据归档
回退操作	涉及会话 SQLite 迁移，需用当前版本 CLI 恢复归档的旧格式转录文件

八、常见报错排查

8.1 下载与安装类

报错现象	修复方案
无执行权限报错	右键程序文件 → 属性 → 勾选「解除锁定」→ 以管理员身份运行
环境变量缺失报错	检查系统 Path 是否包含 Git、Node.js 目录；缺失则配置路径，或卸载重装 Node.js 自动补全
安装包解压失败	关闭杀毒软件（360、腾讯电脑管家、火绒、Windows Defender 实时防护）后重新解压
安装路径报错	确认路径为纯英文，不含中文、空格、`￥`/`&` 等特殊符号；推荐 `D:\OpenClaw`

8.2 启动与服务类

报错现象	修复方案
Gateway 一直离线	确认路径纯英文 → 点击右上角重启服务 → 以管理员身份重启软件
启动无反应、闪退	关闭安全防护软件 → 重新解压安装包 → 右键「以管理员身份运行」
初始化网络报错	关闭本机代理、VPN，保持网络通畅（首次部署需联网加载依赖）
Windows SmartScreen 拦截	点击「更多信息」→「仍要运行」继续（陌生开源程序的常规安全提醒）
端口冲突（18789 被占用）	`lsof -i :18789` 查占用进程 → 停掉该进程，或在 `~/.openclaw/openclaw.json` 修改 `gateway.port`

8.3 功能使用类

报错现象	修复方案
指令无法发送、界面卡死	等待 Gateway 服务完全显示在线后再操作（初始化未完成会致功能失效）
升级后会话丢失	升级前已用 CLI 导出旧格式转录文件；旧版无法读取 2.0 会话，降级前先归档
多人协作会话无法同步	确认所有参与者未开代理拦截 → 重启共享云会话服务
本地模型识别失败	确认 Ollama / LM Studio 正常运行 → 重启 OpenClaw 后重新扫描
Chrome 扩展版本不一致	`openclaw browser doctor --browser-profile chrome` → 在 `chrome://extensions` 重新加载扩展；仍提示则完整退出并重启 Chrome

8.4 更新/回退类

场景	修复方案
更新失败	保留完整错误信息 → `openclaw doctor` + `openclaw gateway status --deep` → 修好 Doctor 报告的问题 → 重新 `openclaw update`
npm 安装阶段失败	`curl -fsSL https://openclaw.ai/install.sh \| bash -s -- --install-method npm` 重新全局安装
pnpm 11 装的 2026.7.1 无法更新	先 `pnpm add -g --allow-build=openclaw openclaw@latest`，之后即可用 `openclaw update`
需要回退	`npm view openclaw versions --json` 查版本 → `openclaw update --tag --dry-run` 预览 → `openclaw update --tag 2.0`
回退前恢复旧会话	`openclaw gateway stop` 后执行 `openclaw doctor --session-sqlite restore --session-sqlite-all-agents`

8.5 进阶修复方案

方案	说明
`openclaw security audit`	一键检查入站访问、工具影响半径、网络暴露，定位安全配置问题
完全重装	卸载旧版 → 清理残留配置文件 → 关闭安全软件 → 重装最新 2.0，可解决 90% 以上顽固异常

九、避坑清单

9.1 安装/升级

坑	规避方式
升级会结束进程内的终端会话，且不自动恢复	重要命令先执行完或保存输出，再升级
前台运行的 Gateway 不会被 `update` 自动替换	先手动停止前台进程，更新后再启动
备份包含敏感信息	保存目录限制为本人可读，不上传公开网盘/代码仓库
Docker / Podman / K8s 部署不适用 `update`	替换容器镜像，按原部署方式处理挂载状态与启动检查

9.2 版本号

坑	规避方式
beta 版本号陷阱	官方说明 `2026.9.1-beta.1` 实际对应 `2026.8.1-beta.4`，不要因数字更大就切 beta；稳定用户坚守 `2026.8.1`

9.3 安全边界

坑	规避方式
协作权限不是安全边界	官方明确：只读/建议/执行控制不是租户隔离，敏感操作仍需自建约束
Incognito 不是完全隔离	模型商仍收到内容、工具仍能写文件，敏感操作别仅靠隐身会话
自动任务无法保证「只执行一次」	付款/发布/删除/通知类任务，外部系统需幂等或人工确认

9.4 模型与对抗提示注入

坑	规避方式
模型越强≠绝对安全	参考官方引用数据：Claude Opus 4.5 被攻破率 0.5%、Sonnet 4.5 1.0%、Haiku 4.5 1.3%、Gemini 2.5 Pro 8.5%
模型选择只是第一道缓解	面对适应性人类攻击者，工具策略、执行审批、沙箱才是真正强制层

附录：命令速查表

命令	作用
`openclaw onboard`	运行新手引导
`openclaw gateway`	启动 Gateway（默认端口 18789）
`openclaw dashboard`	打开浏览器 Control UI
`openclaw chat "..."`	命令行发起对话
`openclaw --version`	查看当前版本
`openclaw update`	升级（建议先 `--dry-run` 预览）
`openclaw backup create --output <dir> --verify`	创建并校验备份
`openclaw doctor`	健康检查与配置迁移
`openclaw security audit`	安全审计
`openclaw browser doctor --browser-profile chrome`	检查 Chrome 扩展状态
`openclaw doctor --session-sqlite restore --session-sqlite-all-agents`	回退前恢复旧会话记录

总结：OpenClaw 2.0 的演进逻辑是「安装先找现有模型、使用围绕一次对话、维护靠明确命令」。按「确认版本 → 全量备份 → 预览更新 → 正式更新 → 运行检查」的顺序操作，升级时不要跳过备份，也不要误把 beta 版本号当成稳定版。 http://AIDeepTHi点nk.cn