Hidewnd Docs
Vibe Coding

OpenClaw

OpenClaw

项目地址：https://github.com/openclaw/openclaw

官网地址：https://openclaws.io/zh/

文档测试机器： Apple Mac mini/M1/16GB

介绍

OpenClaw 是开源、可本地部署的 AI 助手/Agent 平台，支持多系统、多入口。不是你聊一句它回一句的“聊天机器人”，而是把对话入口（各种 Channel）和“能真干活”的执行层（Tools + 多模型）接到一起的编排运行时。2025 年底开源后热度很高，适合当“自己的私人 Agent 中枢”，前提是理解其安全边界（见下风险节）。

本质

  • 定位：基础设施/编排层，不是模型层。模型负责“决定做什么”（推理、规划、选工具），OpenClaw 负责“在哪儿接消息、怎么路由、谁可以执行、执行什么、结果怎么回”。
  • 一句话：多入口、单内核（multi-ingress, single-kernel）——不管从 Telegram、Discord、Web UI 还是 Webhook 进来，都走同一套 Gateway → Agent → Tools，会话用 sessionKey 隔离，执行用同一套策略（沙箱/审批/权限）。
  • 和 Cursor/Claude Code 的区别：后者偏“IDE 内 + 单会话”；OpenClaw 偏“多端接入 + 多会话 + 可插 Skill”，更像自建 Agent 中台。

功能概览

层面能力
入口（Channels）WhatsApp / Telegram / Discord / Slack / Web UI / Webhook / Cron 等，消息统一进 Gateway
控制面（Gateway）会话路由、并发（lane/queue）、认证、WebSocket/HTTP API、事件广播
执行面（Agent）Agentic loop：收消息 → 组上下文 → 调模型 → 调工具 → 流式输出 → 持久化会话
能力层Providers：多模型 + failover（Claude/GPT/Gemini/Ollama/自建等）；Tools：Shell、浏览器、HTTP、文件、邮件、日历等；Skills：可插拔扩展（ClawHub 等）
数据与安全会话 JSONL 持久化、日志与审计、沙箱/工具策略/审批、谁可连（token/pairing）

开发者视角：你装一个 Gateway，配好模型和 Skill，就能从多个端（包括自己写的客户端）发任务，由同一个 Agent 在本机或受控环境里执行，结果再通过对应 Channel 回给你。

工作原理（数据流）

整体是 ingress → control plane → execution，一条消息的路径大致如下：

  1. Ingress：某 Channel 收到消息（或 Webhook/Cron 触发），按账号/群/线程等生成 sessionKey，避免跨会话串话。
  2. 路由：Gateway 按 sessionKey 把消息丢进对应会话队列；同 session 串行，不同 session 可并行。
  3. Control plane：Gateway 协调会话、鉴权、把“待处理”交给执行面，并对外暴露 WS/HTTP、广播事件（方便 Control UI 观测）。
  4. Execution：Agent 取到消息后进入 agentic loop：组上下文（含历史）→ 调 Provider 拿模型输出 → 若含 tool call 则交给 Tools 层执行（Shell/浏览器/API 等）→ 结果再喂回模型，直到模型产出最终回复或结束。
  5. Egress：最终回复经 Channel 回给用户；会话状态（含本轮）持久化到 JSONL。

排查时可在 Control UI 或日志里按同一 runId 跟完上述几步；安全上要同时看 ingress 边界（谁可连）、执行边界（沙箱/工具策略/审批）、以及审计（日志别漏敏感信息）。

风险

  • 基础设计偏“实验性”，默认不安全
    • 默认网关开放 + 默认弱/无认证，等价于在本机挂一个“能执行任意命令的 HTTP 代理”。
    • Web UI 支持通过 gatewayUrl 等参数自动连接，如果被钓鱼页面劫持（XSS / 恶意跳转），有远程命令被代为执行的风险。
  • 远程代码执行（RCE）相关 CVE 披露
    • 2026 年前后社区披露过多起严重漏洞（含一键 RCE / WebSocket 劫持等），部分标注为高危 CVSS（8.x+）。
    • 结论：不要把 OpenClaw 面向公网暴露，也不要直接跑在生产服务器上当“自动运维工具”。
  • 技能（Skill）生态存在恶意包
    • 第三方 Skill 具备“代码执行 + 网络访问”能力，本质上和安装随机 npm/py 包没差。
    • 安装前至少看仓库 Star / 提交记录 / 代码结构，能自己过一眼核心逻辑更好。
  • 系统权限过大
    • 给到主机文件、Shell、SSH、云 API 等权限时，要当作“给另一个有完整 root/管理员权限的人”在本机操作。
    • 建议：日常只给最低权限（只读代码仓库 + 只读配置），需要高危操作时再临时提权。
  • 个人规避策略（自用准则）
    • 只在本机 / 内网环境使用，网关端口不暴露公网，不穿透。
    • 尽量跑在隔离环境：本地 VM / Docker / 专门用户；重要 SSH key、云凭证不要放同一环境。
    • 所有 Skill 默认不信任，遇到“自动修改生产资源”的一律关掉；涉及删库/销毁资源的操作必须人工二次确认。
    • 把 OpenClaw 当作“高级脚本生成器 + 本地助手”，而不是“全自动 Agent 托管生产系统”。

安装

以下以 macOS + 本地开发环境 为例，仅记录自己使用的最小可用路径，具体以官方文档为准。

依赖

  • Node.js 20+（推荐使用 fnm / nvm 管理）
  • Python 3.10+（如需 Python 相关 Skill）
  • Docker（可选，用来跑隔离的代理 / 工具）

基本安装流程

方式一：源码克隆（开发/贡献）

适合需要改源码、调试或参与贡献时使用。

Terminal window
# 1. 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw


# 2. 安装依赖
pnpm install   # 或 yarn / npm，按官方推荐


# 3.（可选）复制示例配置
cp .env.example .env.local

方式二：官方一键脚本（推荐日常使用）

自动安装 Node.js、Python 和 OpenClaw CLI，适合本机快速体验。

  • macOS / Linux：
    Terminal window
    curl -sSL https://openclaw.ai/install.sh | bash
  • Windows（PowerShell）：
    Terminal window
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta

安装完成后运行 openclaw onboard --install-daemon 按向导完成配置（API Key、Channel、可选 Skill）。

方式三：npm / pnpm 全局安装

需已安装 Node.js 22+。

Terminal window
# 任选其一
npm install -g openclaw@latest
# 或
pnpm add -g openclaw@latest


# 首次配置（API Key、Channel、守护进程等）
openclaw onboard --install-daemon

方式四：Docker

若官方提供镜像，可容器化部署，便于隔离与迁移。具体镜像名、端口映射以 官方文档 为准；卸载示例：docker rm -f openclaw。

Ollama 适配

用 Ollama 跑本地模型时，无需云端 API Key，数据不出本机，适合隐私或离线场景。

前置条件

  1. 安装 Ollama，并拉取所需模型，例如：
    Terminal window
    ollama pull llama3.2
    ollama pull qwen2.5:7b
  2. 确认 Ollama 服务可访问：本机一般为 http://127.0.0.1:11434，可用 curl http://127.0.0.1:11434/api/tags 检查。

OpenClaw 侧配置

  • 在 ~/.config/openclaw/openclaw.json5（或 ~/.openclaw/openclaw.json）的 models.providers 中增加：
    "ollama": {
      "baseUrl": "http://127.0.0.1:11434/v1",
      "api": "openai-responses"
    }
  • 必须 设置 "api": "openai-responses"，否则容易出现 0 tokens / 无响应。
  • 设默认模型为 Ollama 模型：
    Terminal window
    openclaw models set ollama/llama3.2
    openclaw gateway restart

Docker 内访问本机 Ollama

若 OpenClaw 跑在 Docker 里、Ollama 跑在宿主机，baseUrl 需指向宿主机：

  • Mac/Windows Docker Desktop：http://host.docker.internal:11434/v1
  • Linux：可用 --add-host=host.docker.internal:host-gateway 或宿主机实际 IP，例如 http://172.17.0.1:11434/v1

常见问题

  • 0 tokens / 无回复：检查是否已设 "api": "openai-responses"，并确认 Ollama 版本较新、模型已成功拉取。
  • 连接超时：防火墙或 Docker 网络是否放行 11434 端口；容器内用 host.docker.internal 或宿主机 IP。

本地只开本机访问

Terminal window
# 网关绑定 127.0.0.1，避免意外暴露局域网/公网
OPENCLAW_GATEWAY_HOST=127.0.0.1 \
OPENCLAW_GATEWAY_PORT=8288 \
pnpm dev

浏览器访问：http://localhost:xxxx（按实际配置），确认仅自己机器可访问。

彻底卸载与清理

以下按顺序执行，可移除主程序并清空所有相关数据与配置；若只打算「保留数据、仅卸 CLI」，可只做「步骤 1 + 步骤 2」。

步骤 1：停止所有服务

Terminal window
# 若曾用 onboard 安装过守护进程，先停掉
openclaw daemon stop


# 若曾用 gateway install 装成系统服务，先卸载服务再停
openclaw gateway uninstall
# 或仅停止：openclaw gateway stop

确认本机没有 openclaw 相关进程（如网关、UI）在跑，必要时 kill 残留进程或重启后再做步骤 2。

步骤 2：卸载主程序（按你的安装方式选一种）

安装方式操作
npm 全局npm uninstall -g openclaw
pnpm 全局pnpm remove -g openclaw
一键脚本同上，脚本本质也是装全局 CLI，用对应包管理器卸
仅源码运行无需卸包，直接删源码目录（见步骤 3 末尾）

步骤 3：删除数据与配置目录

数据与配置可能分布在两处，建议都检查并删除：

  • 默认数据目录（会话、技能、日志、soul.md、.env 等）
    • macOS/Linux：rm -rf ~/.openclaw
    • Windows：在资源管理器中删除 %USERPROFILE%\.openclaw，或在 PowerShell 中：Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw
  • XDG 配置目录（部分版本把 openclaw.json5 放这里）
    • macOS/Linux：rm -rf ~/.config/openclaw
    • Windows：删除 %APPDATA%\openclaw 或 %USERPROFILE%\.config\openclaw（若存在）

若你设置过 OPENCLAW_HOME，数据实际在 $OPENCLAW_HOME（或 %OPENCLAW_HOME%）下，请同样删除该目录。

步骤 4：Docker 部署的清理

若 OpenClaw 是跑在容器里的：

Terminal window
docker rm -f openclaw    # 容器名以你实际为准，如 openclaw-gateway
docker rmi openclaw      # 需要时再删镜像
docker volume ls        # 若有挂载的 volume，用 docker volume rm <name> 删除

步骤 5：源码克隆方式的额外清理

若曾用「方式一」在本地克隆过仓库并跑过：

  • 直接删掉整个克隆目录即可（内含 node_modules、.env.local 等），例如：
    rm -rf /path/to/openclaw

验证

  • which openclaw（Windows 下为 where openclaw）应无输出或报错。
  • 再次安装时不会读到旧配置与数据，等同于全新环境。

删除 ~/.openclaw 会丢失会话历史、已装 Skill、soul.md 及本地配置；若有需要请先备份再删。

配置

这里只记个人使用时关注的最小配置项，完整字段参考官方文档。

环境变量（示例思路）

  • 网关与 UI 安全相关
    • OPENCLAW_GATEWAY_HOST=127.0.0.1：强制只监听本机。
    • OPENCLAW_UI_ORIGIN=http://localhost:xxxx：限制 Web UI 来源。
  • 日志与审计
    • 开启详细日志，方便出问题时回溯（但注意不要在日志里输出密钥）。
  • 模型与 API Key
    • LLM / 向量库等 API Key 统一集中在 .env.local 或系统密钥管理中，不要硬编码到 Skill 里。

模型切换与多 Provider

  • 配置位置：~/.config/openclaw/openclaw.json5 或 ~/.openclaw/openclaw.json（因版本/安装方式而异，以官方文档为准）。
  • 快速改默认模型：
    Terminal window
    openclaw models set anthropic/claude-sonnet-4-20250514
    openclaw models set openai/gpt-4o
    openclaw models set ollama/llama3.2   # 本地 Ollama
    改完后一般要 openclaw gateway restart 才生效。
  • 交互式配置：openclaw configure 或 openclaw onboard，按提示选 provider、填 API Key。
  • 配置结构（思路）：
    {
      "models": {
        "defaults": { "provider": "anthropic", "model": "claude-sonnet-4-20250514" },
        "providers": {
          "anthropic": { "apiKey": "$ANTHROPIC_API_KEY" },
          "openai": { "apiKey": "$OPENAI_API_KEY" },
          "ollama": { "baseUrl": "http://127.0.0.1:11434/v1", "api": "openai-responses" }
        }
      },
      "agents": {
        "defaults": {
          "model": { "primary": "anthropic/claude-sonnet-4-20250514", "fallbacks": ["openai/gpt-4o"] }
        }
      }
    }
  • Ollama 注意：必须设 "api": "openai-responses"，否则容易 0 tokens / 无响应；Docker 里用 http://host.docker.internal:11434/v1。
  • 多 Provider：支持 Anthropic、OpenAI、Google Gemini、vLLM、AWS Bedrock、Ollama 等；自定义需 baseUrl + apiKey。

权限划分建议

  • 单独创建系统用户（如 openclaw），只给到代码目录读写权限。
  • 高危目录（~/.ssh、生产 kubeconfig、云 CLI 配置等）尽量不让该用户直接访问。
  • 对接外部系统时，优先使用“最小权限的专用账号”，不要共用个人高权限凭证。

控制台命令（CLI）

常用的一坨，详细 openclaw --help / 官方 CLI 文档。

Gateway

Terminal window
openclaw gateway              # 前台跑网关（默认端口多为 18789）
openclaw gateway run          # 同上
openclaw gateway --port 8288 --bind 127.0.0.1   # 指定端口 + 只监听本机


openclaw gateway health       # 健康检查
openclaw gateway status       # 服务状态 + 可选 RPC 探测
openclaw gateway probe        # 探测本机/远程网关（含 --ssh user@host）


openclaw gateway install      # 装成系统服务
openclaw gateway start|stop|restart|uninstall

常用选项：--verbose 打日志，--force 杀占口进程再起，--password/--token 覆盖认证（别在命令行长期写密码）。

Models

Terminal window
openclaw models status        # 当前默认/fallback + 各 provider 认证概览
openclaw models list          # 可用模型列表
openclaw models set <provider/model>   # 设默认模型
openclaw models scan          # 扫描/刷新模型
openclaw models auth add      # 添加认证
openclaw models auth login --provider <id>

改配置或改默认模型后，一般要 openclaw gateway restart。

会话内快捷（Web UI / 终端会话）

  • /model — 打开模型选择器
  • /model list — 列出可选模型
  • /model <编号> — 按编号切
  • /model openai/gpt-4o — 按 provider/model 切
  • /model status — 当前模型详情

使用

仅记录个人顺手的使用方式，偏“人肉控制的 Agent”，而不是全自动编排。

基本工作流

  1. 在本地启动网关与 UI。
  2. 在当前项目根目录运行代理/工具，让 OpenClaw 对当前仓库有上下文。
  3. 在 Web UI 里：
    • 明确写清“项目结构 + 当前目标 + 约束”；
    • 控制粒度：一次只让它完成 1 个小任务（函数/模块级），方便 review。
  4. 所有涉及写文件 / git 操作的建议必须先过一眼 diff，再决定是否接受。

和 Cursor / 其它工具的配合

  • OpenClaw 更像是“跨项目 / 跨资源的自动化脚本 + Agent 中枢”；
  • Cursor 偏 IDE 内代码编辑器 + 代码理解；
  • 实际使用时可以：
    • 让 OpenClaw 帮忙跑脚本、调度外部服务；
    • 在 Cursor 里做最后的代码修改和 review，避免 OpenClaw 直接改大仓库。

训练

目前官方能力变化比较快，这里只写通用思路，实际接口以最新文档为准。

  • 将“任务拆分 + 约束 + 外部系统交互”抽象为 Skill，尽量做成可复用的组合块。
  • Skill 内只放必要的业务逻辑，把模型 Prompt 单独抽出来，方便迭代。
  • 对每个 Skill 建最小集的单测 / 集成测试，至少覆盖“误删 / 误操作”的边界。
  • 高危操作（删库、销毁资源、批量变更）必须内置“dry-run 模式 + 人工确认开关”。

SKILL

推荐与来源

  • ClawHub：官方/社区技能仓库（https://clawhub.ai 等），数量多，安装前看 Star、更新日期、源码再装。
  • 安装方式：
    Terminal window
    clawhub search "关键词"
    clawhub install <skill-name>
    或通过 Web 一键安装；Skill 按需加载，装多了不会拖慢简单请求。

推荐方向（自用备忘）

  • 自动分配模型 / 按任务选模型：
    用「按复杂度路由到不同模型」的 Skill，可省成本（简单任务走便宜模型，复杂再上 Claude/GPT-4）。
    • 例如：model-hierarchy-skill（zscole/model-hierarchy-skill）、openclaw-model-router、intelligent-router、smart-router 等，思路都是把任务分档（简单/中等/复杂/推理/关键），再配 primary + fallbacks。
    • 配置好 fallback 链后，主模型不可用时会自动切备用；装前看 SKILL.md 和配置项，确认支持的 provider。
  • Web 搜索：Brave Search 等集成，查实时信息、文档、报错用，建议装一个。
  • 其它：按需选（图生、Gmail、日历、GitHub PR 等），一律当不可信插件，最小权限。

自建与审查原则

  • 给自己写的 Skill 起清晰的命名和说明，方便以后回头看：
    • xxx-audit-*：只读、审计类，默认安全。
    • xxx-ops-*：运维变更类，要额外小心。
  • 每次引入第三方 Skill 前，至少做：
    • 快速过一遍代码里是否有 rm -rf / DROP TABLE / 大范围写文件等；
    • 检查是否把云凭证、数据库密码等写死在代码里。
  • 原则：把所有 Skill 当作“不受信任插件”，只给到完成当前任务所需的最小权限。