OpenClaw 完整配置教程：从安装到深度定制

一站式 AI 助手网关，连接你的所有聊天平台，驱动你的智能工作流

什么是 OpenClaw

OpenClaw 是一个开源的 AI 助手网关（Gateway），它将大语言模型与你日常使用的聊天平台连接起来。通过一个统一的 Gateway 进程，你可以让 AI 助手同时在线 Telegram、WhatsApp、Discord、飞书、Slack 等多个平台，并赋予它执行命令、浏览网页、生成图片等能力。

核心架构： 一个长期运行的 Gateway 进程管理所有消息通道，控制平面客户端（macOS 应用、CLI、Web UI）通过 WebSocket 连接到 Gateway。

一、安装

系统要求

推荐安装方式

macOS / Linux / WSL2：

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

Windows (PowerShell)：

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

安装脚本会自动检测操作系统、安装 Node（如需要）、安装 OpenClaw 并启动引导流程。

其他安装方式

# npm 全局安装
npm install -g openclaw@latest
openclaw onboard --install-daemon

# pnpm
pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

# 从源码
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm link --global
openclaw onboard --install-daemon

验证安装

openclaw --version      # 确认 CLI 可用
openclaw doctor         # 检查配置问题
openclaw gateway status # 验证 Gateway 运行状态

二、目录结构

OpenClaw 的所有状态和配置集中在 ~/.openclaw/ 目录下：

~/.openclaw/
├── openclaw.json          # 主配置文件（JSON5 格式）
├── .env                   # 全局环境变量
├── workspace/             # Agent 工作区
│   ├── AGENTS.md          # Agent 行为指令
│   ├── SOUL.md            # Agent 人格定义
│   ├── USER.md            # 用户信息
│   ├── IDENTITY.md        # Agent 身份
│   ├── TOOLS.md           # 工具配置笔记
│   ├── MEMORY.md          # 长期记忆
│   ├── DREAMS.md          # 梦境日志（实验性）
│   ├── memory/            # 每日笔记
│   │   └── 2026-04-12.md
│   └── skills/            # 工作区级技能
├── credentials/           # 通道凭证
│   ├── whatsapp/          # WhatsApp 凭证
│   └── *-allowFrom.json   # 配对白名单
├── agents/                # Agent 状态
│   └── main/
│       ├── agent/
│       │   └── auth-profiles.json  # 模型认证
│       └── sessions/      # 会话记录
├── cron/                  # 定时任务
│   └── jobs.json
├── skills/                # 管理级技能覆盖
└── secrets.json           # 文件型密钥（可选）

三、配置文件详解

OpenClaw 使用 ~/.openclaw/openclaw.json 作为主配置文件，支持 JSON5 格式（允许注释和尾逗号）。如果文件不存在，使用安全默认值。

最小配置

// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

编辑配置的四种方式

# 1. 交互式向导
openclaw onboard       # 完整引导流程
openclaw configure     # 配置向导

# 2. CLI 单行命令
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey

# 3. Web 控制台
# 打开 http://127.0.0.1:18789 使用 Config 标签页

# 4. 直接编辑
# 编辑 ~/.openclaw/openclaw.json，Gateway 会自动热重载

配置热重载

Gateway 会监视配置文件并自动应用更改，无需手动重启。支持四种重载模式：

{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

拆分配置文件（$include）

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}

四、环境变量

全局环境变量

配置中的环境变量

{
  // 内联环境变量
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

环境变量替换

在任何配置字符串值中引用环境变量：

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

密钥引用（SecretRef）

支持三种密钥来源：env（环境变量）、file（文件）、exec（命令执行）：

{
  models: {
    providers: {
      openai: {
        apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" },
      },
    },
  },
}

五、AI 模型提供商配置

OpenClaw 内置 35+ 模型提供商，只需设置 API 密钥即可使用。

设置主模型

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
    },
  },
}

常用提供商一览

API 密钥轮换

支持多个 API 密钥自动轮换（速率限制时切换）：

# 环境变量设置
OPENAI_API_KEYS="sk-xxx,sk-yyy,sk-zzz"
OPENAI_API_KEY_1="sk-xxx"
OPENAI_API_KEY_2="sk-yyy"

自定义/自托管提供商

{
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "LMSTUDIO_KEY",
        api: "openai-completions",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

CLI 操作

openclaw onboard --auth-choice openai-api-key  # 交互式设置
openclaw models set anthropic/claude-opus-4-6  # 设置主模型
openclaw models list                           # 列出可用模型
openclaw models status --probe                 # 检查认证状态

六、消息通道（Channels）

OpenClaw 支持同时连接多个聊天平台，所有通道通过统一 Gateway 管理。

内置通道

插件通道（bundled plugins）

飞书、Matrix、LINE、Microsoft Teams、QQ Bot、Zalo、Twitch、Nextcloud Talk、Nostr 等。

通道配置示例

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"],
    },
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
    discord: {
      enabled: true,
      botToken: "${DISCORD_BOT_TOKEN}",
    },
  },
}

DM 访问策略

群组提及门控

{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [{
      id: "main",
      groupChat: { mentionPatterns: ["@openclaw", "openclaw"] },
    }],
  },
}

配对管理

openclaw channels login                          # WhatsApp Web 登录
openclaw pairing list whatsapp                   # 查看待审批配对
openclaw pairing approve whatsapp ABC123         # 审批配对码

七、工具集

工具配置概览

{
  tools: {
    profile: "coding",   // messaging | coding | full
    deny: ["group:runtime"],
    fs: { workspaceOnly: true },
    exec: {
      security: "allowlist",  // deny | allowlist | full
      ask: "on-miss",         // off | on-miss | always
    },
    browser: { enabled: true },
  },
}

工具配置文件（tools.profile）

内置工具一览

Web 搜索集成

支持 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax、Perplexity、SearXNG、Tavily 等搜索引擎。

沙箱执行

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

八、技能系统（Skills）

OpenClaw 使用 AgentSkills 兼容格式的技能文件夹来教 Agent 如何使用工具。

技能加载优先级

<workspace>/skills（最高）→ <workspace>/.agents/skills → ~/.agents/skills
→ ~/.openclaw/skills → bundled skills → skills.load.extraDirs（最低）

技能格式

每个技能是一个包含 SKILL.md 的文件夹：

---
name: image-lab
description: 通过提供商支持的图像工作流生成或编辑图像
metadata:
  {
    "openclaw":
      {
        "requires": { "env": ["GEMINI_API_KEY"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

# 图像实验室技能指令
使用 `{baseDir}` 引用技能文件夹路径...

技能配置

{
  skills: {
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: "YOUR_KEY_HERE",
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
    },
  },
}

Agent 技能白名单

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" },                          // 继承默认
      { id: "docs", skills: ["docs-search"] },    // 替换默认
      { id: "locked-down", skills: [] },           // 无技能
    ],
  },
}

ClawHub 技能市场

openclaw skills search "image"           # 搜索技能
openclaw skills install <skill-slug>     # 安装技能
openclaw skills update --all             # 更新所有技能
openclaw skills list                     # 列出已安装技能

九、记忆系统

OpenClaw 通过纯 Markdown 文件实现跨会话记忆。

记忆文件

记忆工具

• memory_search：语义搜索（混合向量相似度 + 关键词匹配）
• memory_get：读取特定记忆文件或行范围

记忆后端

记忆搜索配置

当配置了嵌入提供商时，memory_search 自动启用混合搜索。OpenClaw 自动检测可用的 API 密钥（OpenAI、Gemini、Voyage、Mistral）。

openclaw memory status          # 检查索引状态
openclaw memory search "查询"    # 搜索记忆
openclaw memory index --force   # 重建索引

梦境系统（实验性）

可选的后台记忆整合：收集短期信号、评分候选、将合格条目提升到长期记忆。默认关闭，需手动启用。

十、定时任务（Cron）

配置

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: { maxBytes: "2mb", keepLines: 2000 },
  },
}

CLI 操作

# 一次性提醒
openclaw cron add \
  --name "提醒" \
  --at "20m" \
  --session main \
  --system-event "检查文档草稿" \
  --wake now

# 定时循环任务
openclaw cron add \
  --name "早报" \
  --cron "0 7 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "总结昨夜更新" \
  --announce \
  --channel telegram \
  --to "123456789"

# 管理任务
openclaw cron list
openclaw cron runs --id <job-id>
openclaw cron run <jobId>
openclaw cron edit <jobId> --message "更新的提示"
openclaw cron remove <jobId>

调度类型

执行模式

Webhook 集成

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    mappings: [
      { match: { path: "gmail" }, action: "agent", agentId: "main", deliver: true },
    ],
  },
}

十一、语音配置（TTS）

OpenClaw 支持将文本回复转为语音消息。

支持的 TTS 服务

配置示例

{
  messages: {
    tts: {
      auto: "always",      // off | always | inbound | tagged
      provider: "openai",
      providers: {
        openai: {
          voice: "alloy",
          model: "gpt-4o-mini-tts",
        },
      },
    },
  },
}

Slash 命令

/tts on           # 开启
/tts off          # 关闭
/tts status       # 查看状态
/tts provider openai  # 切换提供商
/tts audio 你好    # 一次性语音

十二、安全与审批

安全模型

OpenClaw 假设个人助手部署模型：每个 Gateway 一个可信操作者。

快速安全审计

openclaw security audit          # 基础审计
openclaw security audit --deep   # 深度审计（含在线探测）
openclaw security audit --fix    # 自动修复常见问题

Gateway 认证

{
  gateway: {
    bind: "loopback",  // loopback | lan | tailnet | custom
    auth: {
      mode: "token",   // token | password | trusted-proxy
      token: "your-long-random-token",
    },
  },
}

Exec 审批系统

Exec 审批是沙箱 Agent 在真实主机上执行命令的安全护栏：

加固基线

{
  gateway: {
    mode: "local",
    bind: "loopback",
    auth: { mode: "token", token: "replace-with-long-random-token" },
  },
  session: { dmScope: "per-channel-peer" },
  tools: {
    profile: "messaging",
    deny: ["group:automation", "group:runtime", "group:fs"],
    fs: { workspaceOnly: true },
    exec: { security: "deny", ask: "always" },
  },
  channels: {
    whatsapp: { dmPolicy: "pairing", groups: { "*": { requireMention: true } } },
  },
}

十三、多 Agent 路由

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

每个 Agent 可以有独立的沙箱策略和工具权限：

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: ["read"],
          deny: ["write", "edit", "exec", "browser"],
        },
      },
    ],
  },
}

十四、心跳（Heartbeat）

定期让 Agent 主动检查：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",      // 触发间隔
        target: "last",     // last | none | <channel-id>
      },
    },
  },
}

十五、常用命令速查

安装与初始化

openclaw onboard --install-daemon     # 安装并引导
openclaw setup                        # 初始化配置
openclaw doctor                       # 健康检查
openclaw doctor --fix                 # 自动修复

Gateway 管理

openclaw gateway status               # 查看状态
openclaw gateway start                # 启动
openclaw gateway stop                 # 停止
openclaw gateway restart              # 重启
openclaw dashboard                    # 打开控制台
openclaw logs --follow                # 查看实时日志

模型管理

openclaw models list                  # 列出模型
openclaw models set <provider/model>  # 设置主模型
openclaw models status --probe        # 检查认证状态

通道管理

openclaw channels list                # 列出通道
openclaw channels status --probe      # 检查通道健康
openclaw channels login               # 登录通道
openclaw pairing list <channel>       # 查看配对请求
openclaw pairing approve <channel> <code>  # 审批配对

记忆管理

openclaw memory status                # 记忆索引状态
openclaw memory search "查询"          # 语义搜索
openclaw memory index --force         # 重建索引

定时任务

openclaw cron list                    # 列出任务
openclaw cron add --name "任务" ...   # 添加任务
openclaw cron run <jobId>             # 手动触发
openclaw cron remove <jobId>          # 删除任务

安全

openclaw security audit               # 安全审计
openclaw security audit --deep        # 深度审计
openclaw security audit --fix         # 自动修复

技能

openclaw skills list                  # 列出技能
openclaw skills search "关键词"        # 搜索技能
openclaw skills install <slug>        # 安装技能
openclaw skills update --all          # 更新所有技能

配置操作

openclaw config get <path>            # 读取配置
openclaw config set <path> <value>    # 设置配置
openclaw config unset <path>          # 删除配置
openclaw config validate              # 验证配置
openclaw config schema                # 输出 JSON Schema

十六、部署选项

远程访问推荐使用 Tailscale：

openclaw onboard --tailscale serve   # 通过 Tailscale Serve 暴露

总结

OpenClaw 是一个功能丰富的 AI 助手网关，其核心设计理念是：

1. 统一网关：一个进程管理所有聊天通道
2. 安全优先：配对机制、白名单、沙箱、审批系统
3. 灵活配置：JSON5 配置 + 热重载 + CLI/Web 多种编辑方式
4. 丰富生态：35+ 模型提供商、20+ 聊天通道、技能市场、插件系统
5. 记忆系统：基于文件的持久记忆，支持语义搜索
6. 自动化：定时任务、Webhook、心跳机制

更多信息请访问 openclaw.ai 或查阅官方文档。