OpenClaw 完整配置详解 - 逐项深度剖析

网管NO.12026-03-28 8:51

把 OpenClaw 配置的每一个项目都单独拆分开，从"是什么"、"为什么"、"怎么配"三个维度进行详细讲解。

目录

  1. 环境与安装阶段

  2. 初始化向导（openclaw onboard）逐项详解

  3. 核心配置文件结构详解

  4. Agent 配置项逐项详解

  5. 模型提供商配置逐项详解

  6. 通信渠道配置逐项详解

  7. 网关配置逐项详解

  8. 会话配置逐项详解

  9. 安全与沙箱配置逐项详解

一、环境与安装阶段

1.1 Node.js 版本要求

项目 详情
配置项名称 Node.js 版本
最低版本 22.0.0
推荐版本 22.11.0 (LTS) 或更高
检查命令 node --version

为什么要 ≥22.x？

  • OpenClaw 使用了 Node.js 22 引入的 --experimental-strip-types 特性来优化 TypeScript 执行

  • 原生 Fetch API 在 22 版本中更稳定

  • 新版 V8 引擎提供更好的性能

各平台安装方法：

bash

复制代码 
# macOS - 使用 Homebrew
brew install node@22

# macOS - 使用 nvm (推荐，可管理多版本)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm alias default 22

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Windows - 使用 WSL2 (推荐)
# 先安装 WSL2，然后在 Ubuntu 子系统内执行上述 Linux 命令

# Windows - 原生 (不推荐)
# 从 nodejs.org 下载 22.x 安装包

1.2 npm 配置

项目 详情
配置项名称 npm 注册表镜像
默认值 https://registry.npmjs.org/
国内推荐 https://registry.npmmirror.com

bash

复制代码 
# 查看当前源
npm config get registry

# 切换到国内镜像（加速安装）
npm config set registry https://registry.npmmirror.com

# 恢复官方源
npm config set registry https://registry.npmjs.org/

1.3 安装方式对比

安装方式 命令 适用场景 优缺点
一键脚本 `curl -fsSL https://openclaw.ai/install.sh bash` 新手、快速部署
npm 全局安装 npm install -g openclaw@latest 有经验的用户 ✅ 标准 npm 流程 ✅ 易于升级 ⚠️ 需要手动配置后续
源码安装 git clone ... && pnpm install && pnpm build 开发者、需要修改源码 ✅ 可使用最新开发版 ✅ 可贡献代码 ⚠️ 需要自行构建

二、初始化向导（openclaw onboard）逐项详解

2.1 启动命令

bash

复制代码 
openclaw onboard

作用 ：以交互式问答方式生成和修改配置文件 ~/.openclaw/openclaw.json

2.2 风险确认

text

复制代码 
? This will modify your configuration. Do you understand? (y/N)
选项 行为
y 继续进入下一步
N 或直接回车 退出向导

为什么需要确认？

  • 配置文件可能包含 API Key 等敏感信息

  • 修改可能影响正在运行的服务

  • 防止误操作

2.3 模式选择

text

复制代码 
? Choose a setup mode:
  ❯ QuickStart (Recommended for new users)
    Advanced (Full control)
    Skip (I'll configure manually)
QuickStart 模式详解
特性 说明
自动选择 使用推荐的默认值，无需逐项确认
模型 自动选择主流的 OpenAI GPT-4o
渠道 跳过，引导用户后续手动配置
Skills 不安装
Hooks 启用 pre-commit 和 post-merge

适用人群：第一次使用 OpenClaw，想最快体验核心功能

Advanced 模式详解
特性 说明
逐项确认 每个配置项都会询问
模型 可自行选择提供商、模型、参数
渠道 可选择配置 Discord/Telegram 等
Skills 可选择安装技能包
Hooks 可选择启用哪些 Git 钩子

适用人群：有经验，需要精确控制每个环节

Skip 模式详解
特性 说明
行为 直接退出向导，不修改配置
后续操作 需手动编辑配置文件或使用 openclaw config set

适用人群：熟悉配置文件结构，想自己从头编写

2.4 模型提供商选择

text

复制代码 
? Select a model provider:
  ❯ OpenAI
    Anthropic (Claude)
    Google (Gemini)
    DeepSeek
    Qwen (Aliyun)
    Custom provider
各提供商详细对比
提供商 API 兼容格式 特色模型 费用 获取 API Key 地址
OpenAI OpenAI GPT-4o, GPT-4o-mini, o1 按 Token 计费 platform.openai.com/api-keys
Anthropic Anthropic Claude 3.5 Sonnet, Claude 3 Opus 按 Token 计费 console.anthropic.com
Google Google AI Gemini 1.5 Pro, Gemini 1.5 Flash 有免费额度 makersuite.google.com/app/apikey
DeepSeek OpenAI 兼容 DeepSeek-V2, DeepSeek-Coder 极低 platform.deepseek.com
Qwen OpenAI 兼容 Qwen-Max, Qwen-Plus, Qwen-Turbo 按 Token 计费 阿里云百炼控制台
Custom 自定义 任意本地/云端模型 取决于服务 自行提供

2.5 API Key 输入方式

text

复制代码 
? How would you like to provide your API key?
  ❯ Paste API key now
    Set environment variable (MANUAL)
    Skip for now
方式一：Paste API key now

text

复制代码 
? Enter your API key: [输入]

存储位置：

  • 加密存储于 ~/.openclaw/credentials/ 目录

  • 格式：{provider}.key 文件

优点：

  • 简单直接，无需额外操作

  • 配置文件和密钥分离

缺点：

  • 明文存储在磁盘上（虽然有文件权限保护）
方式二：Set environment variable

bash

复制代码 
# 设置环境变量（根据选择的提供商不同）
export OPENAI_API_KEY="sk-xxx"
export ANTHROPIC_API_KEY="sk-ant-xxx"
export DASHSCOPE_API_KEY="sk-xxx"
export GOOGLE_API_KEY="xxx"
export DEEPSEEK_API_KEY="sk-xxx"

推荐方式：将环境变量添加到 shell 配置文件：

bash

复制代码 
# 添加到 ~/.bashrc 或 ~/.zshrc
echo 'export OPENAI_API_KEY="sk-xxx"' >> ~/.zshrc
source ~/.zshrc

优点：

  • 更安全，不在磁盘明文存储

  • 便于不同环境切换

方式三：Skip for now

后续配置方法：

bash

复制代码 
# 方法1：使用 config set
openclaw config set models.providers.openai.apiKey "sk-xxx"

# 方法2：直接编辑配置文件
vim ~/.openclaw/openclaw.json

# 方法3：重新运行向导（只配置模型部分）
openclaw onboard --add-model

2.6 默认模型选择

text

复制代码 
? Select default model:
  ❯ gpt-4o (recommended)
    gpt-4o-mini (faster, cheaper)
    gpt-4-turbo
    gpt-3.5-turbo
    o1-preview
    o1-mini
各模型详细对比
模型 上下文长度 输入价格 ($/1M tokens) 输出价格 ($/1M tokens) 特点 推荐场景
gpt-4o 128K 2.50 10.00 平衡性能与速度 日常对话、编程
gpt-4o-mini 128K 0.15 0.60 便宜、快速 简单问答、分类
gpt-4-turbo 128K 10.00 30.00 最强能力 复杂推理、长文档
gpt-3.5-turbo 16K 0.50 1.50 旧版、快 测试、简单任务
o1-preview 128K 15.00 60.00 推理增强 数学、逻辑推理
o1-mini 128K 3.00 12.00 快速推理 代码生成

2.7 自定义提供商配置

如果选择 Custom provider，需要填写以下字段：

text

复制代码 
? Provider ID: [输入]
? Base URL: [输入]
? Model ID: [输入]
? API Key (optional): [输入]
? Compatibility: [openai / anthropic]
Provider ID 详解
项目 说明
作用 在配置中唯一标识这个提供商
命名规则 小写字母、数字、连字符、下划线
示例 my-local-llm、ollama、azure-gpt
Base URL 详解
项目 说明
作用 API 服务的接入点地址
格式 http://host:port/path 或 https://...
必须包含 /v1 结尾（OpenAI 兼容格式）

常见 Base URL 示例：

bash

复制代码 
# Ollama 本地模型
http://localhost:11434/v1

# LM Studio
http://localhost:1234/v1

# 阿里云百炼
https://dashscope.aliyuncs.com/compatible-mode/v1

# vLLM 部署
http://localhost:8000/v1

# Azure OpenAI
https://your-resource.openai.azure.com/openai/deployments/your-deployment
Model ID 详解
项目 说明
作用 具体使用的模型标识符
来源 由提供商定义

示例：

  • llama3.2-3b

  • qwen-max

  • gpt-4o（自定义代理）

  • deepseek-chat

API Key 详解
项目 说明
作用 认证凭证
必填性 取决于提供商，本地模型通常不需要
安全建议 使用环境变量引用

json5

复制代码 
{
  "apiKey": "${MY_CUSTOM_API_KEY}"  // 从环境变量读取
}
Compatibility 详解
选项 说明 典型提供商
openai 兼容 OpenAI API 格式 Ollama、vLLM、DeepSeek、Qwen
anthropic 兼容 Anthropic API 格式 Claude 代理

2.8 渠道选择

text

复制代码 
? Which messaging platform would you like to connect?
  ❯ Discord
    Telegram
    WhatsApp
    Slack
    Signal
    Skip for now (configure later)
Discord 配置详解

Bot Token 获取步骤：

  1. 访问 https://discord.com/developers/applications

  2. 点击 "New Application" → 输入名称 → Create

  3. 左侧菜单选择 "Bot"

  4. 点击 "Reset Token" 或 "Copy" 复制 Token

必需开启的 Privileged Gateway Intents：

  • ✅ MESSAGE CONTENT INTENT

  • ✅ SERVER MEMBERS INTENT

  • ✅ PRESENCE INTENT

邀请 Bot 到服务器的权限：

  • 在 OAuth2 → URL Generator

  • Scopes 勾选：bot、applications.commands

  • Bot Permissions 勾选：

    • Send Messages

    • Read Messages/View Channels

    • Read Message History

    • Use Slash Commands

Telegram 配置详解

Bot Token 获取步骤：

  1. 打开 Telegram，搜索 @BotFather

  2. 发送 /newbot

  3. 输入 Bot 名称（显示名称）

  4. 输入 Bot 用户名（必须以 bot 结尾，如 my_awesome_bot）

  5. 复制返回的 Token

代理配置（国内用户必须）：

json5

复制代码 
{
  "channels": {
    "telegram": {
      "proxy": "socks5://127.0.0.1:7890"
    }
  }
}
WhatsApp 配置详解

特殊说明：

  • 不需要预先获取 Token

  • 启动后终端会显示二维码

  • 用 WhatsApp 扫描即可登录

  • 支持多设备登录

2.9 Skills 安装

text

复制代码 
? Would you like to install any skills?
  ❯ No, skip for now
    Yes, show me available skills
Skills 是什么？

Skills 是 OpenClaw 的扩展功能模块，类似插件或技能包。

可用 Skills 示例：

Skill 名称 功能 安装命令
translate 多语言翻译 clawhub install translate
weather 天气查询 clawhub install weather
wechat-publish 微信公众号发布 clawhub install wechat-publish
email 邮件收发 clawhub install email
calendar 日历管理 clawhub install calendar
news 新闻聚合 clawhub install news

Skill 管理命令：

bash

复制代码 
# 搜索可用技能
clawhub search

# 搜索特定关键词
clawhub search translate

# 查看技能详情
clawhub info translate

# 安装技能
clawhub install translate

# 卸载技能
clawhub uninstall translate

# 列出已安装技能
clawhub list

2.10 Hooks 配置

text

复制代码 
? Which hooks would you like to enable?
  (Use space to select, Enter to confirm)
  ❯ ◉ pre-commit (run checks before commit)
    ◉ post-merge (after pulling changes)
    ◯ pre-push (before pushing to remote)
pre-commit 详解
项目 说明
触发时机 git commit 执行前
默认行为 验证配置文件格式、检查 API Key 有效性
自定义 可在 ~/.openclaw/hooks/pre-commit 添加自定义脚本

为什么推荐启用：

  • 防止提交无效配置

  • 避免将敏感信息（如 API Key）提交到 Git

post-merge 详解
项目 说明
触发时机 git pull 或 git merge 之后
默认行为 重新加载配置、重启服务（如果配置变化）
自定义 可在 ~/.openclaw/hooks/post-merge 添加自定义脚本

为什么推荐启用：

  • 团队协作时自动同步配置

  • 拉取新代码后自动生效

pre-push 详解
项目 说明
触发时机 git push 执行前
默认行为 运行完整测试套件
自定义 可在 ~/.openclaw/hooks/pre-push 添加自定义脚本

适用场景：

  • CI/CD 前验证

  • 确保推送的代码质量

2.11 启动方式选择

text

复制代码 
? How would you like to start the gateway?
  ❯ Web UI (Open in browser)
    TUI (Terminal UI)
    Background service
    Manual
Web UI 详解
项目 说明
启动方式 自动打开浏览器访问 http://127.0.0.1:18789
功能 聊天界面、配置管理、日志查看
适用场景 日常使用、管理

界面说明：

  • 左侧：对话列表

  • 中间：聊天区域

  • 右侧：配置面板、状态信息

TUI (Terminal UI) 详解
项目 说明
启动方式 终端内直接交互
功能 纯命令行聊天体验
适用场景 SSH 远程连接、轻量使用

操作方式：

  • 直接输入消息，回车发送

  • Ctrl+C 退出

  • /help 查看命令

Background service 详解
项目 说明
启动方式 通过 systemd (Linux) 或 launchd (macOS) 后台运行
功能 持续运行，开机自启
适用场景 服务器部署、24/7 运行
Manual 详解
项目 说明
启动方式 不自动启动，后续手动执行
手动启动命令 openclaw gateway start
适用场景 需要调试、临时运行

三、核心配置文件结构详解

3.1 配置文件位置与格式

项目 详情
路径 ~/.openclaw/openclaw.json
格式 JSON5（支持注释、尾逗号）
权限 建议 600（仅所有者可读写）

3.2 完整配置骨架

json5

复制代码 
{
  // ========== Agent 配置 ==========
  "agents": {
    "defaults": { /* 默认 Agent 配置 */ },
    "list": { /* 多 Agent 配置（可选）*/ }
  },
  
  // ========== 模型配置 ==========
  "models": {
    "providers": { /* 模型提供商定义 */ },
    "defaults": { /* 默认模型选择 */ }
  },
  
  // ========== 渠道配置 ==========
  "channels": {
    "discord": { /* Discord 配置 */ },
    "telegram": { /* Telegram 配置 */ },
    "whatsapp": { /* WhatsApp 配置 */ },
    "slack": { /* Slack 配置 */ },
    "signal": { /* Signal 配置 */ }
  },
  
  // ========== 网关配置 ==========
  "gateway": {
    "port": 18789,
    "auth": { /* 认证配置 */ }
  },
  
  // ========== 会话配置 ==========
  "session": {
    "dmScope": "per-channel-peer",
    "reset": { /* 重置策略 */ }
  },
  
  // ========== 安全配置 ==========
  "security": {
    "sandbox": { /* 沙箱配置 */ }
  }
}

四、Agent 配置项逐项详解

4.1 agents.defaults.workspace

json5

复制代码 
{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    }
  }
}
项目 详情
类型 字符串（路径）
默认值 ~/.openclaw/workspace
作用 Agent 的工作目录，存放文件、缓存、临时数据

目录结构：

text

复制代码 
~/.openclaw/workspace/
├── skills/          # 安装的技能
├── cache/           # 模型响应缓存
├── uploads/         # 用户上传的文件
├── downloads/       # Agent 下载的文件
└── logs/            # 运行日志

修改建议：

  • 如果磁盘空间有限，可指向外置硬盘

  • 多个 Agent 可以共享同一个 workspace

4.2 agents.defaults.model

json5

复制代码 
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-4o",
        "fallbacks": ["anthropic/claude-3.5-sonnet"]
      }
    }
  }
}
primary 详解
项目 详情
类型 字符串
格式 {provider}/{model_id}
示例 openai/gpt-4o、anthropic/claude-3.5-sonnet

如何确定可用格式：

bash

复制代码 
# 查看所有已配置模型
openclaw models list
fallbacks 详解
项目 详情
类型 字符串数组
作用 当主模型不可用时，按顺序尝试备选模型

触发条件：

  • API 返回错误（401、429、500 等）

  • 超时（超过 60 秒无响应）

  • 模型不可用（如 OpenAI 服务故障）

示例：

json5

复制代码 
{
  "primary": "openai/gpt-4o",
  "fallbacks": [
    "openai/gpt-4o-mini",           // 第一备选：便宜
    "anthropic/claude-3.5-sonnet",  // 第二备选：不同提供商
    "deepseek/deepseek-chat"        // 第三备选：极低成本
  ]
}

4.3 agents.defaults.temperature

json5

复制代码 
{
  "agents": {
    "defaults": {
      "temperature": 0.2
    }
  }
}
项目 详情
类型 浮点数
范围 0.0 - 1.0
默认值 0.2

数值详解：

值 行为 示例输出
0.0 - 0.1 极度确定，几乎总是相同输出 代码生成、公式计算
0.2 - 0.3 严谨，少量变化 客服回复、文档翻译
0.4 - 0.6 自然，有变化 日常对话、邮件撰写
0.7 - 0.8 创意，多样化 头脑风暴、故事创作
0.9 - 1.0 高度随机，可能不连贯 创意写作、艺术生成

成本影响：

  • 温度越高，Token 使用量可能越大（因为更"发散"）

  • 温度越低，输出更可预测，成本更稳定

4.4 agents.defaults.heartbeat

json5

复制代码 
{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "last",
        "tasks": ["check_mail", "monitor_status"]
      }
    }
  }
}
heartbeat.every 详解
项目 详情
类型 字符串（时间间隔）
格式 {数字}{单位}
单位 s（秒）、m（分）、h（时）、d（天）

示例：

  • "30m"：每 30 分钟

  • "1h"：每小时

  • "12h"：每 12 小时

  • "1d"：每天

heartbeat.target 详解
项目 详情
类型 字符串
可选值 last、all、specific
值 说明
last 将心跳结果发送到最近聊天的窗口
all 发送到所有已连接的渠道
specific 发送到指定渠道/会话（需配合 targetId）

specific 用法：

json5

复制代码 
{
  "heartbeat": {
    "every": "1h",
    "target": "specific",
    "targetId": "discord:123456789"  // 发送到指定 Discord 频道
  }
}
heartbeat.tasks 详解
项目 详情
类型 字符串数组
作用 心跳时执行的任务列表

内置任务：

任务名 功能
status_report 生成系统状态报告
check_mail 检查新邮件
calendar_summary 今日日程摘要
weather_report 天气更新
news_summary 新闻摘要

自定义任务：

  • 放在 ~/.openclaw/workspace/tasks/ 目录下

  • 格式：.js 或 .ts 文件，导出一个 async 函数

4.5 agents.defaults.sandbox

json5

复制代码 
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}
项目 详情
类型 对象
作用 控制 Agent 执行代码的安全性
sandbox.mode 详解
值 说明 安全等级 性能影响
off 禁用沙箱，所有代码直接执行 ❌ 低 无影响
non-main 非主任务（心跳、定时任务）在沙箱中执行 ✅ 中 轻微
all 所有任务（包括对话响应）都在沙箱中执行 ✅✅ 高 明显

沙箱限制：

  • 文件系统访问限制（只能访问 workspace）

  • 网络访问限制（可配置白名单）

  • 进程隔离（无法执行系统命令）

  • 资源限制（CPU、内存、超时）

五、模型提供商配置逐项详解

5.1 models.providers.{providerId}

json5

复制代码 
{
  "models": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "${OPENAI_API_KEY}",
        "api": "openai-completions",
        "models": [ /* 模型列表 */ ]
      }
    }
  }
}
providerId 详解
项目 详情
类型 字符串（键名）
作用 在配置中唯一标识这个提供商
命名建议 使用小写字母和连字符，如 my-llm、azure-gpt

5.2 baseUrl 详解

项目 详情
类型 字符串（URL）
必填 是
格式 必须以 /v1 结尾（OpenAI 兼容格式）

不同场景的 baseUrl：

json5

复制代码 
// OpenAI 官方
"baseUrl": "https://api.openai.com/v1"

// 阿里云百炼
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"

// Ollama 本地
"baseUrl": "http://localhost:11434/v1"

// vLLM 部署
"baseUrl": "http://localhost:8000/v1"

// 代理服务
"baseUrl": "https://your-proxy.com/openai/v1"

5.3 apiKey 详解

项目 详情
类型 字符串
必填 取决于提供商（大多数需要）
安全建议 使用环境变量引用

环境变量引用格式：

json5

复制代码 
"apiKey": "${ENV_VAR_NAME}"

示例：

json5

复制代码 
"apiKey": "${OPENAI_API_KEY}"      // 从环境变量 OPENAI_API_KEY 读取
"apiKey": "${MY_CUSTOM_KEY}"       // 自定义环境变量

5.4 api 详解

项目 详情
类型 字符串
可选值 openai-completions、anthropic-messages
值 说明 适用提供商
openai-completions 使用 OpenAI 的 completions API 格式 OpenAI、DeepSeek、Qwen、Ollama、vLLM
anthropic-messages 使用 Anthropic 的 messages API 格式 Anthropic Claude

5.5 models 数组详解

json5

复制代码 
"models": [
  {
    "id": "gpt-4o",
    "name": "GPT-4o",
    "contextWindow": 128000,
    "maxTokens": 4096,
    "cost": {
      "input": 2.5,
      "output": 10
    }
  }
]
models[].id 详解
项目 详情
类型 字符串
作用 在 primary 和 fallbacks 中使用的标识符
格式 由提供商定义

示例：

  • OpenAI：gpt-4o、gpt-4o-mini

  • Anthropic：claude-3-5-sonnet-20241022

  • DeepSeek：deepseek-chat

  • 自定义：任何字符串，如 llama3.2-3b

models[].name 详解
项目 详情
类型 字符串
作用 在 Web UI 和日志中显示的名称
可选 是
models[].contextWindow 详解
项目 详情
类型 整数
作用 模型能处理的上下文 Token 数上限
可选 是（不配置则使用默认值）

常见模型的 contextWindow：

模型 contextWindow
GPT-4o 128,000
Claude 3.5 Sonnet 200,000
DeepSeek-V2 128,000
Qwen-Max 30,000
models[].maxTokens 详解
项目 详情
类型 整数
作用 单次响应能生成的最大 Token 数
可选 是

默认值：

  • 大多数模型：4096

  • 部分模型：2048

models[].cost 详解
项目 详情
类型 对象
作用 用于成本统计和预算控制
可选 是

json5

复制代码 
"cost": {
  "input": 2.5,   // 每 1M 输入 Token 的价格（美元）
  "output": 10    // 每 1M 输出 Token 的价格（美元）
}

查看成本：

bash

复制代码 
# 查看总成本
openclaw cost summary

# 查看详细成本
openclaw cost report

5.6 models.defaults

json5

复制代码 
{
  "models": {
    "defaults": {
      "provider": "openai",
      "model": "gpt-4o"
    }
  }
}
项目 详情
作用 设置全局默认模型
优先级 低于 agents 中的 model 配置

六、通信渠道配置逐项详解

6.1 渠道通用配置

所有渠道都支持以下通用配置项：

json5

复制代码 
{
  "channels": {
    "discord": {
      "enabled": true,
      "allowFrom": ["123456789"],
      "groups": {
        "*": { "requireMention": true }
      },
      "dmPolicy": "pairing"
    }
  }
}
enabled 详解
项目 详情
类型 布尔值
默认值 false
作用 是否启用该渠道
allowFrom 详解
项目 详情
类型 字符串数组
作用 允许的用户/频道/群组 ID 列表
特殊值 "*" 表示允许所有人

格式：

  • Discord：频道 ID 或用户 ID

  • Telegram：用户 ID（数字）

  • WhatsApp：手机号（带国家码）

示例：

json5

复制代码 
"allowFrom": [
  "123456789",           // 单个 ID
  "987654321",           // 另一个 ID
  "*"                    // 允许所有人
]
groups.*.requireMention 详解
项目 详情
类型 布尔值
默认值 true
作用 在群聊中，是否需要 @机器人 才回复
值 行为
true 必须 @机器人 才回复（推荐）
false 监听群聊所有消息（可能造成刷屏）
dmPolicy 详解
项目 详情
类型 字符串
可选值 pairing、open、blocked
值 说明
pairing 需要配对确认（用户发送配对码，机器人回复确认后才可对话）
open 任何人私聊都直接回复
blocked 禁止私聊

配对流程：

  1. 用户向机器人发送任意消息

  2. 机器人回复配对码（如 123456）

  3. 用户在聊天中输入配对码

  4. 配对成功，开始对话

6.2 Discord 专属配置

json5

复制代码 
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "${DISCORD_BOT_TOKEN}",
      "allowFrom": [],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}
discord.token 详解
项目 详情
类型 字符串
获取方式 Discord Developer Portal → Bot → Token
格式 类似 MTIzNDU2Nzg5MDEyMzQ1Njc4.OpQrS.xxxxxxxxxxxxxxxxxxxxx

6.3 Telegram 专属配置

json5

复制代码 
{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "proxy": "socks5://127.0.0.1:7890"
    }
  }
}
telegram.botToken 详解
项目 详情
类型 字符串
获取方式 @BotFather → /newbot → 复制 Token
格式 类似 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
telegram.proxy 详解
项目 详情
类型 字符串
作用 代理服务器地址
格式 socks5://host:port 或 http://host:port

国内用户必须配置，否则无法连接 Telegram API。

6.4 WhatsApp 专属配置

json5

复制代码 
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+8613912345678"]
    }
  }
}

特殊说明：

  • 不需要预先配置 token

  • 启动后扫码登录

  • 登录后 session 会保存，下次无需重新扫码

首次启动流程：

bash

复制代码 
openclaw gateway start
# 终端显示二维码
# 用 WhatsApp 扫描
# 登录成功

七、网关配置逐项详解

7.1 gateway.port

json5

复制代码 
{
  "gateway": {
    "port": 18789
  }
}
项目 详情
类型 整数
默认值 18789
范围 1024 - 65535
作用 Web UI 和 API 监听的端口

修改方法：

bash

复制代码 
openclaw config set gateway.port 18790

7.2 gateway.auth

json5

复制代码 
{
  "gateway": {
    "auth": {
      "token": "${GATEWAY_TOKEN}",
      "enabled": true
    }
  }
}
auth.token 详解
项目 详情
类型 字符串
作用 Web UI 访问令牌
获取方式 自动生成，或手动设置

自动生成：首次启动时自动生成，存储在配置文件中

访问 URL 格式：

text

复制代码 
http://127.0.0.1:18789/#token=xxxxx
auth.enabled 详解
项目 详情
类型 布尔值
默认值 true
作用 是否启用 token 认证

注意：生产环境强烈建议保持开启，否则任何人都可以访问你的 Web UI。

八、会话配置逐项详解

8.1 session.dmScope

json5

复制代码 
{
  "session": {
    "dmScope": "per-channel-peer"
  }
}
项目 详情
类型 字符串
可选值 per-channel、per-channel-peer、global
各值详解
值 说明 行为
per-channel 同一频道内所有用户共享上下文 A 用户说的话，B 用户也能看到历史
per-channel-peer 每个用户独立上下文（推荐） 每个用户有自己的记忆，互不干扰
global 所有对话共享一个上下文 所有用户和渠道共享同一个记忆

示例场景：

假设有两个用户 A 和 B 在同一个 Discord 频道：

  • per-channel：A 说"我叫小明"，B 问"我叫什么"，机器人会回答"小明"

  • per-channel-peer：A 说"我叫小明"，B 问"我叫什么"，机器人会回答"我不知道，请告诉我你的名字"

8.2 session.reset

json5

复制代码 
{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4
    }
  }
}
reset.mode 详解
值 说明
daily 每天固定时间重置
never 从不自动重置（需手动重置）
manual 手动重置
reset.atHour 详解
项目 详情
类型 整数
范围 0 - 23
作用 当 mode 为 daily 时，指定重置的小时

示例：

json5

复制代码 
"reset": {
  "mode": "daily",
  "atHour": 4  // 每天凌晨 4 点重置
}

8.3 session.maxHistory

json5

复制代码 
{
  "session": {
    "maxHistory": 50
  }
}
项目 详情
类型 整数
默认值 50
作用 每个会话最多保留的消息条数

设置建议：

  • 日常对话：30-50

  • 长文本任务：100

  • 内存有限：20

8.4 session.ttl

json5

复制代码 
{
  "session": {
    "ttl": 86400
  }
}
项目 详情
类型 整数
单位 秒
默认值 86400（24 小时）
作用 会话的存活时间，超时后自动清除

常用值：

  • 1 小时：3600

  • 12 小时：43200

  • 1 天：86400

  • 7 天：604800

九、安全与沙箱配置逐项详解

9.1 security.sandbox

json5

复制代码 
{
  "security": {
    "sandbox": {
      "mode": "non-main",
      "allowedPaths": ["/tmp"],
      "allowedDomains": ["api.example.com"],
      "memoryLimit": 512,
      "cpuLimit": 1,
      "timeout": 30000
    }
  }
}
security.sandbox.mode

（已在 4.5 节详细说明）

security.sandbox.allowedPaths
项目 详情
类型 字符串数组
作用 沙箱内允许访问的额外路径

示例：

json5

复制代码 
"allowedPaths": [
  "/tmp",                           // 临时目录
  "/home/user/data"                 // 数据目录
]

默认允许的路径：workspace 目录

security.sandbox.allowedDomains
项目 详情
类型 字符串数组
作用 沙箱内允许访问的域名白名单

示例：

json5

复制代码 
"allowedDomains": [
  "api.openai.com",                 // OpenAI API
  "api.anthropic.com",              // Anthropic API
  "newsapi.org"                     // 新闻 API
]
security.sandbox.memoryLimit
项目 详情
类型 整数
单位 MB
默认值 512
作用 沙箱进程的最大内存限制
security.sandbox.cpuLimit
项目 详情
类型 整数或浮点数
单位 CPU 核心数
默认值 1
作用 沙箱进程的最大 CPU 使用限制
security.sandbox.timeout
项目 详情
类型 整数
单位 毫秒
默认值 30000（30 秒）
作用 沙箱任务的超时时间

附录：配置管理命令速查

查看配置

bash

复制代码 
# 查看完整配置
openclaw config get

# 查看特定配置项
openclaw config get agents.defaults.temperature

# 查看 JSON 格式
openclaw config get --json

修改配置

bash

复制代码 
# 设置配置项
openclaw config set agents.defaults.temperature 0.5

# 删除配置项
openclaw config delete agents.defaults.temperature

配置文件操作

bash

复制代码 
# 编辑配置文件（使用默认编辑器）
openclaw config edit

# 验证配置文件语法
openclaw config validate

# 重置为默认配置
openclaw config reset
相关推荐
m0_488913012 小时前
收藏备用！大厂AI Agent开发岗位解析+小白友好学习路线（程序员必看）
人工智能·学习·langchain·大模型·agent·就业·大模型学习
mit6.8242 小时前
agent|世界模型|产业链
人工智能
网管NO.12 小时前
OpenClaw 完整部署教程（双方案 + 混合模型）
运维·服务器·网络
荣仔灬2 小时前
怎么查询SSL证书的信息？
网络·网络协议·ssl
新缸中之脑2 小时前
智能体间通信实践指南
人工智能
GOWIN革文品牌咨询2 小时前
国际B2B品牌定位，先把“角色模型”搭出来
大数据·人工智能
皮卡 | 皮卡 | 丘尊2 小时前
关于相机和坐标的问题
人工智能·数码相机·计算机视觉
cui_win2 小时前
Rocky Linux(9.7) 完整使用指南（ISO下载 + 系统安装 + 网络配置）
linux·网络·rocky linux
踩着两条虫2 小时前
VTJ.PRO 在线应用开发平台的工作台与后台管理视图
前端·人工智能·ai编程
热门推荐
012026年3月AI领域大事件：DeepSeek引领开源风暴02GitHub 镜像站点03围棋-html版本04班级宠物园部署指南05小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）06【计算机一级WPSoffice】小黑课堂题库软件下载安装教程（2026年3月最新版）07Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南08UV安装并设置国内源09OpenClaw 使用和管理 MCP 完全指南10中国象棋-html版本