AI | OpenClaw文档分析——如何正确抄作业

为了消除这些疑虑，我决定回归最可靠的源头——官方文档。本文将按照 OpenClaw 官方文档（https://docs.openclaw.ai/zh-CN）的章节顺序，逐一拆解各种操作背后的原理：它们到底在干什么？有什么用？注意：本文基于Windows。

一、第一步：安装 OpenClaw，到底在装什么？

1、准备工作：node.js、git、Python核心依赖与辅助工具

在正式“抄作业”之前，需要先给电脑搭好运行环境。根据 OpenClaw 官方文档，真正绕不开的只有 Node.js，Git 和 Python 则属于“按需安装”——想从源码编译需要 Git，要用到视频处理等技能才需要 Python。

Node.js —— 核心依赖，必须安装

OpenClaw 基于 Node.js （版本 ≥ 22.0.0）开发，这是无论如何都绕不开的。安装完成后，系统会多出几个重要文件夹：

• 主程序目录：C:\Program Files\nodejs\（默认路径）里面放着 node.exe（运行 JavaScript 的引擎）、npm.cmd（包管理器）等核心文件。

• 全局包存放目录：C:\Users\你的用户名\AppData\Roaming\npm（默认）当你用 npm install -g 安装全局工具时（比如后面的 OpenClaw），可执行文件就会被放到这里。这也是为什么安装完 OpenClaw 后，你可以在命令行直接敲 openclaw——因为该目录已被自动添加到系统环境变量 PATH 中。

环境管理小技巧：npm 的全局包都集中在这个文件夹里。如果某天你发现全局工具混乱了，或者想彻底重置环境，直接把这个文件夹删掉，然后重新安装需要的包即可。不需要纠结哪些文件该删、哪些该留——因为所有全局包都装在这里，删掉就等于清空了。

• 用户配置目录：C:\Users\你的用户名\.openclaw这个文件夹是在你第一次运行 OpenClaw 时自动创建的，用来存放配置文件、日志和插件。以点开头的目录在文件管理器中默认隐藏，但你可以直接在路径栏输入访问。

环境变量 —— 系统如何找到你的命令？

当你打开命令行输入 node --version 时，系统并不是满硬盘搜索 node.exe，而是去一个叫 PATH 的环境变量里“按图索骥”。PATH 里保存了一串文件夹路径（比如 C:\Program Files\nodejs\），系统会挨个进去找，找到了就执行。

安装 Node.js 时，安装程序会自动把它的主目录添加到 PATH 中，这就是为什么装完就能直接用 node 命令。同样，后续通过 npm 安装的全局工具（如 OpenClaw），其存放目录也会被自动加入 PATH，让你在任何位置都能调用。

Git —— 代码搬运工

Git的作用很纯粹——从GitHub拉取代码。安装后主要做了两件事：

• 在开始菜单添加了Git Bash（命令行工具）和Git GUI（图形界面）

• 把git命令添加到系统PATH，让你能在任何命令行窗口使用

什么情况需要Git？走源码安装时才用得到。如果用官方推荐的一键安装脚本（默认走npm路径），Git其实不是必需的。但如果你打算自己拉取最新开发版折腾，或者安装某些依赖git仓库的插件，就得装上。

安装也简单：官网下载安装包，一路“Next”到底，记得勾选“Git from the command line”那项，PATH就自动配好了。

Python —— 技能扩展包

Python是为OpenClaw的特定技能准备的。比如你想让AI分析表格、处理图片，才需要Python环境。

安装后发生的变化：

• Python主程序目录（如C:\Python39\），里面有python.exe和pip.exe

• 如果安装时勾选了“Add Python to PATH”，系统就能直接识别python命令

环境管理核心建议：使用虚拟环境Python 的包默认会安装到全局目录（比如 Lib\site-packages），不同项目混用容易产生依赖冲突。更推荐的做法是：为 OpenClaw 单独创建一个虚拟环境。这样做的好处是：如果 Python 环境搞坏了，或者想换一个干净的依赖集合，直接删除 openclaw-venv 文件夹，重新创建即可。完全不影响系统全局 Python。

这里特别提醒一下：AI 有时候很”贴心”，为了使用某个工具会自动安装大量 Python 包，眨眼间几百兆空间就没了。用虚拟环境的好处就是——随便装，装坏了删掉重来，毫无心理负担。

• 后续用pip install安装的Python包，会放在Lib\site-packages目录下

官方对Python版本有明确要求：3.8~3.10，推荐3.9。版本太高或太低都可能出问题。

2、正式安装：一键脚本到底干了什么？

准备工作做好后，真正的安装就开始了。第一步很简单——打开 PowerShell（记得用管理员身份运行）。

然后在终端里敲下这行命令：

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

这一行看起来很玄乎，拆开来看其实很简单：

• iwr 是 Invoke-WebRequest 的缩写，就是从网上下载东西——这里下载的是官方放在服务器上的安装脚本

• -useb 表示按字节处理，避免编码问题

• | iex 是管道符加 Invoke-Expression，意思是把下载下来的东西直接执行

整个操作相当于：你从官网下载了一个 install.ps1 脚本，然后双击运行它。只不过这一切在命令行里自动完成，不需要手动下载文件。

这里有个小坑需要提醒：如果是第一次在 Windows 上运行这类脚本，可能会遇到执行策略报错。这时候需要先放行一下：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

这条命令的意思是：允许运行从网上下载的本地脚本，但只对当前用户生效，不影响系统全局安全设置 。

脚本跑起来之后，它会自动做三件事：

• 检查 Node.js：如果没装或版本不对，会提示你先装好

• 通过 npm 全局安装 OpenClaw：把 openclaw 命令装到你的电脑里

• 自动进入配置向导：开始问你各种问题，比如用哪个 AI 模型、API Key 是多少

小知识：细心的读者可能会发现，官方文档里除了这行一键脚本，还写着 npm install -g openclaw@latest。其实两者是一回事——一键脚本就是给这行命令套上了一层“保姆级”的外壳。它会帮你检查 Node.js 装没装、版本对不对，装完还会自动进入配置向导。而直接 npm 安装，则需要你自己搞定这些前置条件。对于大多数新手来说，用一键脚本是最省心的选择。

装完之后，你可能会好奇：OpenClaw 到底装在哪了？

根据 npm 的规则，全局安装的包会被放在之前提到的 C:\Users\你的用户名\AppData\Roaming\npm 目录下。你可以去那里看看，openclaw 相关的文件都在里面。

接下来，脚本会自动带你进入配置环节——也就是选择 AI 模型、输入 API Key。

3、配置环节：最容易出事的几个地方

一键脚本跑完后，会自动进入配置向导（或者手动运行 openclaw onboard）。这时候看起来就是回答几个问题，但真正的坑往往藏在回答完之后。

特别提醒1：API-Key别搞丢也别泄露

配置向导会让你选择AI模型提供商（OpenAI、阿里云百炼、Anthropic等），然后输入API-Key。这一步要记住三件事：

• API-Key相当于钱——大部分模型是按token收费的，输进去之后，你的OpenClaw就有“消费能力”了。首次配置建议选有免费额度的服务商，先玩明白再考虑付费。

• 别分享、别上传——有人把配置文件贴到论坛求助，结果被刷爆账单。.openclaw目录里的配置文件要当钱包一样看好。

特别提醒2：模型选错了，后面全是泪

配置向导会让你选默认模型。这里有个新手最容易忽略的点：

• 不要把最贵/最强的模型设为默认——OpenClaw有很多后台任务（定期复盘、心跳检测等），它们也会调用默认模型。有人把Claude Opus设成默认，第二天收到“调用两千次”的账单，直接破产。

• 推荐组合：默认模型用性价比高的，需要干重活时再在对话里指定用强模型。

特别提醒3：配置文件是“命根子”，改前要备份

配置完成后，所有设置会保存在 C:\Users\你的用户名\.openclaw\openclaw.json（Windows默认路径）。这个文件决定了你的AI能干什么、不能干什么。

常见死法：OpenClaw运行一段时间后，你或AI自己想改配置，直接编辑了JSON文件，结果少个逗号或多括号——Gateway启动失败，AI罢工。

保命技巧：

• 改配置前先备份：把config.json复制一份到桌面

• 改完后一定要跑自检：openclaw doctor --non-interactive，让系统帮你检查有没有语法错误

• 养成习惯：代码约束优于文字规则——把“必须自检后才能重启”写成脚本，让AI自己遵守

特别提醒4：配置向导可以重跑，别怕

如果第一次配置时选错了（比如模型提供商选错了、API-Key输错了），不用卸载重装。直接重新运行：

openclaw onboard

它会重新走一遍配置流程，覆盖之前的设置。所有旧配置会备份到 .openclaw/openclaw.json.bak，手贱了还能找回来。

特别提醒5：多Agent配置时，小心“自举”陷阱

如果你后续要配置多个Agent（高级玩法），官方文档里有几个隐藏坑：

• 不要手动创建 BOOTSTRAP.md——这个文件是Agent的初始化任务清单，只有Agent执行完里面的命令才会自动删除。如果你手动创建，Agent会永远卡在“启动中”状态，反复尝试完成不存在的任务。

• Agent目录不要重用——给不同Agent分配同一个工作目录，会导致认证失败、会话混乱。

• Bindings顺序有讲究——把具体的匹配规则（比如“某个具体频道的ID”）放在前面，泛规则（比如“所有频道”）放后面，否则可能匹配错。

4、OpenClaw命令速查：装好了怎么用？

安装完成后，你手里多了一个叫 openclaw 的命令行工具。这套命令家族大概有40多个子命令，但日常用到的其实就那么几个，按功能分类如下：

配置管理类

• openclaw onboard：安装后自动进入的配置向导，也可以随时重跑

• openclaw configure：手动修改配置（比直接改JSON安全）

• openclaw config get/set：快速查看或修改某个配置项

• openclaw doctor --fix：出问题了先跑这个，能自动检查和修复大部分问题

服务控制类

• openclaw gateway start/stop/restart：控制后台核心服务的启停

• openclaw gateway status：查看网关运行状态

• openclaw logs：查看运行日志，出问题时的第一现场

日常使用类

• openclaw dashboard：打开Web管理界面（默认地址 http://127.0.0.1:18789）

• openclaw tui：在终端里直接对话（命令行版聊天界面）

• openclaw status：查看整体运行状况

• openclaw update：升级到最新版本

技能扩展类

• openclaw skills list：查看已安装的技能

• openclaw plugins install：安装插件

特别解释：为什么它“偷偷”设置了开机自启动？

很多用户装完后重启电脑，发现OpenClaw还在后台跑着，第一反应是：“这软件怎么偷偷搞我电脑？”

真相是：这不是偷偷搞，而是你安装时主动选择的（或者默认勾选的）。

在运行 openclaw onboard 时，如果你用了 --install-daemon 参数，或者在配置向导里选择了“安装为服务”，OpenClaw就会把自己注册为系统服务，Windows系统会通过计划任务或开机启动项实现。

为什么这么设计？

OpenClaw的定位不是“打开才用的聊天软件”，而是长期在后台运行的AI基础设施。它的核心进程叫“网关”（Gateway），负责：

• 持续接收来自微信/飞书的消息

• 维护会话状态和记忆

• 按计划执行定时任务（比如每天早上8点推送简报）

如果每次开机都要手动启动，这些功能就全废了。所以它需要像杀毒软件一样——装一次，以后开机自动跑。

如果我不想要开机自启动怎么办？

三种方法：

1. 安装时选择不安装服务：运行 openclaw onboard --no-install-daemon

2. 卸载网关 (openclaw gateway uninstall)：从系统里彻底删掉这个计划任务，一了百了。

3. 计划任务中禁用：在任务计划程序库找到 OpenClaw 的任务，右键禁用。这样既关掉了开机启动，以后想用的时候随时右键启用就行，不用重新安装。

需要时手动启动就行：openclaw gateway start

5、安装完成后，OpenClaw用户配置文件都有哪些？

当你第一次运行 openclaw onboard 配置完成后，系统会在你的用户目录下生成一个 .openclaw 文件夹（Windows 在 C:\Users\你的用户名\.openclaw）。这里面装的是整个 AI 的“家”——配置文件、记忆、技能、日志，全都在这里。

很多新手打开这个文件夹，看到一堆不认识的文件和目录，第一反应是：这些能删吗？能改吗？哪个是重要的？

下面这张表帮你理清楚：

一句话总结：如果你要备份 OpenClaw，重点备份 openclaw.json、workspace/、agents/ 和 exec-approvals.json。其他丢了可以重建，但这四个丢了，AI 就不认识你了。

二、配置文件：OpenClaw 的控制面板

安装好 OpenClaw 之后，你最想做的事肯定是：让它按我的意思干活。网上有各种教程教你“怎么配置”，但说实话，照着改的时候心里总有点发毛——这个参数是干什么的？改错了会不会把 AI 搞疯？

其实，OpenClaw 的所有行为都藏在它的配置文件里。只要读懂了这份文件，你就掌握了 AI 的“方向盘”。这一节我们就一起打开看看，里面到底写了什么，改了会怎样。

1、配置文件在哪？

配置文件默认在用户目录下的 .openclaw 文件夹里，名字叫 openclaw.json：

• Windows：C:\Users\你的用户名\.openclaw\openclaw.json

第一次运行 openclaw onboard 后，这个文件就会自动生成。它是一个 JSON 格式的文本文件，你可以用记事本或任何代码编辑器打开。

重要提醒：修改配置文件之前，一定先备份。复制一份改名为 openclaw.json.bak，万一改错了还能找回来。

2、配置文件的“骨架”：四层架构的映射

打开 openclaw.json，你可能会看到一堆嵌套的 {} 和 []。别慌，它的结构其实反映了 OpenClaw 的四层架构，而且每一块都对应着管理界面里的某个菜单——你既可以在文件里改，也可以在界面里点。

下面我们逐个拆解每个配置块，同时你会看到——官方文档里列的那些功能，其实都分散在这四个板块里。

交互层（channels）：AI 的“耳朵和嘴巴”

这一层控制 AI 能从哪些平台听到你说话，以及怎么回你。对应官方文档中的：

• Telegram 机器人支持：channels.telegram 里填 Bot Token，基于 grammY 实现

• Discord 机器人支持：channels.discord 配置，用 discord.js 库

• Mattermost 机器人支持：作为插件渠道，通过扩展包添加

• WebChat 和 macOS 菜单栏应用：交互层的“额外触角”，让你在浏览器或菜单栏也能跟 AI 说话

• 群聊支持，通过提及激活：channels.whatsapp.groups.requireMention 控制是否必须@才回应

• 图片、音频和文档的媒体支持：所有渠道默认支持，channels.*.media 可细粒度控制

• 可选的语音消息转录钩子：语音消息转文字，需要配置转录服务

案例：想同时在 WhatsApp 和 Telegram 上用 AI，只在群里被@时才回答——在 channels 里分别配置两个渠道，再把 groups.requireMention 设为 true 就行。

网关层（gateway）：AI 的“总机接线员”

这一层不直接跟你说话，但它管着所有消息怎么走、什么时候走。对应官方文档中的：

• 长响应的流式传输和分块处理：网关层负责把 AI 的长回复切成小块，像打字一样流式返回，避免超时

• 多智能体路由，按工作区或发送者隔离会话：网关的路由功能，根据消息来源分配到不同智能体 

• 会话管理：私信合并为共享的 main 会话，群组相互隔离——这是网关层的会话路由策略

• 通过 OAuth 进行 Anthropic 和 OpenAI 的订阅认证：网关层处理认证流程，把 token 传给智能体层

• Pi 的智能体桥接，支持 RPC 模式和工具流式传输：网关层内置的 Pi 二进制文件，以 RPC 模式运行智能体

案例：想让公司群里所有人都能@AI，但每个人的私聊记录互相看不见——网关层通过“按发送者隔离会话”就能实现。

智能体层（agents）：AI 的“大脑”

这一层是 AI 真正思考的地方——你是谁、它该记什么、用什么模型想问题。对应官方文档中的：

• 会话管理：智能体层的会话管理器维护每个对话的状态，包括短期记忆（当天日志）和长期记忆（MEMORY.md）

• 多智能体路由：agents 里可以配多个智能体，每个有不同的 persona 和模型，网关层负责路由到正确的那个 

• Pi 的智能体桥接：agents.default 里可以指定用内置的 Pi 智能体，还是连接外部模型

案例：想分两个 AI——一个工作用 GPT-4，一个闲聊用便宜的 qwen-turbo——在 agents 里配两个，然后在不同渠道指定用哪个。

执行层（sandbox）：AI 的“手脚”

这一层让 AI 不光能说，还能干——截屏、发邮件、控制设备。对应官方文档中的：

• iOS 节点，支持配对和 Canvas 界面：你的 iPhone 可以作为一个“远端节点”，AI 能通过它执行任务（比如拍照）

• Android 节点，支持配对、Canvas、聊天和相机：同理，安卓手机也能变成 AI 的“远程手脚”

• 通过本地 imsg CLI 集成 iMessage（macOS）：这既是交互层（收消息），也是执行层（发消息）——调用本地命令

• 图片、音频和文档的媒体支持：在技能层面，AI 可以生成图片、处理音频，这些都算执行层的技能调用

案例：调用本地 PowerShell 脚本、执行批处理命令，或者通过 MCP (Model Context Protocol) 协议接入本地服务端来控制具体的应用程序

小结

官方文档里的那些功能，没有一个独立于四层架构之外——它们要么是某一层的具体能力（比如“群聊提及激活”是交互层的规则），要么是跨层协作的结果（比如“远程截屏”需要交互层收指令、网关层路由、智能体层决策、执行层干活）。

3、能力的总闸：tools 配置块

如果说四层架构定义了 OpenClaw 的“身体结构”，那么 tools 就是控制这个身体“能做什么”的总闸。它不负责定义每个动作的细节（比如命令超时多久），而是决定 AI 可以调用哪些类型的能力——能否浏览网页、能否执行命令、能否操作你的手机。

打开 openclaw.json，找到 "tools" 这个顶级配置项，你会发现它的结构像一套精密的权限管理系统：

"profile": "coding",          // 基础能力模板：coding、messaging、minimal 或 full"allow": ["group:fs", "browser"], // 额外允许的工具或工具组"deny": ["exec"],              // 明确禁止的工具（优先级最高）"byProvider": {                // 针对不同模型提供商的特殊策略"openai/gpt-4": { "allow": ["group:runtime"] }}

核心机制：允许/拒绝 + 配置文件 + 提供商策略

这个配置块的核心逻辑只有三句话：

• 基础模板 (profile)：快速设定 AI 的“职业”。选 coding，它就擅长读写文件、运行代码；选 messaging，它就专注收发消息、管理会话。这相当于给你一个安全的起点。

• 允许与拒绝 (allow/deny)：在模板基础上微调。deny 拥有最高优先级——哪怕模板里开了所有工具，只要在 deny 里列了 exec，AI 就不能执行系统命令。

• 按模型细化 (byProvider)：针对不同 AI 模型设置不同权限。比如让强大的 GPT 可以用浏览器，但便宜的快速模型只能查聊天记录——既省钱又安全。

工具组：高效的权限简写

文档里提到的 group:fs、group:runtime 等，是给管理员用的“快捷方式”。一个 group:fs，就代表了 read、write、edit、apply_patch 这一整套文件操作工具。这让配置既简洁又不容易遗漏。

它如何控制其他核心板块？

这正是 tools 作为“总闸”的关键——它直接决定了后续章节里那些“灵魂”、“记忆”、“安全”能否被 AI 使用：

换句话说，你在 tools 里勾选的每一个能力，都是在为后面几章要管理的具体内容授予 AI 操作权限。

特别提醒：配置 tools 时的几个生死攸关的细节

1. 小心 deny: ["\*"]——这会让 AI 变回“傻子”deny 的优先级高于 allow，如果你为了测试写了个 "deny": ["*"] 却忘了删，AI 将无法使用任何工具——不能读文件、不能搜网页、不能执行命令，连查看会话状态都不行。所有依赖工具的功能都会失效，但对话还能继续（因为聊天本身不依赖工具）。遇到 AI 突然“装傻”，先检查这里。

2. 不要把 group:runtime 当成普通的“运行”组group:runtime 包含 exec、bash、process——这是最危险的三个工具，允许 AI 直接在你的电脑上运行命令。如果你只是想允许 AI 读写文件，应该用 group:fs，而不是 group:runtime。记错组名，等于把系统权限拱手送出。

3. profile: "full" 是给专家用的，新手别碰full 配置文件会开放所有工具，包括 exec、browser、nodes 等高风险能力。如果你刚接触 OpenClaw，请从 minimal 或 coding 开始，逐步按需开放。用 full 相当于给 AI 发了把万能钥匙，万一提示词被注入，后果不堪设想。

4. 善用 doctor 命令验证配置在修改完 tools 后，强烈建议运行：

openclaw doctor --non-interactive

它会检查配置语法、工具依赖是否满足、是否有冲突规则。这能帮你提前发现 deny 写错、组名拼错等低级错误，避免服务崩溃。

5. 警惕 browser 和 nodes 工具的隐私泄露browser 工具可以让 AI 控制你的浏览器（打开网页、点击、截图），nodes 工具可以调用摄像头、屏幕录制、获取地理位置。启用这些工具前，请确保你完全信任当前对话的 AI，并且理解它们可能收集的信息。 如果不确定，可以在 exec-approvals.json 中为这些工具设置 "ask": "always"，每次调用都让你点头。

4、skills：AI 的“技能包”

Skills 就是给 AI 装上的“外挂功能包”——每个 Skill 让 AI 多一项本事，比如读文件、搜网页、控制浏览器、甚至连接外部服务。

你可以把 OpenClaw 想象成一部手机，AI 是手机系统，而 Skills 就是手机上的 App：

• 系统本身只有基础功能（对话）。

• 装个“计算器” App，AI 就能算数（对应 exec 命令执行）。

• 装个“浏览器” App，AI 就能上网（对应 browser 工具）。

• 装个“文件管理器” App，AI 就能读写文件（对应文件操作工具）。

Skills 怎么配？——其实就是列个清单

在 OpenClaw 的配置文件 openclaw.json 里，有一个叫 "skills" 的节点，它的结构长这样：

"skills": {  "entries": {    "skill的名字": {      "enabled": true,      "其他配置": "..."    },    "另一个skill": {      "enabled": false,      ...    }  }}

• entries 下面每一个键都是一个 Skill 的 ID（唯一名字）。

• enabled 决定这个 Skill 是否启用（true 表示打开，AI 能用；false 表示关闭）。

• 每个 Skill 还可以有自己的专属配置，比如环境变量、路径、参数等。

最常见的例子：mcporter Skill

"skills": {  "entries": {    "mcporter": {      "enabled": true,      "env": {        "MCPORTER_CONFIG": "C:\\Users\\chcsyf\\.mcporter\\mcporter.json"      }    }  }}

这个 mcporter 是一个特殊的 Skill，它本身不直接干活，而是充当 “万能转接头”——帮 AI 连接外部世界。

但请注意：mcporter Skill 只是 OpenClaw 里的一个“插座”，真正干活的是你需要单独安装的 mcporter 命令行工具。

1. 写好 mcporter.json 配置文件，里面列出你想让 AI 用的外部服务（比如 GitHub、Notion、本地文件系统）。这个文件通常放在用户目录下的 .mcporter 文件夹里。

2. 在 OpenClaw 中启用 mcporter Skill，并通过环境变量 MCPORTER_CONFIG 告诉它配置文件的位置（就像你看到的那样）。

3. 当 OpenClaw 启动时，mcporter Skill 会调用你安装的 mcporter 命令行工具，后者会自动启动配置文件中定义的所有 MCP 服务器，并把它们提供的功能“翻译”成 OpenClaw 能懂的工具。

4. 最终，AI 就能像调用内置工具一样调用这些 MCP 工具了。

Skills 从哪来？怎么装？

Skill 的来源主要有两种：

1. OpenClaw 内置的 Skill：比如 mcporter（这个 Skill 本身是 OpenClaw 自带的），你只需要在配置里启用它，并按要求配好环境变量。但请注意：内置 Skill 也可能依赖外部工具，比如 mcporter Skill 依赖 mcporter 命令行工具，你需要提前用 npm 安装好。

2. 社区开发的 Skill：可以通过命令安装。

   安装后，它会自动在 skills.entries 里添加一条配置（通常默认是 enabled: false），你需要手动改成 true 并补充必要配置（比如路径、密钥等）。

手动安装（不推荐新手）：你也可以直接编辑 openclaw.json 添加 entries，但需要自己确保 Skill 的代码已经下载到正确位置。通常还是用命令省心。

Skills 配置的常见“坑”和保命技巧

1. skill会给OpenClaw增加权限吗？

   不会，但是会利用你现有的权限。

2. 不要随意启用不熟悉的 Skill尤其是从社区下载的，先看看它的代码或文档，确保它不会窃取你的 API Key 或干坏事。

3. Skill 可能依赖 Python 或 Node 环境有些 Skill 需要额外的运行时，如果启动失败，检查是否装了对应依赖。

5、plugins：AI 的“插件生态”

在 openclaw.json 里，plugins 是一个顶级配置块，它的结构和 skills 几乎一样：

"plugins": {  "entries": {    "插件ID": {      "enabled": true,      "config": {        // 该插件特有的配置参数      }    },    "另一个插件ID": {      "enabled": false,      "config": { ... }    }  }}

• entries 下面每一个键都是插件的唯一 ID。

• enabled 控制插件是否启用（true 表示加载，false 表示禁用）。

• config 是插件的专属配置，不同插件要求的字段完全不同。

1. plugins 到底是干什么的？

如果说 skills 是给 AI 装“App”（增加它能做的事），那么 plugins 就是给 OpenClaw 系统本身“打补丁”或“换主题”——它们能：

• 修改网关的启动行为

• 注册新的 CLI 命令（比如装了个企业微信插件后，你就可以用 openclaw wecom 命令）

• 接入新的消息渠道（如企业微信、钉钉）

• 改变 AI 记忆和上下文处理的核心机制（如 ContextEngine 插件）

• 添加安全审计、性能监控等系统级功能

简单说：skills 影响 AI，plugins 影响 OpenClaw 本身。

2. 热门插件示例（以及它们在配置里长什么样）

以下插件是目前社区最活跃的，但重点看它们如何在 openclaw.json 中体现：

4. 插件的安装和管理

插件的安装命令和 skills 类似，但作用域不同：

# 安装插件（以企业微信插件为例）openclaw plugins install @wecom/wecom-openclaw-plugin# 安装后，配置会自动添加到 openclaw.json，但可能默认禁用（enabled: false）# 你需要手动编辑配置文件把 enabled 改成 true，并补充 config 里的参数# 查看已安装插件openclaw plugins list# 卸载插件（同时会从配置文件中移除对应条目）openclaw plugins remove <插件ID>

5. 配置插件的常见“坑”和保命技巧

1. 插件的 config 参数必须填对比如企业微信插件的 corpId 填错，网关启动时可能报错甚至崩溃。建议先查阅插件文档，确认必填项。

2. 插件可能互相冲突两个插件如果修改了同一个系统行为（比如都试图接管消息路由），可能导致网关启动失败。遇到问题，先禁用最近安装的插件（enabled: false），然后重启试试。

3. 卸载后检查残留虽然 openclaw plugins remove 会删除配置条目，但有些插件可能还在其他地方（如 skills/ 目录）留下文件，需要手动清理。

4. ContextEngine 插件必须在配置向导中指定如果安装了多个上下文引擎插件，只有你在 openclaw config wizard 里选中的那个才会生效，其他的即使 enabled: true 也不会被使用。

5. 高危插件要慎用插件权限比技能大得多，尤其是那些声明要“执行任意命令”或“完全文件系统访问”的。安装前建议用 claw-security-auditor 扫描一下风险。

6. Plugins vs. Skills

三、exec-approvals：安全屏障

OpenClaw 最强大的能力之一，就是 AI 可以直接在你的电脑上执行系统命令——但这也是最危险的地方。如果 AI 被恶意提示词诱导，或者你误开了过高权限，它可能删文件、改设置、甚至格式化硬盘。为了避免灾难，OpenClaw 设计了一道可配置的安全屏障：exec-approvals.json。

这个文件定义了 AI 执行命令时的审批规则——哪些命令需要你点头，哪些可以自动执行，哪些直接被禁止。它就像 AI 的“行为监管员”，所有危险操作都必须先经过你同意。

1. 文件在哪？长什么样？

exec-approvals.json 和主配置文件放在一起，默认路径：

• Windows：C:\Users\你的用户名\.openclaw\exec-approvals.json

它是一个 JSON 文件，内容大致如下：

{  "version": 1,  "rules": [    {      "name": "允许安全的文件操作",      "description": "允许 AI 在用户目录下读写文件，但禁止删除",      "match": "^(cat|ls|head|tail|grep) .*",      "allow": true,      "ask": "on-miss"    },    {      "name": "高危命令必须询问",      "match": "^(rm|del|format|shutdown|sudo) .*",      "allow": true,      "ask": "always"    },    {      "name": "禁止修改系统关键文件",      "match": ".*(C:\\\\Windows\\\\System32|/etc/passwd).*",      "allow": false,      "ask": "off"    }  ],  "default": {    "allow": false,    "ask": "always"  }}

• rules 数组：每条规则定义了对匹配命令的处理方式。

• "off"：不询问，直接按 allow 决定。

• "on-miss"：如果没有更具体的规则匹配，才询问（通常用于白名单机制）。

• "always"：即使匹配了允许规则，也还是要问你一次。

• match：正则表达式，用来匹配 AI 要执行的命令。

• allow：true 表示允许执行，false 表示禁止（规则匹配后直接拒绝）。

• ask：控制是否询问你：

• default：当没有规则匹配时的默认行为。

2. 它是怎么工作的？

当 AI 调用 exec 工具执行命令时，OpenClaw 网关会：

1. 遍历 rules 列表，按顺序匹配命令字符串（正则匹配）。

2. 找到第一条匹配的规则，根据 allow 和 ask 决定：

• 如果 allow: false → 直接拒绝，AI 会收到“命令被禁止”的错误。

• 如果 allow: true 且 ask: "off" → 静默执行，AI 直接运行命令，你完全不知道。

• 如果 allow: true 且 ask: "always" → 弹窗询问，你必须手动确认才能执行。

• 如果 allow: true 且 ask: "on-miss" → 只有当没有其他规则匹配时才询问（相当于白名单+默认询问）。

3. 如果没有任何规则匹配，则采用 default 行为。

关键点：exec-approvals.json 只控制 exec 工具的行为，其他工具（如 read_file、browser）不受此文件影响——它们的权限在 tools.allow/deny 里控制。

3. 为什么需要它？一个真实案例

假设你给 AI 开了 group:runtime（包含 exec），让它能帮你执行命令。某天你让它“整理一下桌面”，AI 可能自作聪明地执行：

rm -rf ~/Desktop/*

如果你的 exec-approvals.json 没有保护，桌面文件就全没了。但如果你有一条规则：

{  "match": "^rm .*",  "allow": true,  "ask": "always"}

AI 执行 rm 前就会弹窗问你：“要执行 rm -rf ~/Desktop/* 吗？[允许]/[拒绝]”。你一看不对劲，果断拒绝，避免悲剧。

4. 配置原则：最小权限 + 分层防御

原则 1：默认拒绝，按需开放

default.allow: false 是最安全的起点。然后针对你确信安全的命令（比如 ls、cat、grep）添加允许规则，并设置 ask: "off"，让日常操作流畅。高危命令（rm、del、format、sudo）即使允许，也要 ask: "always"。

原则 2：规则顺序很重要

规则按从上到下匹配，第一条命中的生效。所以具体的规则放前面，宽泛的规则放后面。比如：

{  "match": "^rm -rf /home/.*/\\.Trash",  "allow": true,  "ask": "off"},{  "match": "^rm .*",  "allow": true,  "ask": "always"}

这样清空回收站的操作可以自动执行，但其他 rm 命令必须询问。

原则 3：禁止修改系统关键区域

建议添加一条全局禁止规则，匹配常见的系统关键路径：

{  "match": ".*(C:\\\\Windows\\\\System32|/etc|/usr/bin).*",  "allow": false,  "ask": "off"}

这样 AI 无论如何都无法触碰系统核心文件。

5. 与 tools 配置的关系（容易混淆的地方）

• tools.allow/deny 控制的是 AI 能否使用 exec 工具。如果 tools.deny 里写了 exec，那 AI 根本不能执行任何命令，exec-approvals.json 根本用不上。

• 如果 tools.allow 里开了 exec，那么执行的具体命令才会受 exec-approvals.json 的审批规则约束。

6.  特别提醒

1. ask: "on-miss" 的逻辑容易误解它只在 没有规则匹配 时才询问。如果你有一条宽泛的允许规则（比如 match: ".*"），那 on-miss 永远不会触发，所有命令都会按那条规则处理。所以宽泛规则要小心。

2. 命令可能带参数，正则要匹配完整比如 rm -rf / 和 rm file.txt 可能被同一条规则匹配。如果你只想禁止危险用法，正则要写精确，比如 "^rm -rf /$" 只匹配删除根目录。

3. AI 可能会尝试绕过理论上 AI 可以把危险命令拆成多步执行，或者用编码绕过。但 OpenClaw 的审批是基于最终执行的命令字符串，所以除非你写了过于宽泛的允许规则，否则很难绕过。

四、nodes：远程设备的管理与控制

在 OpenClaw 的四层架构中，执行层（sandbox）负责 AI 的“手脚”，而 nodes 则是将执行层的能力延伸到远程设备的关键——它让 AI 不仅能操作你的电脑，还能控制你授权的手机、平板、树莓派等其他设备。

但请注意：nodes 本身不是一个“工具”，而是一套设备管理和能力发现的机制。正确理解它的配置方式，是安全使用远程功能的前提。

1. Nodes 是什么？

Nodes 是连接 OpenClaw 网关（Gateway）的原生设备客户端，包括：

• iOS 节点、Android 节点（通过配套 App）

• macOS 节点（通过菜单栏应用）

• 无头节点主机（Linux/Windows 服务器，通过命令行运行）

每个节点配对成功后，会向网关报告自己具备的能力，例如：

• 摄像头拍照/录像（camera.snap、camera.clip）

• 屏幕录制（screen.record）

• 发送通知（system.notify）

• 执行系统命令（system.run）

• 获取地理位置（location.get）

• 访问联系人/日历/短信（contacts.*、calendar.*、sms.send）

这些能力会被网关自动注册为 AI 可调用的工具，名称通常就是上述的命令标识。

2. Nodes 的配置位置

Nodes 的核心配置在 gateway 配置块下。

"gateway": {  "port": 18789,  "auth": {    "mode": "token",    "token": "你的网关令牌"  },  "nodes": {    "denyCommands": [      "camera.snap",      "camera.clip",      "screen.record",      "contacts.add",      "calendar.add",      "reminders.add",      "sms.send"    ]  }}

• gateway.nodes.denyCommands：在网关层全局禁止某些高危命令。即使节点设备具备这些能力，AI 也无法调用。这是一个一刀切的安全防线，适用于所有智能体和所有节点。

• 节点配对信息（如设备 ID、名称、公钥）通常存储在用户目录下的 .openclaw/devices/ 文件夹中，或者通过 openclaw node list 命令查看。

3. 如何让 AI 使用节点能力？—— 两层控制体系

Nodes 的权限控制分为两层，两者必须同时允许，AI 才能真正调用：

生效规则：实际可用命令 = 网关层未禁止 ∩ 工具层允许。例如：若网关层禁止了 camera.snap，即使 tools.allow 里有它，AI 也无法拍照。反之，若网关层允许但 tools.deny 禁止了，同样无法调用。

重要区别：你不需要在 tools.allow 中写一个叫 "nodes" 的工具——节点能力是自动注册的，直接在 tools.allow 中按命令名称（如 camera.snap）控制即可。

4. 无头节点主机的配置

如果你想将一台 Linux/Windows 服务器变成“无头节点主机”（只执行命令，没有 UI），需要用 openclaw node 命令单独配置：

# 在目标主机上安装节点服务并连接到网关openclaw node install --host <网关IP> --port 18789 --token <网关令牌># 安装后，节点信息会存储在 ~/.openclaw/node.json# 可用命令查看节点状态openclaw node status

这种模式下，节点的配置独立于主配置文件，但节点上报的能力（如 system.run）同样受上述两层规则控制。

5. 特别提醒：Nodes 是双刃剑，配置务必谨慎

Nodes 赋予了 AI 前所未有的物理世界控制能力，但也带来了巨大的隐私和安全风险。以下是必须牢记的要点：

• 默认禁止所有高危命令初次安装后，gateway.nodes.denyCommands 应包含所有摄像头、屏幕、短信、联系人等敏感操作。只有在明确需要且理解风险时，才从列表中移除个别条目。

• 不要在 tools.allow 中随意开放节点命令即使网关层允许，工具层也应保持最小权限原则。例如，除非你真的需要 AI 远程拍照，否则不要让 camera.snap 出现在 tools.allow 中。

• 定期审计已配对的节点用 openclaw nodes list 查看所有已连接的设备。如果发现陌生设备，立即删除配对（可通过 openclaw nodes remove <id> 或直接删除 devices/ 下对应文件）。

• 节点应用本身也有权限请求在 iOS/Android 设备上配对时，节点 App 会请求摄像头、位置等系统权限。请仔细阅读提示，只授予必要权限。例如，如果不需要 AI 拍照，就不要给 App 摄像头权限。

• system.run 是最危险的命令它允许在远程设备上执行任意系统命令。即使你只允许在特定节点上运行，也应通过 exec-approvals.json 设置严格的审批规则（例如 ask: "always"），并考虑在网关层用 denyCommands 彻底禁止。

• 保护网关令牌节点连接网关时需要提供令牌。如果令牌泄露，攻击者可以随意添加恶意节点。定期更换令牌（openclaw config set gateway.auth.token NEW_TOKEN）并重启网关。

6. 配置示例：安全地使用远程截图功能

假设你希望 AI 能偶尔从你的 Android 手机获取屏幕截图（用于自动化测试），但禁止其他所有高危操作。可以这样配置：

openclaw.json 中：

"gateway": {  "nodes": {    "denyCommands": [      "camera.snap",      "camera.clip",      "contacts.add",      "calendar.add",      "reminders.add",      "sms.send"      // 注意：screen.record 未列入禁止，因为我们需要它    ]  }}

同时，在 tools 中明确允许：

"tools": {  "allow": ["screen.record"],   // 只允许录屏  "deny": []                    // 其他节点命令默认禁止（因为没有出现在 allow 中）}

这样，AI 只能调用 screen.record，无法使用摄像头、短信等其他敏感功能。