OpenClaw 完全配置指南：从安装到 Slack 集成

gwd2002026-02-19 8:12

OpenClaw 完全配置指南：从安装到 Slack 集成

本指南基于 OpenClaw 2026.2.15，完整记录了实际配置过程、遇到的问题及解决方案。本文采用实测优先原则，明确标注哪些内容已验证、哪些来自官方文档但未亲测。

文档说明： ✅ 已验证 | 📖 来自文档 | ⚠️ 已知坑点 | 🔬 待探索
测试环境： WSL2 Ubuntu + OpenClaw 2026.2.15

目录

  • [1. 安装 OpenClaw](#1. 安装 OpenClaw)
  • [2. 配置 GLM-5](#2. 配置 GLM-5)
  • [3. Slack Bot 配置](#3. Slack Bot 配置)
  • [4. 启动和使用](#4. 启动和使用)
  • [5. 故障排查实录](#5. 故障排查实录)
  • [6. 常见问题 FAQ](#6. 常见问题 FAQ)
  • [7. 后续探索方向](#7. 后续探索方向)
  • [8. 配置检查清单](#8. 配置检查清单)

1. 安装 OpenClaw

1.1 安装 ✅

bash 复制代码 
# WSL2 Ubuntu 安装（实测）
curl -fsSL https://openclaw.ai/install.sh | bash

# 验证
openclaw --version

安装脚本会自动检测系统环境、安装依赖、配置 PATH，并启动配置向导。

📖 其他安装方式：npm install -g openclaw 或 pnpm install -g openclaw（未验证）

1.2 配置向导 ✅

安装后自动启动 wizard，或手动运行 openclaw onboard。向导会引导你选择模型提供商、配置 API Key、设置工作区等。

Skills 配置建议： 全部 Skip。部分 skills 需要 Homebrew、额外 API keys 或系统依赖，Skip 不影响核心对话功能。后续需要时可通过 openclaw skills enable <name> 单独启用。

Hooks 配置建议： 全选。Hooks 是事件钩子机制，不需要额外依赖。

2. 配置 GLM-5

2.1 在 Wizard 中配置 ✅

运行 openclaw onboard，选择添加自定义模型提供商，输入以下信息：

⚠️ 注意：使用通用 API endpoint，不要使用 code-plan 专用 URL，否则容易被封号。

配置完成后会生成 custom-open-bigmodel-cn/glm-5 模型。

2.2 修复 Context Window ⚠️ 必做

Wizard 生成的默认配置 contextWindow 只有 4096，会导致错误：Model context window too small (4096 tokens). Minimum is 16000.

编辑 ~/.openclaw/openclaw.json，找到 models.providers 配置并修改：

json 复制代码 
{
  "models": {
    "mode": "merge",
    "providers": {
      "custom-open-bigmodel-cn": {
        "baseUrl": "https://open.bigmodel.cn/api/paas/v4/",
        "apiKey": "your-api-key-here",
        "api": "openai-completions",
        "models": [
          {
            "id": "glm-5",
            "name": "glm-5 (Custom Provider)",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 4,
              "output": 18,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 128000
          }
        ]
      }
    }
  }
}

重要说明： GLM-5 实际规格为 200k context window、128k max output tokens（参考智谱AI官方文档）。不要直接修改 agents/main/agent/models.json，它会被 openclaw.json 中的 provider 配置覆盖。

2.3 验证配置 ✅

bash 复制代码 
openclaw gateway restart
sleep 15
openclaw models status --probe

确认输出显示 ok 而非 context window 错误，并检查 openclaw status 显示 Agents: 1 active（不是 bootstrapping）。

openclaw status 可能显示 Memory: enabled (plugin memory-core) · unavailable，这是正常的。OpenClaw 有两套记忆系统：Session Transcript（已启用，基于 JSONL 文件）和 Semantic Memory（不可用，需要 Embedding Provider）。实测表明 Memory unavailable 不影响核心功能，200k context window 足够日常使用。对话保存在 ~/.openclaw/agents/main/sessions/*.jsonl，每次加载整个 session 到 context。如果想消除警告，可在配置中添加 agents.defaults.memorySearch.enabled: false。

3. Slack Bot 配置

3.1 创建 Slack App ✅

访问 https://api.slack.com/apps，点击 Create New App → From scratch ，输入 App Name（如 "OpenClaw"），选择工作区，点击 Create App。

3.2 启用 Socket Mode ✅

左侧菜单 → Socket Mode → Enable Socket Mode ，创建 App-Level Token（Scope: connections:write），复制 Token（格式：xapp-...）。此 token 只显示一次，务必保存。

3.3 配置 Bot Token Scopes ⚠️ 关键步骤

这是最容易出错的部分，权限不全会导致 missing_scope 错误。左侧菜单 → OAuth & Permissions → Bot Token Scopes，添加以下所有权限：

Scope Scope Scope
app_mentions:read chat:write chat:write.public
channels:history groups:history im:history
mpim:history im:write im:read
groups:write groups:read users:read
assistant:write

权限说明：

  • app_mentions:read：接收 @mention 事件
  • chat:write：在公开频道发送消息
  • chat:write.public：在未加入的频道发送消息
  • channels:history, groups:history, im:history, mpim:history：读取各类频道的消息历史
  • im:write, im:read：DM（私信）场景必需，缺少会导致 missing_scope
  • groups:write, groups:read：私密频道场景必需
  • users:read：读取用户信息
  • assistant:write：App Agent 功能

⚠️ 常见坑点 ：chat:write 只能在频道使用，DM 必须要 im:write；私密频道必须要 groups:write。这是 missing_scope 错误的主要来源。

3.4 配置 Event Subscriptions ⚠️ 坑点

左侧菜单 → Event Subscriptions → 开启 Enable Events → Subscribe to bot events 添加：

message.channels, message.groups, message.im, message.mpim, app_mention

⚠️ 重要：修改 Event Subscriptions 后必须重新安装 app，否则不生效！实测表明只修改不 Reinstall 会导致日志完全无记录。

3.5 安装 App ✅

左侧菜单 → Install App → Install to Workspace （首次）或 Reinstall to Workspace （修改配置后），授权所有权限，复制 Bot User OAuth Token（格式：xoxb-...）。

⚠️ 每次修改 Scopes 或 Events 都要 Reinstall to Workspace！

3.6 配置 OpenClaw ✅

编辑 ~/.openclaw/openclaw.json，添加或修改 channels 部分：

json 复制代码 
{
  "channels": {
    "slack": {
      "mode": "socket",
      "enabled": true,
      "botToken": "xoxb-your-bot-token-here",
      "appToken": "xapp-your-app-token-here",
      "groupPolicy": "open",
      "dmPolicy": "pairing"
    }
  }
}

配置说明：mode: "socket" 使用 Socket Mode；groupPolicy: "open" 表示频道需要 @mention；dmPolicy: "pairing" 表示 DM 需要批准配对。

bash 复制代码 
openclaw gateway restart

3.7 验证连接 ✅

bash 复制代码 
openclaw channels status --probe

确认输出显示 Slack ON / OK。运行 openclaw logs --follow，然后在 Slack 发消息，应该能看到日志输出。如果日志无反应，检查 Event Subscriptions 是否配置并 Reinstall。

4. 启动和使用

4.1 启动 Gateway ✅

bash 复制代码 
openclaw gateway start
openclaw status

确认 Gateway service 显示 running，Agents 显示 1 active（不是 bootstrapping），Channels Slack 显示 ON/OK，Sessions 显示 glm-5 (200k ctx)。

4.2 使用 TUI ✅

运行 openclaw tui 启动终端界面。TUI 是测试 agent 最快的方式，如果能正常对话，说明 Gateway、Agent、模型 API 和 Context window 配置都正确。

4.3 在 Slack 中使用 ✅

DM 方式： 在 Slack 中点击 bot 头像进入私聊，直接发送消息。首次使用时 bot 会回复配对码，运行 openclaw pairing list slack 查看请求，openclaw pairing approve slack <code> 批准配对。

频道方式： 在频道中运行 /invite @YourBotName 邀请 bot，然后 @YourBotName 消息内容 与 bot 对话。

4.4 查看日志 ✅

运行 openclaw logs --follow 查看实时日志。调试时建议开两个终端，一个运行日志，一个在 Slack 发消息，观察是否有消息接收记录、是否有错误（如 missing_scope）、Agent 调用了哪些工具。

日志文件位置：/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

Systemd 日志：journalctl -u openclaw-gateway -f

4.5 停止服务 ✅

bash 复制代码 
openclaw gateway stop
openclaw gateway status  # 验证已停止
systemctl --user disable openclaw-gateway  # 禁用开机自启

5. 故障排查实录

5.1 TUI 卡在 "twiddling thumbs" / "noodling" ⚠️

现象： openclaw tui 显示 ⠇ twiddling thumbs... • 6m 59s | connected 或 ⠋ noodling... • 43s | connected，长时间无响应。

排查： 运行 openclaw status 查看 Agents 状态，如果显示 1 bootstrapping 说明 agent 未启动成功。运行 openclaw models status --probe 查看模型状态。

根本原因（实测）： Custom Provider 配置的 context window 只有 4096，OpenClaw 要求最少 16000。

解决： 修改 ~/.openclaw/openclaw.json 中 provider 的 contextWindow 为 200000 和 maxTokens 为 128000（见 2.2 节），重启并验证 openclaw gateway restart && sleep 15 && openclaw status。

教训： 不要直接改 agents/main/agent/models.json，它会被 openclaw.json 覆盖。要改源头配置。

5.2 Slack Bot 不回复 - missing_scope ⚠️

场景 A - 公开频道正常，DM 无响应： 日志显示 slack final reply failed: Error: An API error occurred: missing_scope。原因是缺少 im:write scope，chat:write 只能在频道用。解决方案：添加 im:write 和 im:read → Reinstall to Workspace → openclaw gateway restart。

场景 B - 日志完全没有消息记录： 在 Slack 发消息，openclaw logs --follow 完全无输出。原因是 Event Subscriptions 配置不完整或修改后没有 Reinstall。解决方案：检查 Event Subscriptions 是否启用，确认添加了所有必需的 bot events（message.channels, message.groups, message.im, message.mpim, app_mention），Reinstall to Workspace，重启 OpenClaw。

教训： 不同场景需要不同 scope（公开频道: chat:write，私密频道: groups:write，DM: im:write）。修改 Scopes 或 Events 后必须 Reinstall。

5.3 web_fetch 失败

现象： 日志显示 web_fetch failed: fetch failed。Agent 尝试调用 web_fetch 工具时部分请求失败，但会重试其他 URL 或继续执行。

影响： 不影响最终响应，agent 有重试机制。偶尔的 fetch 失败是正常的。

可能原因： 网络波动、WSL2 DNS 问题、网站限制或需要认证。

解决（如频繁出现）： 测试网络 curl -I https://www.google.com，检查 DNS cat /etc/resolv.conf，如需要设置为 Google DNS echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf。如果不需要 web 搜索功能，可运行 openclaw config set agents.main.skills.web_fetch.enabled false && openclaw gateway restart。

6. 常见问题 FAQ

6.1 Agent 一直 "bootstrapping"

openclaw status 显示 Agents: 1 bootstrapping 长时间不变。可能原因：Context window 配置错误（运行 openclaw models status --probe 检查），模型 API 连接失败，或 Gateway 启动未完成（等待 30 秒后重新检查）。实测表明 Memory unavailable 不会导致 bootstrapping。

诊断步骤：openclaw models status --probe → openclaw doctor → openclaw logs --follow

6.2 Context Window 错误

症状：Model context window too small (4096 tokens). Minimum is 16000.

解决：编辑 ~/.openclaw/openclaw.json（不是 models.json）的 provider 配置，设置 contextWindow 为 200000 和 maxTokens 为 128000（见 2.2 节），重启并验证 openclaw gateway restart && openclaw models status --probe。

6.3 Slack missing_scope

根据使用场景添加对应 scope，修改后必须 Reinstall to Workspace 并重启 OpenClaw。

DM 不回复：添加 im:write, im:read

私密频道不回复：添加 groups:write, groups:read

完全没日志：检查 Event Subscriptions，添加所有必需 events，Reinstall

6.4 配对（Pairing）

DM bot 时收到配对码请求是正常安全机制。运行 openclaw pairing list slack 查看请求，openclaw pairing approve slack <code> 批准。如想禁用配对（不推荐），运行 openclaw config set channels.slack.dmPolicy open && openclaw gateway restart。

6.5 常用诊断命令

bash 复制代码 
openclaw doctor                      # 健康检查
openclaw status                      # 整体状态
openclaw models status --probe       # 测试模型 API
openclaw channels status --probe     # 测试频道连接
openclaw logs --follow               # 实时日志
openclaw gateway status              # Gateway 状态
openclaw pairing list slack          # Slack 配对请求

7. 后续探索方向

7.1 长期记忆系统 🔬

当前使用 Session Transcript（JSONL 文件，无 embedding），容量受限于 200k context window。探索方向：使用 OpenAI/Gemini Embedding（配置 API key 到 ~/.openclaw/.env），智谱AI Embedding（理论可行但需验证，可能需要代码级修改），或本地 Embedding 模型（参考 https://docs.openclaw.ai/memory/local-embeddings）。

7.2 Skills 配置 🔬

当前所有 skills 已 skip。后续可运行 openclaw skills list 查看可用 skills，openclaw skills enable <name> 启用特定 skill。常用 skills：web_search（需 Brave API）、browser（需 Playwright）、code_execution（需沙箱）。

7.3 多 Agent 系统 🔬

OpenClaw 支持多个独立 agent，适用于不同任务使用不同模型、隔离配置、测试新配置等场景。命令：openclaw agents create <name>、openclaw tui --agent <name>。

7.4 其他方向 🔬

自定义工具（https://docs.openclaw.ai/tools/custom）、其他 LLM Provider（Claude、Qwen、DeepSeek）、WhatsApp/Telegram 集成、语音输入输出。

8. 配置检查清单

安装验证： openclaw --version 显示版本 | openclaw gateway status 显示 running | openclaw doctor 无 CRITICAL 错误

GLM-5 验证： API Key 已配置 | openclaw.json 中 contextWindow 为 200000、maxTokens 为 128000 | openclaw models status --probe 显示 ok | Agent 状态为 1 active

Slack 验证： Socket Mode 已启用 | App Token (xapp-) 和 Bot Token (xoxb-) 已配置 | 所有必需 Bot Scopes 已添加（见 3.3 节表格） | Event Subscriptions 已启用并添加所有 events | App 已 Reinstall to Workspace | openclaw channels status --probe 显示 OK | Bot 已被邀请到测试频道

功能验证： TUI 能正常对话 | Slack DM 和频道能正常对话 | openclaw logs --follow 能看到消息记录 | 没有持续的 missing_scope 错误

结语

本指南基于 WSL2 环境的实际配置经验整理。关键要点：使用官方安装脚本；GLM-5 配置需在 wizard 后手动修改 openclaw.json 的 contextWindow 和 maxTokens，不要改 models.json；Slack 权限需根据场景添加对应 scope，修改后必须 Reinstall；Memory unavailable 不影响核心功能。

本文档的局限性： 已验证 WSL2 安装、GLM-5 Custom Provider 配置、Slack Bot 集成和故障排查；未验证标准 zai provider、智谱 Embedding、高级 Skills 和多 Agent 系统；部分命令和配置选项来自官方文档。

文档版本： 4.0
基于 OpenClaw 版本： 2026.2.15
测试环境： WSL2 Ubuntu
最后更新： 2026-02-17
参考资源：

🦞 祝配置顺利！

相关推荐
FeelTouch Labs15 小时前
智能体Workflow的技术实现分类
智能体
坐吃山猪15 小时前
OpenClaw01-Skill-天气
openclaw
AI周红伟1 天前
周红伟：具身机器人大爆炸了，机器人时代来临
大数据·人工智能·机器人·大模型·智能体·seedance
带娃的IT创业者1 天前
解密OpenClaw系列10-OpenClaw系统要求
人工智能·macos·ios·objective-c·ai智能体·智能体开发·openclaw
AI周红伟1 天前
周红伟：2026年10个AI预言：迈向AGI通用人工智能体时代
大数据·人工智能·机器学习·大模型·agi·智能体·seedance
阿杰学AI1 天前
AI核心知识109—大语言模型之 Industry Agent Operations Specialist（简洁且通俗易懂版）
大数据·人工智能·ai·语言模型·agent·智能体·行业智能体运营师
SunnyRivers1 天前
智能体与工具集成
langchain·工具·智能体
带娃的IT创业者1 天前
解密OpenClaw系列09-OpenClaw核心功能特性
macos·objective-c·ai agent·ai智能体·openclaw
铁甲前沿1 天前
OpenClaw从零开始（篇一，初识OpenClaw）
microsoft·openclaw
热门推荐
01GitHub 镜像站点02从零搭建一个 PHP 登录注册系统（含完整源码）03使用 1panel面板 部署 php网站04openClaw安装飞书插件｜核心踩坑：spawn EINVAL 错误终极解决指南05AI Agent 平台横评：ZeroClaw vs OpenClaw vs Nanobot06MIUI显示/隐藏5G开关的方法，信号弱时开启手机Wifi通话方法07让你的代码更整洁：10 个必知的 Kotlin 扩展函数08Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services09如何解决 OpenClaw “Pairing required” 报错：两种官方解决方案详解10openclaw 配置飞书 报错 应用未建立长连接