OpenClaw配置详解文档

完整配置指南，涵盖所有配置项、交互方式和 Skills 管理

目录

  1. 配置文件结构
  2. 核心配置详解
  3. 交互方式
  4. Skills 配置
  5. 频道配置
  6. 高级配置
  7. 配置命令参考

配置文件结构

OpenClaw 使用 JSON 配置文件，默认位置：

~/.openclaw/openclaw.json

完整配置结构概览

{
  "meta": {},           // 元数据
  "wizard": {},         // 向导配置
  "auth": {},           // 认证配置
  "models": {},         // AI 模型配置
  "agents": {},         // Agent 行为配置
  "tools": {},          // 工具配置
  "messages": {},       // 消息处理配置
  "commands": {},       // 命令行为配置
  "session": {},        // 会话配置
  "channels": {},       // 聊天频道配置
  "gateway": {},        // Gateway 服务配置
  "plugins": {}         // 插件配置
}

核心配置详解

1. Meta 元数据

用途： 记录配置文件的版本和修改历史，由系统自动维护，通常不需要手动修改。

{
  "meta": {
    "lastTouchedVersion": "2026.3.13",
    "lastTouchedAt": "2026-03-18T10:27:46.383Z"
  }
}
字段 说明 是否手动修改
lastTouchedVersion 最后修改配置的 OpenClaw 版本 否（自动）
lastTouchedAt 最后修改时间（ISO 8601 格式） 否（自动）

2. Wizard 向导配置

用途： 记录配置向导的运行历史，用于判断是否需要重新运行向导。通常不需要手动修改。

{
  "wizard": {
    "lastRunAt": "2026-03-18T10:27:46.333Z",
    "lastRunVersion": "2026.3.13",
    "lastRunCommand": "configure",
    "lastRunMode": "local"
  }
}
字段 说明 是否手动修改
lastRunAt 上次运行向导时间 否（自动）
lastRunVersion 上次运行向导时的版本 否（自动）
lastRunCommand 上次运行的命令 否（自动）
lastRunMode 运行模式：local / remote 否（自动）

相关命令：

# 重新运行配置向导
openclaw configure
openclaw onboard

3. Auth 认证配置

用途： 配置 AI 模型提供商的认证信息。API Key 实际存储在独立的 secrets 文件中（~/.openclaw/secrets.json），此处仅记录配置档案。

{
  "auth": {
    "profiles": {
      "moonshot:default": {
        "provider": "moonshot",
        "mode": "api_key"
      }
    }
  }
}
字段 说明 示例值
profiles 认证档案集合 对象
{profile_name} 档案名称，格式：provider:标识 moonshot:default
provider 提供商标识 moonshot, openai, anthropic
mode 认证模式 api_key, oauth, token
支持的 Provider
Provider 说明 API 端点 获取 API Key
moonshot Moonshot (Kimi) https://api.moonshot.cn/v1 https://platform.moonshot.cn/
openai OpenAI https://api.openai.com/v1 https://platform.openai.com/
anthropic Anthropic (Claude) https://api.anthropic.com https://console.anthropic.com/
google Google (Gemini) https://generativelanguage.googleapis.com https://aistudio.google.com/
azure Azure OpenAI 自定义 Azure Portal
认证模式
模式 说明 适用场景
api_key 使用 API Key 认证 大多数提供商
oauth OAuth 2.0 认证 Google, Microsoft
token Bearer Token 认证 自定义部署

修改方法：

# 重新运行配置向导修改认证
openclaw configure

# 或直接设置环境变量（优先级更高）
export MOONSHOT_API_KEY="your-api-key"
export OPENAI_API_KEY="your-api-key"
export ANTHROPIC_API_KEY="your-api-key"

4. Models 模型配置 ⭐

用途： 配置可用的 AI 模型，包括模型参数、成本和 API 端点。这是修改模型时需要编辑的核心配置。

{
  "models": {
    "mode": "merge",
    "providers": {
      "moonshot": {
        "baseUrl": "https://api.moonshot.cn/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "kimi-k2.5",
            "name": "Kimi K2.5",
            "api": "openai-completions",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 256000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}
配置项说明
配置项 说明 可选值 修改建议
mode 模型合并模式 merge / replace 保持 merge 以合并多个提供商
providers 提供商配置集合 对象 添加新的提供商
{provider} 提供商名称 moonshot, openai 等 与 auth.profiles 对应
baseUrl API 基础地址 URL 通常不需要修改
api API 协议类型 openai-completions, anthropic-messages, google-generative 根据提供商选择
models 模型列表 数组 添加/修改模型
模型配置字段详解
字段 类型 说明 示例
id string 模型标识符（唯一） kimi-k2.5, gpt-4o
name string 显示名称 Kimi K2.5
api string API 协议类型 openai-completions
reasoning boolean 是否支持推理模式 false, true
input array 支持的输入类型 ["text"], ["text", "image"]
cost object 成本配置（美元/1K tokens） 见下方
contextWindow number 上下文窗口大小（tokens） 256000
maxTokens number 最大输出 tokens 8192
成本配置
{
  "cost": {
    "input": 0.001,        // 输入成本（美元/1K tokens）
    "output": 0.002,       // 输出成本
    "cacheRead": 0.0005,   // 缓存读取成本
    "cacheWrite": 0.001    // 缓存写入成本
  }
}
修改模型的方法

方法1：使用配置命令（推荐）

# 修改默认模型
openclaw config set agents.defaults.model.primary "moonshot/kimi-k2.5"

# 修改模型别名
openclaw config set agents.defaults.models.moonshot/kimi-k2.5.alias "Kimi"

# 添加新模型到配置
openclaw config set models.providers.openai.models '[{"id":"gpt-4o","name":"GPT-4o","api":"openai-completions"}]'

方法2：直接编辑配置文件

# 打开配置文件
openclaw config file --edit

# 修改 models 部分，例如添加 OpenAI：
{
  "models": {
    "mode": "merge",
    "providers": {
      "moonshot": { ... },
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "api": "openai-completions",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": {
              "input": 0.005,
              "output": 0.015,
              "cacheRead": 0.00125,
              "cacheWrite": 0.0025
            },
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  }
}

方法3：使用配置向导

openclaw configure
# 选择 "Configure AI Models"
常用模型配置示例

添加 GPT-4o：

{
  "id": "gpt-4o",
  "name": "GPT-4o",
  "api": "openai-completions",
  "reasoning": false,
  "input": ["text", "image"],
  "cost": {
    "input": 0.005,
    "output": 0.015,
    "cacheRead": 0.00125,
    "cacheWrite": 0.0025
  },
  "contextWindow": 128000,
  "maxTokens": 4096
}

添加 Claude 3.5 Sonnet：

{
  "id": "claude-3-5-sonnet-20241022",
  "name": "Claude 3.5 Sonnet",
  "api": "anthropic-messages",
  "reasoning": false,
  "input": ["text", "image"],
  "cost": {
    "input": 0.003,
    "output": 0.015,
    "cacheRead": 0.0003,
    "cacheWrite": 0.00375
  },
  "contextWindow": 200000,
  "maxTokens": 8192
}


---

### 5. Agents Agent 配置 ⭐

**用途：** 配置 Agent 的默认行为，包括默认模型、工作目录、并发限制等。**修改默认模型时需要编辑此配置。**

```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "moonshot/kimi-k2.5"
      },
      "models": {
        "moonshot/kimi-k2.5": {
          "alias": "Kimi"
        }
      },
      "workspace": "/home/zeven/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  }
}
配置项说明
配置项 说明 默认值 修改建议
model.primary 默认使用的模型 首次配置时设置 根据需求切换
models.{id} 模型别名配置 - 为模型设置易记名称
models.{id}.alias 模型显示别名 - 简短易记的名字
workspace Agent 工作目录 ~/.openclaw/workspace 可改为项目目录
compaction.mode 会话历史压缩模式 safeguard 长会话可改 aggressive
maxConcurrent 最大并发 Agent 数 4 根据 CPU/内存调整
subagents.maxConcurrent 子 Agent 最大并发 8 复杂任务可调高
压缩模式说明
模式 说明 适用场景
off 关闭压缩，保留完整历史 短会话、调试
safeguard 安全压缩，保留关键信息 日常使用（推荐）
aggressive 激进压缩，最大化节省 tokens 长会话、上下文紧张
修改方法

修改默认模型：

# 切换到其他模型
openclaw config set agents.defaults.model.primary "openai/gpt-4o"
openclaw config set agents.defaults.model.primary "anthropic/claude-3-5-sonnet-20241022"
openclaw config set agents.defaults.model.primary "moonshot/kimi-k2.5"

# 添加模型别名
openclaw config set agents.defaults.models.openai/gpt-4o.alias "GPT-4o"

修改工作目录：

# 改为项目目录
openclaw config set agents.defaults.workspace "/home/user/projects/my-project"

# 或改为文档目录
openclaw config set agents.defaults.workspace "/home/user/Documents/openclaw"

调整并发限制：

# 降低并发（低配置机器）
openclaw config set agents.defaults.maxConcurrent 2
openclaw config set agents.defaults.subagents.maxConcurrent 4

# 提高并发（高配置机器）
openclaw config set agents.defaults.maxConcurrent 8
openclaw config set agents.defaults.subagents.maxConcurrent 16

修改压缩模式：

# 长会话优化
openclaw config set agents.defaults.compaction.mode "aggressive"

# 调试模式（保留完整历史）
openclaw config set agents.defaults.compaction.mode "off"

6. Tools 工具配置

用途： 配置 Agent 可用的工具集，定义 Agent 能执行的操作类型。

{
  "tools": {
    "profile": "coding"
  }
}
配置项说明
配置项 说明 可选值 文件位置
profile 工具集配置文件 coding, default, 自定义 ~/.openclaw/TOOLS.md
内置工具集
Profile 说明 适用场景
coding 编程工具集 代码开发、文件操作
default 默认工具集 一般用途
修改方法

切换工具集：

# 使用编程工具集
openclaw config set tools.profile "coding"

# 使用默认工具集
openclaw config set tools.profile "default"

自定义工具集：

# 编辑工具配置文件
nano ~/.openclaw/TOOLS.md

# 添加自定义工具说明，例如：
### Cameras
- living-room → Main area, 180° wide angle
- front-door → Entrance, motion-triggered

### SSH
- home-server → 192.168.1.100, user: admin

### TTS
- Preferred voice: "Nova"
- Default speaker: Kitchen HomePod

7. Messages 消息配置

用途： 配置 Agent 在聊天频道中的自动响应行为。

{
  "messages": {
    "ackReactionScope": "group-mentions"
  }
}
配置项说明
配置项 说明 可选值 建议
ackReactionScope 自动响应范围 all, group-mentions, none 群组用 group-mentions
响应范围说明
值 说明 适用场景
all 响应所有消息 私聊机器人
group-mentions 仅响应 @提及 群组聊天（推荐）
none 不自动响应 纯手动模式
修改方法
# 群组模式（仅响应 @提及）
openclaw config set messages.ackReactionScope "group-mentions"

# 私聊模式（响应所有消息）
openclaw config set messages.ackReactionScope "all"

# 手动模式（不自动响应）
openclaw config set messages.ackReactionScope "none"

8. Commands 命令配置

用途： 配置命令行行为和处理方式。

{
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  }
}
配置项说明
配置项 说明 可选值 默认值
native 原生命令处理 auto, enabled, disabled auto
nativeSkills Skills 原生处理 auto, enabled, disabled auto
restart 允许重启命令 true, false true
ownerDisplay 所有者信息显示 raw, masked raw
配置说明
值 说明
native/nativeSkills=auto 自动检测并启用原生处理
native/nativeSkills=enabled 强制启用原生处理
native/nativeSkills=disabled 禁用原生处理
ownerDisplay=raw 显示完整所有者信息
ownerDisplay=masked 隐藏敏感信息
修改方法
# 禁用原生命令处理
openclaw config set commands.native "disabled"

# 隐藏所有者信息
openclaw config set commands.ownerDisplay "masked"

# 禁用重启命令
openclaw config set commands.restart false

9. Session 会话配置

用途： 配置会话的隔离范围，影响私聊消息的上下文关联。

{
  "session": {
    "dmScope": "per-channel-peer"
  }
}
配置项说明
配置项 说明 可选值 建议
dmScope DM 会话范围 per-channel-peer, global 多频道用 per-channel-peer
会话范围说明
值 说明 适用场景
per-channel-peer 每个频道-用户组合独立会话 同一用户在不同频道有不同上下文
global 全局统一会话 同一用户在所有频道共享上下文

示例：

  • per-channel-peer: 用户在 Telegram 私聊和 Discord 服务器的对话互不影响
  • global: 用户在 Telegram 提到的内容，在 WhatsApp 也能记住
修改方法
# 频道隔离模式（推荐）
openclaw config set session.dmScope "per-channel-peer"

# 全局统一模式
openclaw config set session.dmScope "global"

交互方式

OpenClaw 支持多种交互方式：

1. Web Dashboard（控制面板）

# 打开 Dashboard
openclaw dashboard

# 指定端口打开
openclaw dashboard --port 8080

功能：

  • 查看会话列表和状态
  • 管理配置
  • 查看日志
  • 管理定时任务
  • 管理设备配对

2. TUI（终端界面）

# 启动 TUI
openclaw tui

快捷键：

  • Tab / Shift+Tab - 切换面板
  • Enter - 确认/进入
  • Esc / q - 返回/退出
  • ? - 帮助

3. CLI（命令行）

# 直接发送消息
openclaw agent --message "你好"

# 指定目标发送
openclaw agent --to +1234567890 --message "Hello"

# 查看状态
openclaw status

4. 聊天频道

支持通过以下渠道交互：

Telegram

介绍： Telegram 是一款注重速度和安全的即时通讯应用，支持机器人 API，是 OpenClaw 最常用的集成渠道。

特点：

  • 支持 Bot API，易于集成
  • 支持群组和频道
  • 支持 Markdown 格式
  • 支持文件传输
  • 全球可用，国内需要代理

配置方式：

# 交互式配置
openclaw channels login --channel telegram

# 手动配置
openclaw config set channels.telegram.botToken "your-bot-token"

获取 Bot Token：

  1. 在 Telegram 中搜索 @BotFather
  2. 发送 /newbot 创建新机器人
  3. 按提示设置名称和用户名
  4. 获取 HTTP API Token

使用示例：

# 发送消息
openclaw message send --channel telegram --target @username --message "Hello"

# 发送到群组
openclaw message send --channel telegram --target -1001234567890 --message "Hello Group"
WhatsApp

介绍： WhatsApp 是全球最流行的即时通讯应用之一，支持个人和群组聊天。

特点：

  • 端到端加密
  • 支持文字、语音、图片、视频
  • 全球用户基数大
  • 需要手机保持在线
  • 国内使用受限

配置方式：

# 交互式配置（需要扫描二维码）
openclaw channels login --channel whatsapp

注意事项：

  • 需要手机保持联网
  • 会话会过期，需要定期重新登录
  • 有频率限制，避免发送过多消息

使用示例：

# 发送消息
openclaw message send --channel whatsapp --target "+1234567890" --message "Hello"
Discord

介绍： Discord 是一款面向游戏社区的即时通讯和数字分发平台，支持文本、语音和视频通话。

特点：

  • 支持 Bot 机器人
  • 支持服务器（群组）和频道
  • 支持富文本和嵌入消息
  • 支持语音频道
  • 适合社区和团队协作

配置方式：

# 交互式配置
openclaw channels login --channel discord

# 手动配置
openclaw config set channels.discord.token "your-bot-token"

获取 Bot Token：

  1. 访问 https://discord.com/developers/applications
  2. 创建新应用
  3. 进入 “Bot” 页面，点击 “Add Bot”
  4. 复制 Token
  5. 在 OAuth2 URL Generator 中授权机器人加入服务器

使用示例：

# 发送消息到频道
openclaw message send --channel discord --target "#general" --message "Hello"

# 发送私信
openclaw message send --channel discord --target @username --message "Hello"
Slack

介绍： Slack 是一款面向企业的团队协作工具，支持即时通讯、文件共享和应用集成。

特点：

  • 企业级协作平台
  • 支持工作区（Workspace）
  • 支持频道和私信
  • 丰富的应用生态系统
  • 支持工作流自动化

配置方式：

# 交互式配置
openclaw channels login --channel slack

# 手动配置
openclaw config set channels.slack.token "xoxb-your-token"

获取 Token：

  1. 访问 https://api.slack.com/apps
  2. 创建新应用
  3. 进入 “OAuth & Permissions”
  4. 添加所需的 Scope（如 chat:write, channels:read）
  5. 安装应用到工作区
  6. 获取 Bot User OAuth Token

使用示例：

# 发送到频道
openclaw message send --channel slack --target "#general" --message "Hello"

# 发送私信
openclaw message send --channel slack --target @username --message "Hello"
Signal

介绍： Signal 是一款注重隐私的即时通讯应用，以端到端加密和开源著称。

特点：

  • 端到端加密（Signal Protocol）
  • 开源软件
  • 无广告，非营利
  • 支持文字、语音、视频通话
  • 隐私保护最强

配置方式：

# 交互式配置
openclaw channels login --channel signal

注意事项：

  • 需要 Signal 桌面版或 signal-cli
  • 配置相对复杂
  • 国内使用受限

使用示例：

# 发送消息
openclaw message send --channel signal --target "+1234567890" --message "Hello"
频道对比表
特性 Telegram WhatsApp Discord Slack Signal
易用性 ⭐⭐⭐⭐⭐ ⭐⭐⭐ ⭐⭐⭐⭐ ⭐⭐⭐⭐ ⭐⭐
隐私性 ⭐⭐⭐ ⭐⭐⭐⭐ ⭐⭐ ⭐⭐ ⭐⭐⭐⭐⭐
国内可用 需代理 受限 需代理 需代理 受限
Bot 支持 ✅ ✅ ✅ ✅ ⚠️
群组规模 20万 1024 无限 无限 1000
文件传输 2GB 100MB 25MB 1GB 100MB
适用场景 个人/社区 个人通讯 游戏/社区 企业协作 隐私通讯
通用频道命令
# 列出所有已配置频道
openclaw channels list

# 测试频道连接
openclaw channels test --channel telegram

# 登出频道
openclaw channels logout --channel telegram

# 查看频道配置
openclaw config get channels

# 发送消息（通用格式）
openclaw message send --channel <channel> --target <target> --message "内容"

Skills 配置

查看可用 Skills

# 列出所有 skills
openclaw skills list

# 查看 skill 详情
openclaw skills show <skill-name>

Skills 状态说明

状态 含义
✓ ready 已就绪，可以使用
✗ missing 缺少依赖，需要安装
⚠ pending 等待配置

安装 Skill 依赖

每个 skill 有自己的依赖要求，通常需要安装对应的 CLI 工具：

# 示例：安装 weather skill 依赖（无需额外安装）
# weather 使用 wttr.in，无需本地依赖

# 示例：安装 github skill 依赖
sudo apt install gh
gh auth login

# 示例：安装 notion skill 依赖
npm install -g notion-cli

创建自定义 Skill

# 使用 skill-creator skill
openclaw skill-creator create my-skill

Skill 配置位置

~/.npm-global/lib/node_modules/openclaw/skills/
├── healthcheck/
│   └── SKILL.md
├── node-connect/
│   └── SKILL.md
├── skill-creator/
│   └── SKILL.md
└── weather/
    └── SKILL.md

频道配置

Channels 配置结构

{
  "channels": {
    "telegram": {
      "botToken": "your-bot-token",
      "webhook": {
        "enabled": false,
        "url": "https://your-domain.com/webhook"
      }
    },
    "whatsapp": {
      "session": "default",
      "webhook": {}
    },
    "discord": {
      "token": "your-bot-token"
    }
  }
}

配置 Telegram

# 交互式配置
openclaw channels login --channel telegram

# 手动配置
openclaw config set channels.telegram.botToken "your-token"

配置 WhatsApp

openclaw channels login --channel whatsapp

配置 Discord

openclaw channels login --channel discord

高级配置

Gateway 配置详解 ⭐

用途： 配置 Gateway 服务的网络参数、安全设置和访问控制。这是配置远程访问和 Dashboard 时需要编辑的核心配置。

{
  "gateway": {
    "port": 8080,
    "mode": "local",
    "bind": "lan",
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:8080",
        "http://127.0.0.1:8080",
        "http://192.168.1.16:8080"
      ],
      "allowInsecureAuth": true
    },
    "auth": {
      "mode": "token",
      "token": "your-secret-token"
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    },
    "nodes": {
      "denyCommands": [
        "camera.snap",
        "camera.clip",
        "screen.record"
      ]
    }
  }
}
配置项说明
配置项 说明 可选值 默认值 修改建议
port Gateway 服务端口 1024-65535 18789 常用 8080, 3000
mode 运行模式 local, remote local 本地用 local
bind 绑定地址 localhost, lan, 0.0.0.0 localhost 远程访问用 lan
controlUi.allowedOrigins Dashboard 允许的来源 URL 数组 - 添加你的访问地址
controlUi.allowInsecureAuth 允许非安全认证 true, false false 本地开发可开
auth.mode 认证模式 token, oauth token 保持 token
auth.token 访问令牌 字符串 自动生成 可自定义
tailscale.mode Tailscale 模式 off, userspace, kernel off 需要时开启
nodes.denyCommands 节点禁止的命令 字符串数组 - 安全限制
关键配置详解

1. Port（端口）

  • 修改 Gateway 监听的端口
  • 1024 以下端口需要 root 权限
  • 常用端口：8080, 3000, 18789

2. Bind（绑定地址）

值 说明 适用场景
localhost 仅本机访问 单机使用
lan 监听所有局域网接口 局域网访问（推荐）
0.0.0.0 监听所有接口 公网访问

3. Allowed Origins（允许来源）

  • 配置 Dashboard 允许的访问来源
  • 必须包含协议、IP/域名、端口
  • 例如：http://192.168.1.16:8080

4. Auth Token（认证令牌）

  • 访问 Dashboard 和 API 的凭证
  • 建议设置强随机字符串
  • 可通过环境变量 OPENCLAW_GATEWAY_TOKEN 覆盖
修改方法

修改端口：

# 改为 8080
openclaw config set gateway.port 8080

# 重启生效
openclaw gateway restart

启用远程访问：

# 绑定到所有网络接口
openclaw config set gateway.bind "lan"

# 添加允许的来源（替换为你的 IP）
openclaw config set gateway.controlUi.allowedOrigins '["http://localhost:8080", "http://127.0.0.1:8080", "http://192.168.1.16:8080"]'

# 重启生效
openclaw gateway restart

修改访问令牌：

# 生成新 token
openclaw config set gateway.auth.token "$(openssl rand -hex 32)"

# 或使用自定义 token
openclaw config set gateway.auth.token "my-secure-token-123"

# 重启生效
openclaw gateway restart

配置防火墙：

# UFW 防火墙
sudo ufw allow 8080/tcp

# 或限制特定 IP
sudo ufw allow from 192.168.1.0/24 to any port 8080

"nodes": {
  "denyCommands": [
    "camera.snap",
    "camera.clip",
    "screen.record"
  ]
}

}
}


#### Gateway 配置字段

| 字段 | 可选值 | 说明 |
|------|--------|------|
| `port` | number | 服务端口 |
| `mode` | `local` / `remote` | 运行模式 |
| `bind` | `localhost` / `lan` / `0.0.0.0` | 绑定地址 |
| `controlUi.allowedOrigins` | array | 允许的 Dashboard 来源 |
| `controlUi.allowInsecureAuth` | boolean | 允许非安全认证（仅本地） |
| `auth.mode` | `token` / `oauth` | 认证模式 |
| `auth.token` | string | 访问令牌 |
| `tailscale.mode` | `off` / `userspace` / `kernel` | Tailscale 模式 |

### Plugins 插件配置

**用途：** 配置 OpenClaw 插件的加载路径和启用状态。

```json
{
  "plugins": {
    "load": {
      "paths": [
        "/path/to/custom/plugins"
      ]
    },
    "entries": {
      "kimi-claw": {
        "enabled": true,
        "config": {
          "bridge": {
            "token": "your-token",
            "promptTimeoutMs": 1800000
          }
        }
      }
    },
    "installs": {},
    "allow": ["kimi-claw"]
  }
}
配置项说明
配置项 说明 示例
load.paths 自定义插件加载路径 ["/opt/openclaw/plugins"]
entries.{plugin} 插件配置 见下方
entries.{plugin}.enabled 是否启用 true, false
entries.{plugin}.config 插件特定配置 对象
allow 允许的插件列表 ["kimi-claw"]
常用插件配置

kimi-claw（Kimi 桥接插件）：

{
  "kimi-claw": {
    "enabled": true,
    "config": {
      "bridge": {
        "token": "your-bridge-token",
        "promptTimeoutMs": 1800000
      }
    }
  }
}
修改方法
# 启用插件
openclaw config set plugins.entries.kimi-claw.enabled true

# 配置插件
openclaw config set plugins.entries.kimi-claw.config.bridge.token "your-token"

# 添加到允许列表
openclaw config set plugins.allow '["kimi-claw"]'

常用命令速查

🚀 快速开始命令

# 查看版本
openclaw --version

# 查看帮助
openclaw --help
openclaw <command> --help

# 运行配置向导
openclaw configure
openclaw onboard

# 查看系统状态
openclaw status
openclaw health

🔧 配置管理命令

查看配置
# 查看配置文件路径
openclaw config file

# 获取特定配置项
openclaw config get gateway.port
openclaw config get agents.defaults.model.primary

# 查看完整配置
openclaw config get

# 验证配置有效性
openclaw config validate
修改配置
# 设置配置项
openclaw config set gateway.port 8080
openclaw config set agents.defaults.model.primary "moonshot/kimi-k2.5"

# 删除配置项
openclaw config unset channels.telegram

# 编辑配置文件
openclaw config file --edit
常用配置修改速查
想要修改 配置路径 命令示例
默认模型 agents.defaults.model.primary openclaw config set agents.defaults.model.primary "moonshot/kimi-k2.5"
Gateway 端口 gateway.port openclaw config set gateway.port 8080
启用远程访问 gateway.bind openclaw config set gateway.bind "lan"
Dashboard 跨域 gateway.controlUi.allowedOrigins openclaw config set gateway.controlUi.allowedOrigins '["http://192.168.1.16:8080"]'
修改 Token gateway.auth.token openclaw config set gateway.auth.token "new-token"
工作目录 agents.defaults.workspace openclaw config set agents.defaults.workspace "/new/path"
并发限制 agents.defaults.maxConcurrent openclaw config set agents.defaults.maxConcurrent 4
压缩模式 agents.defaults.compaction.mode openclaw config set agents.defaults.compaction.mode "safeguard"
响应范围 messages.ackReactionScope openclaw config set messages.ackReactionScope "group-mentions"
会话范围 session.dmScope openclaw config set session.dmScope "per-channel-peer"
工具集 tools.profile openclaw config set tools.profile "coding"

🖥️ Gateway 管理命令

# 启动 Gateway
openclaw gateway start
openclaw gateway start --port 8080

# 停止 Gateway
openclaw gateway stop

# 重启 Gateway
openclaw gateway restart

# 查看 Gateway 状态
openclaw gateway status

# 使用 systemd 管理
systemctl --user start openclaw-gateway
systemctl --user stop openclaw-gateway
systemctl --user restart openclaw-gateway
systemctl --user status openclaw-gateway
systemctl --user enable openclaw-gateway  # 开机自启

🤖 Agent 交互命令

# 发送消息给 Agent
openclaw agent --message "你好"

# 使用特定模型
openclaw agent --message "你好" --model moonshot/kimi-k2.5

# 启用推理模式
openclaw agent --message "复杂问题" --reasoning

# 传递上下文
openclaw agent --message "总结刚才的对话" --context

💬 消息管理命令

# 发送消息
openclaw message send --target +1234567890 --message "Hello"
openclaw message send --channel telegram --target @user --message "Hello"

# 读取消息
openclaw message read --channel telegram --limit 10

# 查看会话列表
openclaw sessions list
openclaw sessions list --active-minutes 60

# 查看会话历史
openclaw sessions history <session-key>
openclaw sessions history <session-key> --limit 50

# 清理旧会话
openclaw sessions cleanup --older-than 30d

📺 交互界面命令

# 打开 Dashboard
openclaw dashboard
openclaw dashboard --port 8080
openclaw dashboard --no-open  # 不自动打开浏览器

# 启动 TUI
openclaw tui

# 打开文档
openclaw docs

🔧 Skills 管理命令

# 列出所有 skills
openclaw skills list
openclaw skills list --all

# 查看 skill 详情
openclaw skills show healthcheck
openclaw skills show weather

# 使用 skill
openclaw skill healthcheck run

# 搜索和安装 skills
npx clawhub search <keyword>
npx clawhub install <skill-name>

📡 频道管理命令

# 登录频道
openclaw channels login --channel telegram
openclaw channels login --channel whatsapp
openclaw channels login --channel discord
openclaw channels login --channel slack
openclaw channels login --channel signal

# 列出已配置频道
openclaw channels list

# 测试频道连接
openclaw channels test --channel telegram

# 断开频道
openclaw channels logout --channel telegram

⏰ 定时任务命令

# 列出定时任务
openclaw cron list
openclaw cron list --include-disabled

# 添加定时任务
openclaw cron add --name "daily-report" --schedule "0 9 * * *" --message "生成日报"

# 删除定时任务
openclaw cron remove <job-id>

# 启用/禁用任务
openclaw cron enable <job-id>
openclaw cron disable <job-id>

# 立即运行任务
openclaw cron run <job-id>

# 查看任务执行历史
openclaw cron runs <job-id>

🔐 设备配对命令

# 生成配对二维码
openclaw qr

# 查看配对码
openclaw pairing code

# 列出已配对设备
openclaw devices list

# 撤销设备配对
openclaw devices revoke <device-id>

🩺 诊断与维护命令

# 健康检查
openclaw doctor
openclaw doctor --fix

# 查看系统状态
openclaw system status

# 查看日志
openclaw logs
journalctl --user -u openclaw-gateway -f

# 搜索记忆
openclaw memory search "关键词"

# 备份数据
openclaw backup create
openclaw backup list

🔄 更新与维护命令

# 检查更新
openclaw update check

# 执行更新
openclaw update
npm update -g openclaw

# 查看更新日志
openclaw update changelog

🧪 开发调试命令

# 开发模式运行
openclaw --dev gateway start

# 指定日志级别
openclaw --log-level debug gateway start

# 查看插件状态
openclaw plugins list

# 生成 shell 补全
openclaw completion bash > ~/.bash_completion.d/openclaw

修改后必须重启的服务

# Gateway 配置修改后
openclaw gateway restart

# 或使用 systemd
systemctl --user restart openclaw-gateway

配置命令参考

查看配置

# 查看配置文件路径
openclaw config file

# 查看特定配置项
openclaw config get gateway.port
openclaw config get agents.defaults.model.primary

# 查看完整配置
openclaw config get

修改配置

# 设置配置项
openclaw config set gateway.port 8080
openclaw config set agents.defaults.model.primary "moonshot/kimi-k2.5"

# 删除配置项
openclaw config unset channels.telegram

# 验证配置
openclaw config validate

配置示例

# 修改 Gateway 端口
openclaw config set gateway.port 8080

# 添加 Dashboard 允许来源
openclaw config set gateway.controlUi.allowedOrigins '["http://localhost:8080", "http://192.168.1.16:8080"]'

# 修改默认模型
openclaw config set agents.defaults.model.primary "openai/gpt-4o"

# 修改工作目录
openclaw config set agents.defaults.workspace "/path/to/workspace"

配置文件直接编辑

# 使用默认编辑器打开
openclaw config file --edit

# 或使用指定编辑器
EDITOR=vim openclaw config file --edit

环境变量

OpenClaw 支持以下环境变量：

变量 说明
OPENCLAW_CONFIG_PATH 配置文件路径
OPENCLAW_STATE_DIR 状态数据目录
OPENCLAW_GATEWAY_PORT Gateway 端口
OPENCLAW_GATEWAY_TOKEN 访问令牌
OPENCLAW_LOG_LEVEL 日志级别

使用示例

# 使用自定义配置
OPENCLAW_CONFIG_PATH=/etc/openclaw/config.json openclaw status

# 临时修改端口
OPENCLAW_GATEWAY_PORT=9090 openclaw gateway start

配置文件示例

完整生产环境配置

{
  "meta": {
    "lastTouchedVersion": "2026.3.13",
    "lastTouchedAt": "2026-03-19T10:00:00.000Z"
  },
  "wizard": {
    "lastRunAt": "2026-03-19T10:00:00.000Z",
    "lastRunVersion": "2026.3.13",
    "lastRunCommand": "configure",
    "lastRunMode": "local"
  },
  "auth": {
    "profiles": {
      "moonshot:default": {
        "provider": "moonshot",
        "mode": "api_key"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "moonshot": {
        "baseUrl": "https://api.moonshot.cn/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "kimi-k2.5",
            "name": "Kimi K2.5",
            "api": "openai-completions",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 256000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "moonshot/kimi-k2.5"
      },
      "models": {
        "moonshot/kimi-k2.5": {
          "alias": "Kimi"
        }
      },
      "workspace": "/home/zeven/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },
  "tools": {
    "profile": "coding"
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "channels": {},
  "gateway": {
    "port": 8080,
    "mode": "local",
    "bind": "lan",
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:8080",
        "http://127.0.0.1:8080",
        "http://192.168.1.16:8080"
      ],
      "allowInsecureAuth": true
    },
    "auth": {
      "mode": "token",
      "token": "your-secure-token-here"
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    },
    "nodes": {
      "denyCommands": [
        "camera.snap",
        "camera.clip",
        "screen.record",
        "calendar.add",
        "contacts.add",
        "reminders.add"
      ]
    }
  },
  "plugins": {
    "load": {
      "paths": []
    },
    "entries": {},
    "installs": {}
  }
}

参考链接

  • 官方文档：https://docs.openclaw.ai
  • GitHub：https://github.com/openclaw/openclaw
  • Skills 仓库：https://clawhub.com

希望这篇教程能帮到想要上手 OpenClaw 的朋友，要是觉得内容不错，不妨支持转发一下～

大家如果有任何问题，都可以加入 OpenClaw 交流群探讨提问，后续我会在群里更方便地分享更多好玩的 AI 工具，企业微信和 QQ 的对接教程做好后，也会第一时间在群里同步。加群时请备注：OpenClaw 交流群。

在这里插入图片描述

文档版本：2026.3.13

# 服务器 # linux
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

无头浏览器自动化：Cookie 管理该走 OS Keychain 还是独立 Vault？

avatar 龙虾开发者社区
cover

Webhook 幂等实践：从重复执行到 ClawBridge 的 mTLS 加固

avatar 龙虾开发者社区
cover

Agent日志乱码频发？UTF-8与GBK混编环境的沙箱预处理方案

avatar 龙虾开发者社区