OpenClaw 是一款开源自托管的 AI 个人智能体，支持多聊天渠道接入与大模型调用。档提供从环境准备、一键安装、交互式初始化配置到渠道接入、安全加固及故障排查的全流程指南。涵盖 macOS、Windows WSL2 及 Linux 系统适配方案，详解 Kimi、Claude 等模型接入方法，并包含 Web 控制台使用、权限管理、定时任务配置及常见问题解决方案，帮助用户快速搭建本地 AI 自动化工作流。
本教程基于官方最新文档、社区博客实战指南优化编写，覆盖从架构理解、环境准备、安装配置、渠道接入到日常使用、安全加固、故障排查的全流程，重点补充国内用户适配方案、新手避坑指南、全场景问题排查。
如果你只想最快跑通核心流程，直接按以下 4 步操作，无需提前阅读全文，后续可回头补全细节：
curl -fsSL https://openclaw.ai/install.sh | bash；Windows 管理员 PowerShell 执行 iwr -useb https://openclaw.ai/install.ps1 | iexopenclaw onboard --install-daemon，跟着向导选「本地模式」、配置 AI 模型 API Key、选择 Telegram 渠道、安装后台守护进程openclaw pairing list telegram 查看配对码，执行 openclaw pairing approve telegram <配对码> 完成授权OpenClaw 是一款开源自托管的 AI 个人智能体，区别于只能给建议的对话式 AI，它的核心能力是**「发一句话，就帮你在本机 / 服务器上真实执行任务」**。
一次完整的指令执行，会经过以下核心组件，理解每个组件的作用，出问题可快速定位故障点：
你常用的聊天 App（Telegram/WhatsApp 等）【消息入口 Channels】 ↓（消息流入/流出）Gateway 网关【唯一总机，管理所有连接、认证、消息路由】 ↓（RPC 调用）Agent 智能体运行时【理解指令、调用模型、执行工具、维护会话上下文】 ↓（工具调用）内置工具/技能插件【浏览器/终端/文件管理/邮件/日历等扩展能力】 ↓（模型调用）AI 大模型提供商【Claude/GPT/Kimi/本地模型】
| 名词 | 核心作用 | 新手通俗理解 |
|---|---|---|
| Gateway | 唯一常驻后台进程，管理所有聊天渠道、消息路由、认证授权，默认端口 18789 | 相当于总机，所有消息都要经过它中转 |
| Agent | 智能体运行时，负责对话逻辑、工具调用、上下文维护，可配置多个独立 Agent | 相当于接线员 + 执行者，负责理解需求并干活 |
| Channels | 消息入口渠道，即你用来发指令的聊天软件（Telegram/WhatsApp 等） | 你给智能体打电话的手机 |
| Session | 会话上下文容器，跨消息保存对话历史，默认按发送者隔离 | 你和接线员的通话记录 |
| Workspace | Agent 的工作目录，存放生成的文件、脚本、配置模板 | 执行者的办公文件夹 |
| Pairing | 安全配对机制，陌生用户发消息需你手动批准，防止机器人被滥用 | 来电防火墙，只接你批准的号码 |
| Skills | 技能插件，扩展 OpenClaw 的能力，比如邮件管理、智能家居控制 | 给执行者新增的专业技能 |
| 系统 | 推荐配置 | 注意事项 |
|---|---|---|
| macOS | macOS 14+，内存≥4GB，磁盘≥5GB | 需安装 Xcode Command Line Tools（源码构建时） |
| Windows | 强烈推荐 WSL2（Ubuntu 22.04+），原生 Windows 支持有限 | 原生 Windows 工具兼容性差，大概率会出现未知问题 |
| Linux | Ubuntu/Debian/Fedora/Arch 等主流发行版，内置 systemd，内存≥4GB | 适合 7×24 小时服务器部署 |
推荐使用 nvm 安装，可灵活切换版本，避免权限问题：
# 1. 安装 nvm（macOS/Linux/WSL2）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 2. 重载终端配置
source ~/.bashrc # bash 终端
source ~/.zshrc # zsh 终端
# 3. 安装 Node.js 22 LTS 版本
nvm install 22
nvm use 22
# 4. 验证安装成功（必须输出版本≥22.0.0）
node -v
npm -v
Windows 原生系统：直接前往 Node.js 官网 下载 22.x LTS 版本，按向导安装后，在 PowerShell 执行 node -v 验证。
xcode-select --install（macOS）/sudo apt install git（Linux）即可安装npm install -g pnpm 即可安装wsl --shutdown，重新打开 Ubuntu 终端，执行 systemctl --user status 验证 systemd 正常运行开启 systemd（后台服务必备），在 Ubuntu 终端执行：
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF
重启电脑，再次以管理员身份打开 PowerShell，设置 WSL2 为默认版本：
wsl --set-default-version 2
以管理员身份打开 PowerShell，执行以下命令开启 WSL2 功能：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
OpenClaw 本身不提供大模型能力，需提前准备好模型 API Key，二选一即可：
如果使用海外模型，需提前配置系统代理，否则无法调用 API、启动网关：
# 终端临时配置代理（端口改为你自己的代理端口）
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
# 永久配置（写入终端配置文件）
echo 'export HTTPS_PROXY="http://127.0.0.1:7890"' >> ~/.zshrc
echo 'export HTTP_PROXY="http://127.0.0.1:7890"' >> ~/.zshrc
source ~/.zshrc
# 也可直接在 OpenClaw 配置中设置代理
openclaw config set gateway.proxy.url "http://127.0.0.1:7890"
安装完依赖后，执行以下命令，全部通过再继续后续步骤：
# 检查 Node.js 版本（必须≥22.0.0）
node -v
# 检查 npm 是否正常
npm -v
# 检查网络连通性（海外模型需执行，能正常返回即代理生效）
curl https://api.anthropic.com/v1/messages --head
# 国内模型检查
curl https://api.moonshot.cn/v1/chat/completions --head
自动安装 Node.js、Python、OpenClaw CLI 及所有依赖，无需手动配置，全程无需干预。
打开终端，执行以下命令：
curl -fsSL https://openclaw.ai/install.sh | bash
以管理员身份打开 PowerShell，执行以下命令：
iwr -useb https://openclaw.ai/install.ps1 | iex
安装完成后，终端会提示 Install completed，即安装成功。
适合已有 Node.js 环境，想自主控制安装过程的用户：
# NPM 安装（通用）
npm install -g openclaw@latest
# PNPM 安装（推荐，性能更好）
pnpm add -g openclaw@latest
pnpm approve-builds -g
适合想调试代码、贡献社区、自定义修改的用户：
# 1. 克隆官方仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw
# 2. 安装依赖
pnpm install
# 3. 构建 UI 和项目
pnpm ui:build
pnpm build
# 4. 执行初始化配置
openclaw onboard --install-daemon
执行以下命令，能正常输出版本号，即安装成功：
openclaw --version
# 查看帮助文档，确认命令可用
openclaw --help
command not found这是 npm 全局安装目录不在系统 PATH 中导致的，按以下方案解决：
# macOS/Linux/WSL2
# 1. 查找 openclaw 安装位置
which openclaw
# 2. 若找不到，添加 npm 全局 bin 目录到 PATH
export PATH="$(npm prefix -g)/bin:$PATH"
# 3. 永久生效
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc # bash
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc # zsh
source ~/.zshrc # 重载配置
# Windows PowerShell
# 1. 查找安装位置
where.exe openclaw
# 2. 添加到环境变量
$npmPath = npm prefix -g
$env:Path += ";$npmPath"
# 3. 永久生效
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$npmPath", "User")
openclaw onboard 是官方推荐的配置方式，全程交互式引导，新手跟着选即可，不会出错。
打开终端，执行以下命令，启动向导并自动安装后台守护进程（开机自启）：
openclaw onboard --install-daemon
以下是向导全步骤的命令行视图与新手选择建议，实际输出可能因版本略有差异，以官方提示为准。
🦞 OpenClaw Onboarding Wizard ─────────────────────────────────────
Welcome! This wizard will help you set up OpenClaw.
Mode selection:
[1] QuickStart (recommended for first-time users)
[2] Advanced (full control over every setting)
Choose mode [1]:
1（QuickStart），使用官方推荐的默认值，只需要填写核心配置，避免踩坑2（Advanced），完全自主控制所有配置项如果之前安装过 OpenClaw，向导会检测到现有配置，提示：
Found existing config at ~/.openclaw/openclaw.json
What would you like to do?
[1] Keep existing config
[2] Modify existing config
[3] Reset (start fresh)
Choose [1-3] [1]:
1，想修改部分配置选 2，想完全清空重来选 3Gateway mode:
[1] Local (run Gateway on this machine)
[2] Remote (connect to Gateway elsewhere)
Choose [1-2] [1]:
1（Local），在本机运行网关，所有数据都在本地2（Remote）仅用于连接远程服务器上已部署的网关，首次安装不要选向导会先检测环境变量中已有的 API Key，然后列出所有支持的认证方式：
Checking for existing API keys...
✓ Found ANTHROPIC_API_KEY in environment
✗ No MOONSHOT_API_KEY found
Authentication method:
[1] Anthropic API Key (recommended)
[2] Anthropic OAuth (Claude Code CLI)
[3] OpenAI API Key
[6] Moonshot (Kimi K2)
[7] MiniMax M2.1
[8] 智谱 GLM
[11] Skip (configure later)
Choose [1-11] [1]:
6，用 Claude 就选 1~/.openclaw/.env 文件中Workspace location:
Default: ~/.openclaw/workspace
[1] Use default
[2] Custom path
Choose [1-2] [1]:
1，使用默认工作目录，后续可随时修改Gateway settings:
Port: 18789
Bind: 127.0.0.1 (loopback)
Auth: Token (auto-generated)
[1] Keep defaults
[2] Customize
Choose [1-2] [1]:
1，使用默认配置，端口 18789，仅本地可访问，自动生成认证 Token，安全有保障2，禁止新手直接绑定 0.0.0.0，会有严重安全风险Channel setup:
[1] Telegram
[2] WhatsApp
[3] Discord
[4] Google Chat
[5] Signal
[6] Skip (configure later)
Choose channels (comma-separated, e.g., 1,3) [1]:
1（Telegram），配置最简单，稳定性最高，后续可添加其他渠道6 跳过，后续通过 openclaw configure 命令补充配置Daemon installation:
Install Gateway as a background service? This allows Gateway to run automatically on startup.
[1] Yes (recommended)
[2] No (run manually)
Choose [1-2] [1]:
1，安装后台服务，实现开机自启，关闭终端也能正常运行Skills installation:
Skills are plugins that extend Agent capabilities. Recommended skills:
- gmail (email management)
- calendar (calendar integration)
- web-search (Brave Search API)
[1] Install recommended skills
[2] Skip (install later)
Choose [1-2] [1]:
2 跳过，先跑通基础闭环，再按需安装技能插件1，安装推荐技能，后续需单独配置 OAuth 授权向导会自动执行健康检查，验证网关、模型 API、渠道是否正常：
如果你需要用脚本自动化部署，可使用非交互模式，无需手动选择，示例如下：
openclaw onboard --non-interactive \
--mode local \
--auth-choice moonshot-api-key \
--moonshot-api-key "你的 Kimi API Key" \
--gateway-port 18789 \
--gateway-bind loopback \
--install-daemon \
--daemon-runtime node \
--skip-skills
注意：非交互模式的参数可能因版本变化，执行
openclaw onboard --help查看最新可用参数。
如果后续想修改配置，无需重新跑向导，执行以下命令即可进入交互式配置界面，只修改你需要的部分：
openclaw configure
Kimi 是国内用户首选，网络可直连，无需代理，长上下文能力强，OpenClaw 原生支持。
sk-xxx）在 openclaw onboard 的认证方式步骤，选择 6 Moonshot (Kimi K2)，粘贴你复制的 API Key，向导会自动配置好模型参数，无需手动修改。
方式 A：通过交互式命令配置
openclaw configure --section models
# 选择 3 Moonshot (Kimi)
# 粘贴 API Key
# 选择是否设为默认模型
方式 B：直接编辑配置文件编辑 ~/.openclaw/openclaw.json 文件，添加以下配置：
{
"env": {
"MOONSHOT_API_KEY": "你的 Kimi API Key"
},
"agents": {
"defaults": {
"model": {
"primary": "moonshot/kimi-k2.5"
}
}
},
"models": {
"mode": "merge",
"providers": {
"moonshot": {
"baseUrl": "https://api.moonshot.cn/v1",
"apiKey": "${MOONSHOT_API_KEY}",
"api": "openai-completions",
"models": [
{
"id":
保存后，执行 openclaw gateway restart 重启网关生效。
# 查看状态，确认模型已配置
openclaw status
# 健康检查，验证 API 可正常调用
openclaw health
# 发送测试消息，验证模型响应
openclaw agent --agent main --message "你好，用一句话介绍自己"
能正常收到回复，即 Kimi 接入成功。
| 模型 ID | 名称 | 思考能力 | 上下文窗口 | 适用场景 |
|---|---|---|---|---|
| moonshot/kimi-k2.5 | Kimi K2.5 | ❌ | 256K | 通用场景，新手首选 |
| moonshot/kimi-k2-turbo-preview | Kimi K2 Turbo | ❌ | 256K | 快速响应，低成本场景 |
| moonshot/kimi-k2-thinking | Kimi K2 Thinking | ✅ | 256K | 复杂推理、代码开发场景 |
| moonshot/kimi-k2-thinking-turbo | Kimi K2 Thinking Turbo | ✅ | 256K | 快速推理场景 |
/model moonshot/kimi-k2-thinkingopenclaw models set moonshot/kimi-k2.5，然后重启网关MiniMax、智谱 GLM 等国内模型，配置逻辑与 Kimi 一致，在 openclaw onboard 向导中选择对应选项，输入 API Key 即可自动配置，也可参考官方文档手动编辑配置文件。
实现零云端依赖，完全隐私可控，所有数据均在本地处理：
ollama run 模型名称（比如 llama3），确保本地模型正常运行openclaw gateway restart 重启网关，执行 openclaw health 验证模型连通性。编辑 ~/.openclaw/openclaw.json 配置文件，添加以下内容：
{
"agents": {
"defaults": {
"model": {
"primary": "ollama:你的模型名称"
}
}
},
"models": {
"providers": {
"ollama": {
"baseUrl": "http://127.0.0.1:11434",
"api": "openai-completions"
}
}
}
}
Gateway 是 OpenClaw 的核心，所有消息、渠道、会话都由它统一管理，必须确保网关正常运行。
| 运行方式 | 命令 | 适用场景 |
|---|---|---|
| 前台运行（调试用） | openclaw gateway run --port 18789 --verbose | 排查问题时使用，可实时看到日志，按 Ctrl+C 停止 |
| 后台启动（常驻运行） | openclaw gateway start | 日常使用，关闭终端也能运行，需先安装守护进程 |
| 停止网关 | openclaw gateway stop | 停止后台运行的网关 |
| 重启网关 | openclaw gateway restart | 修改配置后，必须重启网关才能生效 |
| 查看网关状态 | openclaw gateway status | 查看网关是否正常运行、PID、端口等信息 |
执行以下 3 条命令，确认网关完全正常：
# 1. 查看网关状态，确认显示 running
openclaw gateway status
# 2. 全量状态检查，确认渠道、模型均正常
openclaw status
# 3. 健康检查，确认无报错
openclaw health
网关启动后，即可通过浏览器访问可视化控制界面，无需敲命令即可完成所有配置、聊天、管理操作。
openclaw dashboard，会自动打开浏览器并跳转到仪表板# 命令行修改
openclaw config set gateway.port 18790
# 重启网关生效
openclaw gateway restart
警告：新手禁止绑定 0.0.0.0，会将网关暴露到公网，有严重安全风险，远程访问请使用 Tailscale 或 SSH 隧道
# 仅本地访问（默认，安全）
openclaw config set gateway.bind loopback
# 仅 Tailscale 网络访问（推荐远程使用）
openclaw config set gateway.bind tailnet
# 局域网访问（仅家庭内网使用）
openclaw config set gateway.bind lan
# 重启网关生效
openclaw gateway restart
openclaw channels status --probe 命令查看Telegram 是 OpenClaw 适配最完善的渠道，新手首选。
@BotFather（带官方蓝标认证），点击进入/newbot 命令，跟着提示设置机器人名称、用户名（用户名必须以 bot 结尾）HTTP API，后面的一串字符就是 Bot Token（格式类似 123456789:ABCdefGHIjklMNOpqrsTUVwxyz），复制保存好方式 A：onboard 向导配置在初始化向导的渠道步骤，选择 1 Telegram，粘贴你复制的 Bot Token，向导会自动完成配置。
方式 B：手动命令配置
# 进入渠道配置界面
openclaw configure --section channels.telegram
# 按提示粘贴 Bot Token，回车确认
# 重启网关生效
openclaw gateway restart
方式 C：Web 界面配置打开 Web 仪表板 → 渠道管理 → 选择 Telegram → 粘贴 Bot Token → 点击保存，自动完成配置。
✓ Pairing approved，即配对完成，回到 Telegram，重新发送消息，机器人就会正常响应了。执行以下命令，批准配对（替换为你的配对码）：
openclaw pairing approve telegram <你的配对码>
回到终端，执行以下命令，查看待处理的配对请求：
openclaw pairing list telegram
如果你想让指定用户无需配对，直接使用，可配置白名单：
~/.openclaw/openclaw.json 配置文件添加以下配置，替换为你的 Telegram 用户 ID（可通过 @userinfobot 获取）：
{
"channels": {
"telegram": {
"dmPolicy": "pairing",
"allowFrom": [123456789, 987654321]
}
}
}
编辑配置文件，添加群聊配置：
{
"channels": {
"telegram": {
"groups": {
"*": {
"requireMention": true
}
}
}
},
"messages": {
"groupChat": {
"mentionPatterns": ["@你的机器人用户名"]
}
}
}
openclaw pairing list whatsapp 查看配对码，执行 openclaw pairing approve whatsapp <配对码> 批准后，才能正常响应channels.whatsapp.allowFrom 中添加允许的手机号（格式为 +8613800138000）终端执行以下命令，启动登录流程：
openclaw channels login
bot 和 applications.commands，然后在 Bot 权限中勾选发送消息、读取消息、管理消息等基础权限，复制生成的 URL，在浏览器中打开，邀请机器人到你的服务器openclaw configure --section channels.discord，粘贴 Bot Token，重启网关生效openclaw configure --section channels.imessage，完成配置先安装 imsg CLI 工具，终端执行：
brew install keith/formulae/imsg
很多新手一上来就配置大量功能，结果出问题找不到原因，正确的做法是先跑通「发指令→真执行→回结果」的最小闭环，验证全链路通畅。
给你的机器人发送以下消息，能稳定收到回复，说明聊天链路、模型调用完全正常：
如果没收到回复，直接跳转到第十三章故障排查，按步骤排查问题，不要继续往下走。
选择无风险、不会造成系统损坏的任务，验证智能体的执行能力，推荐以下测试指令，按顺序执行：
能完整执行以上步骤，返回正确结果，说明最小闭环完全跑通，你已经可以正常使用 OpenClaw 的所有能力了。
每次修改配置、出现异常时，先执行以下 3 条命令，可定位 90% 的问题：
# 1. 查看全量状态
openclaw status
# 2. 健康检查，验证网关、模型、渠道是否正常
openclaw health
# 3. 自动诊断并修复常见问题
openclaw doctor --fix
直接在聊天窗口发送图片、音频、文档、压缩包等文件，再补充对应的需求指令即可，支持几乎所有常见格式，示例：
| 场景 | 指令示例 |
|---|---|
| 系统操作 | 帮我列出当前电脑桌面的所有文件，按文件大小排序，标注每个文件的修改时间 |
| 代码开发 | 帮我写一个 Python 爬虫，抓取某网站的公开文章标题、发布时间、链接，保存到 Excel 文件，要求加入异常处理，避免被反爬 |
| 代码优化 | 帮我优化这段 PostgreSQL 查询语句，分析执行计划，添加合适的索引，把查询耗时从 8s 降到 100ms 以内 |
| 浏览器自动化 | 帮我打开 Chrome 浏览器，访问某购物网站，筛选价格 100-300 元的商品，按销量排序，截图前 10 个商品的信息，保存到工作目录 |
| 邮件管理 | 帮我读取今天的收件箱，把促销类、广告类邮件标为已读并归档，把工作相关的重要邮件整理成摘要，按优先级排序 |
| 运维部署 | 帮我写一个 K8s 部署配置文件，完成 3 个微服务的部署、ingress 配置、健康检查，注释每一项的作用 |
| 文档处理 | 帮我润色这份工作总结，优化语言逻辑，突出工作成果和数据亮点，适配正式的年终汇报场景，控制在 3000 字以内 |
| 安全审计 | 帮我对这段代码做安全审计，找出 SQL 注入、XSS 等安全漏洞，给出修复方案和完整的修复代码 |
OpenClaw 内置了 3 个核心工具，无需额外安装即可使用：
技能是扩展 OpenClaw 能力的插件，目前有 100 + 预置技能，支持 50 + 第三方服务对接，比如 Gmail、日历、智能家居、音乐平台等。
命令行安装：
# 查看可用技能列表
openclaw skills list
# 安装指定技能
openclaw skills install gmail
# 配置技能
openclaw skills config gmail
# 更新技能
openclaw skills update gmail
| 技能名称 | 核心作用 |
|---|---|
| gmail | 邮件管理，读取、发送、归档、筛选邮件 |
| calendar | 日历管理，创建、查看、修改日程，设置提醒 |
| web-search | 网页搜索，支持 Brave Search，获取实时网络信息 |
| github | GitHub 管理，查看 Issue、提交 PR、管理仓库 |
| home-assistant | 智能家居控制，对接 Home Assistant |
OpenClaw 支持配置多个独立的 Agent，每个 Agent 使用不同的模型、技能、权限、工作目录，按发送者、渠道自动路由，实现场景隔离。
示例配置：编辑 ~/.openclaw/openclaw.json，添加以下内容
{
"agents": {
"default": {
"model": "moonshot/kimi-k2.5",
"skills": ["file-system", "terminal"],
"workspace": "~/.openclaw/workspace/default"
},
"code-agent": {
"model": "anthropic/claude-3-5-sonnet-20241022",
"skills": ["git", "code-review", "testing"],
"workspace": "~/code",
"allowFrom": ["+8613800138000", 123456789]
},
"local-agent": {
保存配置，重启网关生效，即可实现：指定用户使用代码专属 Agent，Telegram 渠道使用本地模型 Agent，其他用户使用默认 Agent，上下文、权限、能力完全隔离。
OpenClaw 支持配置 Cron 定时任务，实现无人值守自动化执行，比如每天 9 点清邮件、每周五生成数据报告、每天凌晨备份文件等。
配置方法：
~/.openclaw/openclaw.json 配置文件，添加 cron 配置项示例：每天 9 点执行清邮件任务，每周五 18 点生成周报
{
"cron": {
"jobs": [
{
"name": "daily-email-cleanup",
"schedule": "0 9 * * *",
"agent": "default",
"message": "帮我清理今天的收件箱，把广告、促销邮件标为已读并归档，整理重要工作邮件的摘要，发送到我的 Telegram"
},
{
"name": "weekly-report",
"schedule": "0 18 * * 5",
"agent": "default",
"message": "帮我读取本周的工作文档、邮件、Git 提交记录，生成一份完整的工作周报，突出核心成果和下周计划"
}
]
}
}
如果你需要在其他设备访问 OpenClaw，禁止直接暴露公网端口，推荐以下两种安全方案：
终端执行以下命令，配置网关绑定 Tailscale 网络：
openclaw config set gateway.bind tailnet
openclaw gateway restart
在本地访问设备上，执行以下命令，建立 SSH 隧道：
ssh -N -L 18789:127.0.0.1:18789 你的服务器用户名@服务器IP
OpenClaw 支持配对 iOS 和 Android 移动节点，扩展 Canvas、移动端相机、文件访问等能力，步骤如下：
你可以自己编写技能插件，扩展 OpenClaw 的能力，甚至让 OpenClaw 帮你生成技能代码：
index.js 入口文件、package.json 依赖配置、README.md 说明文档openclaw skills install 本地技能路径 安装，也可发布到社区，供其他用户使用。OpenClaw 拥有你设备的系统权限，一旦配置不当，可能导致数据泄露、系统损坏、API 额度被盗刷，必须做好安全加固。
OpenClaw 通过三层权限控制：Sandbox 沙箱、Tool Policy 工具策略、Elevated 权限，新手必须先配置沙箱，限制 Agent 的权限范围。
openclaw sandbox explain
可查看当前 Agent 的沙箱模式、工作目录权限、工具允许列表、提权状态。
编辑 ~/.openclaw/openclaw.json，添加以下配置，推荐新手使用 non-main 模式：
{
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main",
"scope": "agent",
"workspaceAccess": "rw",
"bindMounts": [
{
"source": "~/Downloads",
"target": "/downloads",
"access": "ro"
}
]
}
}
}
}
mode: non-main：主会话在主机运行，其他会话全部在沙箱中运行，平衡便利性与安全性，新手首选mode: all：所有会话全部在沙箱中运行，最高安全性mode: off：关闭沙箱，Agent 可直接访问主机系统，仅完全信任时使用workspaceAccess: ro：只读权限，rw：读写权限，新手先设为 ro，验证稳定后再开放 rwbindMounts：挂载指定目录到沙箱，可设置只读 / 读写权限，避免 Agent 访问无关目录{
"agents": {
"defaults": {
"tools": {
"allow": ["read", "exec"],
"deny": ["write", "delete", "edit", "sudo"],
"sandbox": {
"tools": {
"allow": ["read"],
"deny": ["write", "delete", "exec"]
}
}
}
}
}
}
allow：允许使用的工具，新手先只开放 read，逐步添加deny：禁止使用的工具，必须禁止 sudo、rm -rf 等高风险操作read 工具，禁用 execread、exec，禁用 write、deletebindMounts 限制范围启用网关 Token 认证：即使是本地访问，也必须启用 Token 认证，防止本地其他进程误连
openclaw config set gateway.auth.mode token
# 生成强随机 Token，替换为你自己的
openclaw config set gateway.auth.token "你的强随机 Token"
openclaw gateway restart
防火墙配置：只允许本地访问网关端口，禁止公网入站访问
# Linux ufw 防火墙配置
sudo ufw allow from 127.0.0.1 to any port 18789
sudo ufw deny 18789
sudo ufw reload
禁止绑定公网地址：必须确保网关只绑定 127.0.0.1 或 tailnet，禁止绑定 0.0.0.0
# 检查当前绑定地址
openclaw status --all | grep "Bind"
# 修正为本地回环地址
openclaw config set gateway.bind loopback
openclaw gateway restart
~/.openclaw/.env 文件中✅ 正确做法：所有敏感信息都通过环境变量配置，~/.openclaw/.env 文件权限设为 600，仅当前用户可读写
chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/.env
chmod 700 ~/.openclaw/workspace/
可配置高风险命令执行前必须经过你的手动批准，避免 Agent 误执行危险操作，比如 rm -rf、dd、格式化磁盘等命令。
# 添加需要审批的危险命令
openclaw approvals allowlist add "rm -rf"
openclaw approvals allowlist add "/usr/bin/dd"
openclaw approvals allowlist add "mkfs"
openclaw approvals allowlist add "sudo"
# 查看当前审批配置
openclaw approvals get
配置完成后，Agent 执行这些命令时，会先向你发送审批请求，你点击确认后，才会执行，避免误操作。
也可以通过 JSON 文件批量导入审批规则：
导入配置：
openclaw approvals set --file ./exec-approvals.json
创建 exec-approvals.json 文件：
{
"allowlist": [
"rm -rf",
"/usr/bin/dd",
"mkfs",
"sudo",
"shutdown",
"reboot"
]
}
执行以下命令，定期对 OpenClaw 做深度安全审计，及时发现安全隐患：
# 基础安全审计
openclaw security audit
# 深度安全审计，全面检查配置、权限、网络、凭证
openclaw security audit --deep
审计完成后，会列出所有安全隐患和修复建议，按提示及时修复即可。
| 检查频率 | 检查命令 | 检查目的 |
|---|---|---|
| 每日 | openclaw status openclaw health | 确认网关、模型、渠道正常运行 |
| 每周 | openclaw status --all openclaw doctor | 全面检查系统状态，自动修复常见问题 |
| 每周 | `openclaw logs --limit 500 | grep -i error` |
| 每月 | openclaw security audit --deep | 安全审计，修复安全隐患 |
| 每月 | 检查模型 API 使用额度 | 避免额度超额，及时发现异常调用 |
# 实时查看运行日志，排查问题必备
openclaw logs --follow
# 实时查看日志，只过滤错误和警告
openclaw logs --follow | grep -i "error\|warning\|unauthorized"
# 查看最近 100 行日志
openclaw logs --limit 100
# 查看最近 1 小时的日志
openclaw logs --since 3600000
# 清理 7 天前的旧日志
find /tmp/openclaw -name "openclaw-*.log" -mtime +7 -delete
# 备份主配置文件
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup.$(date +%Y%m%d)
# 备份环境变量和凭证
cp -r ~/.openclaw/credentials/ ~/.openclaw/backup/credentials-$(date +%Y%m%d)
cp ~/.openclaw/.env ~/.openclaw/backup/.env.backup.$(date +%Y%m%d)
# 备份整个工作区
tar -czvf ~/openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/ --exclude='*.log' --exclude='sessions/'
chmod +x ~/.openclaw/backup.sh添加定时任务，每天凌晨 2 点自动备份：
crontab -e
# 添加以下内容
0 2 * * * ~/.openclaw/backup.sh >> ~/.openclaw/backup.log 2>&1
创建备份脚本 ~/.openclaw/backup.sh：
#!/bin/bash
BACKUP_DIR=~/openclaw-backups
mkdir -p $BACKUP_DIR
DATE=$(date +%Y%m%d)
# 备份配置
cp ~/.openclaw/openclaw.json $BACKUP_DIR/openclaw.json.backup.$DATE
cp ~/.openclaw/.env $BACKUP_DIR/.env.backup.$DATE
tar -czvf $BACKUP_DIR/openclaw-full-backup-$DATE.tar.gz ~/.openclaw/ --exclude='*.log' --exclude='sessions/'
# 保留最近 30 天的备份
find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete
# 恢复配置文件
cp ~/openclaw-backups/openclaw.json.backup.20260204 ~/.openclaw/openclaw.json
# 恢复完整备份
tar -xzvf ~/openclaw-backups/openclaw-full-backup-20260204.tar.gz -C ~/
# 重启网关生效
openclaw gateway restart
OpenClaw 更新频繁，建议每月更新一次，获取最新功能和 bug 修复，更新前务必备份配置。
# 1. 停止网关服务
openclaw gateway stop
# 2. 备份配置（必做）
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup.before-update
# 3. 执行更新（一键脚本安装的用户）
curl -fsSL https://openclaw.ai/install.sh | bash
# NPM 安装的用户执行：npm install -g openclaw@latest
# 4. 运行诊断，修复配置兼容问题
openclaw doctor --fix
# 5. 重启网关服务
openclaw gateway start
# 6. 验证更新成功，查看新版本号
openclaw --version
openclaw status
openclaw doctor --fix 修复配置兼容性问题适合服务器 7×24 小时部署的用户，配置监控脚本，网关异常时自动重启并告警。
chmod +x ~/.openclaw/monitor.sh添加定时任务，每小时执行一次：
crontab -e
# 添加以下内容
0 * * * * ~/.openclaw/monitor.sh
创建监控脚本 ~/.openclaw/monitor.sh：
#!/bin/bash
LOG_FILE=~/.openclaw/monitor.log
echo "=== $(date) ===" >> $LOG_FILE
# 检查网关状态
if ! openclaw gateway status | grep -q "running"; then
echo "⚠️ Gateway 未运行，尝试重启..." >> $LOG_FILE
openclaw gateway restart >> $LOG_FILE 2>&1
# 重启后再次检查
sleep 5
if openclaw gateway status | grep -q "running"; then
echo "✅ Gateway 重启成功" >> $LOG_FILE
else
echo "❌ Gateway 重启失败，请手动排查" >> $LOG_FILE
# 可在这里添加邮件/企业微信/飞书告警通知
fi
fi
# 健康检查
if ! openclaw health | grep -q "Model API: ✓ accessible"; then
echo "⚠️ 模型 API 调用异常，请检查 API Key 和网络" >> $LOG_FILE
fi
# 清理 7 天前的旧日志
find /tmp/openclaw -name "openclaw-*.log" -mtime +7 -delete
# 清理临时文件
rm -rf ~/.openclaw/tmp/*
# 清理过期会话缓存（保留最近 30 天）
find ~/.openclaw/agents/*/sessions/ -mtime +30 -delete
# 清理 npm 缓存
npm cache clean --force
遇到问题时，先执行 openclaw doctor --fix，可自动修复 80% 的常见问题，若无法解决，再按以下场景排查。
command not found核心原因：npm 全局安装目录不在系统 PATH 环境变量中
排查 & 解决步骤：
若能找到安装路径，将路径添加到系统 PATH 中
# macOS/Linux/WSL2
export PATH="$(npm prefix -g)/bin:$PATH"
# 永久生效
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Windows PowerShell
$npmPath = npm prefix -g
$env:Path += ";$npmPath"
# 永久生效
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$npmPath", "User")
先查找 openclaw 的安装位置
# macOS/Linux/WSL2
which openclaw
find /usr -name openclaw -type f 2>/dev/null
find ~/.npm -name openclaw -type f 2>/dev/null
# Windows PowerShell
where.exe openclaw
排查 & 解决步骤：
node -v，确认版本≥22.0.0，低于该版本请升级 Node.jscurl https://api.anthropic.com/v1/messages --head 验证网络连通性launchctl list | grep openclaw，查看系统日志 log show --predicate 'process == "openclaw"' --last 5m，重新安装守护进程 openclaw configure --section gateway，选择重新安装 daemonsystemctl --user status openclaw-gateway，确认已启用 systemd，启用 lingering sudo loginctl enable-linger $USER，避免用户登出后服务停止。常见报错 2：配置文件 JSON 格式错误
# 运行诊断，检查配置文件
openclaw doctor
# 若提示 JSON 格式错误，修复配置文件语法，或重置配置
openclaw reset
# 选择"Config only"，仅重置配置，保留凭证和会话
常见报错 1：Error: Port 18789 is already in use（端口被占用）
# 查看占用端口的进程
# macOS/Linux/WSL2
lsof -i :18789
# Windows PowerShell
netstat -ano | findstr :18789
# 解决方法 1：杀死占用进程（替换为实际 PID）
kill -9 12345 # Linux/macOS
Stop-Process -Id 12345 -Force # Windows
# 解决方法 2：更换端口启动
openclaw config set gateway.port 18790
openclaw gateway restart
前台启动网关，查看详细报错信息
openclaw gateway run --port 18789 --verbose
排查 & 解决步骤（按顺序执行）：
allowFrom，确认你的手机号 / 用户 ID 已添加到白名单，或配置的免配对规则正确。openclaw health，确认模型 API 可正常调用，若 API 报错，检查 API Key 是否有效、是否有额度、网络是否正常。查看实时日志，确认消息是否到达网关
openclaw logs --follow | grep -i "channel\|message"
第三步：确认配对已批准（90% 新手的问题）
# 查看待处理的配对请求
openclaw pairing list telegram
# 替换为你的渠道
# 若有 pending 的配对请求，批准配对
openclaw pairing approve telegram <配对码>
第二步：确认渠道已正常连接
# 查看渠道状态，探测连通性
openclaw channels status --probe
# 若显示 disconnected，重新配置渠道 Token，重启网关
openclaw configure --section channels.telegram
openclaw gateway restart
第一步：确认网关正常运行
openclaw gateway status
# 若未运行，启动网关
openclaw gateway start
排查 & 解决步骤：
tools.allow，确认对应的工具已在允许列表中，比如执行终端命令需要开放 exec 工具。Permission denied（权限不足）
bindMounts 挂载需要访问的目录第五步：查看详细报错日志
openclaw logs --follow | grep -i "error\|tool\|exec"
根据日志中的具体报错，修复对应问题。
第四步：常见报错：浏览器启动失败
# 验证浏览器安装
google-chrome --version
chromium --version
# 未安装则执行安装
# macOS
brew install --cask google-chrome
# Linux/Ubuntu
sudo apt-get update && sudo apt-get install chromium-browser
第二步：确认沙箱权限配置正确
# 查看当前沙箱权限
openclaw sandbox explain
# 若权限不足，修改沙箱配置，开放对应的目录访问权限
排查 & 解决步骤：
401 Unauthorized（未授权）
403 Forbidden（禁止访问）
https://api.moonshot.cn/v1，不要用海外地址执行 curl 命令，直接测试 API 连通性
# 测试 Kimi API
curl https://api.moonshot.cn/v1/chat/completions \
-H "Authorization: Bearer 你的 Kimi API Key" \
-H "Content-Type: application/json" \
-d '{"model":"kimi-k2.5","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'
执行健康检查，查看具体报错信息
openclaw health
排查 & 解决步骤：
若终端代理生效，但 OpenClaw 还是无法访问，直接在配置文件中设置代理
openclaw config set gateway.proxy.url "http://127.0.0.1:7890"
openclaw gateway restart
若使用海外模型，必须配置系统代理，且终端代理生效
# 确认代理环境变量已设置
env | grep -E "(HTTPS_PROXY|HTTP_PROXY)"
# 测试代理是否生效
curl https://api.anthropic.com/v1/messages --head
macOS 排查步骤：
~/.openclaw/.env 文件存在，API Key 已正确写入openclaw configure --section gateway，选择重新安装 daemon查看系统日志，定位报错原因
openclaw logs --follow
log show --predicate 'process == "openclaw"' --last 5m
查看 LaunchAgent 状态
launchctl list | grep openclaw
Linux/WSL2 排查步骤：
sudo loginctl enable-linger $USERopenclaw configure --section gateway，选择重新安装 daemon查看 systemd 服务状态
systemctl --user status openclaw-gateway
若出现配置混乱、无法启动、未知错误，可按以下步骤紧急恢复：
若仍有问题，恢复备份的配置文件，重启网关
cp ~/.openclaw/openclaw.json.emergency ~/.openclaw/openclaw.json
openclaw gateway start
重新执行初始化配置
openclaw onboard
重置配置，保留工作区和凭证
openclaw reset
# 选择"Config only"，仅重置配置
备份当前配置（必做，避免丢失凭证）
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.emergency
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.emergency
停止网关服务
openclaw gateway stop
| 命令 | 核心作用 |
|---|---|
openclaw --version | 查看当前版本号 |
openclaw --help | 查看帮助文档，所有命令用法 |
openclaw status | 查看核心状态概览 |
openclaw status --all | 查看全量详细状态，调试必备 |
openclaw health | 健康检查，验证网关、模型、渠道 |
openclaw doctor | 自动诊断常见问题 |
openclaw doctor --fix | 自动诊断并修复常见问题 |
openclaw dashboard | 自动打开 Web 仪表板 |
openclaw update | 更新 OpenClaw 到最新版本 |
| 命令 | 核心作用 |
|---|---|
openclaw gateway start | 后台启动网关服务 |
openclaw gateway stop | 停止后台网关服务 |
openclaw gateway restart | 重启网关服务（修改配置后必执行） |
openclaw gateway status | 查看网关运行状态、PID、端口 |
openclaw gateway run --verbose | 前台运行网关，实时输出日志，调试必备 |
openclaw gateway install | 安装网关后台守护进程 |
openclaw gateway uninstall | 卸载网关后台守护进程 |
| 命令 | 核心作用 |
|---|---|
openclaw configure | 进入交互式配置界面，修改所有配置 |
openclaw configure --section xxx | 配置指定模块，比如 channels.telegram |
openclaw config get | 查看完整的配置文件 |
openclaw config get xxx | 查看指定配置项，比如 gateway.port |
openclaw config set xxx yyy | 设置指定配置项的值 |
openclaw config unset xxx | 删除指定配置项 |
openclaw reset | 重置配置，可选择仅重置配置或全量重置 |
| 命令 | 核心作用 |
|---|---|
openclaw models list | 查看所有可用的模型列表 |
openclaw models status | 查看当前默认模型的状态 |
openclaw models scan | 扫描可用的模型，包括本地 Ollama 模型 |
openclaw models set 模型 ID | 设置默认模型 |
openclaw models probe 模型 ID | 测试指定模型的连通性 |
| 命令 | 核心作用 |
|---|---|
openclaw channels login | 渠道登录，主要用于 WhatsApp 扫码登录 |
openclaw channels logout | 退出渠道登录 |
openclaw channels list | 查看所有已配置的渠道列表 |
openclaw channels status | 查看所有渠道的运行状态 |
openclaw channels status --probe | 探测所有渠道的连通性 |
| 命令 | 核心作用 |
|---|---|
openclaw pairing list 渠道名 | 查看指定渠道的待处理配对请求 |
openclaw pairing approve 渠道名 配对码 | 批准指定配对请求 |
openclaw pairing deny 渠道名 配对码 | 拒绝指定配对请求 |
openclaw pairing list --all | 查看所有渠道的配对请求 |
| 命令 | 核心作用 |
|---|---|
openclaw agents list | 查看所有已配置的 Agent 列表 |
openclaw agents add 代理名 --workspace 路径 | 添加新的 Agent |
openclaw agents status 代理名 | 查看指定 Agent 的状态 |
openclaw agent --agent 代理名 --message "xxx" | 给指定 Agent 发送测试消息 |
openclaw sessions list | 查看所有活跃会话 |
openclaw sessions history 会话 ID | 查看指定会话的历史记录 |
openclaw sessions reset 会话 ID | 重置指定会话的上下文 |
| 命令 | 核心作用 |
|---|---|
openclaw skills list | 查看所有已安装的技能列表 |
openclaw skills install 技能名 | 安装指定技能 |
openclaw skills uninstall 技能名 | 卸载指定技能 |
openclaw skills config 技能名 | 配置指定技能 |
openclaw skills update 技能名 | 更新指定技能到最新版本 |
openclaw skills update --all | 更新所有已安装的技能 |
| 命令 | 核心作用 |
|---|---|
openclaw logs --follow | 实时查看运行日志，排查问题必备 |
openclaw logs --limit 100 | 查看最近 100 行日志 |
openclaw logs --since 3600000 | 查看最近 1 小时的日志 |
openclaw security audit | 基础安全审计 |
openclaw security audit --deep | 深度安全审计 |
openclaw sandbox explain | 查看当前沙箱权限配置 |
openclaw approvals get | 查看高风险命令审批配置 |
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online