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

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
参考资源:

🦞 祝配置顺利!

相关推荐
谙弆悕博士19 小时前
多智能体架构详解:网状去中心化架构(Mesh对等P2P)
人工智能·架构·去中心化·p2p·多智能体·智能体·langgraph
真上帝的左手3 天前
26. AI-Agent-技术架构:Harness、Runtime、Orchestrator、Framework
人工智能·架构·agent·ai编程·智能体
前进的李工5 天前
Agent 学习笔记 15:Agent 怎样响应事件与中途打断?
人工智能·笔记·agent·openclaw·工具设计·gpt-6 astra·原生异步
小小-猿6 天前
从 gpt-6-luna 到第一个 Nexent 智能体:配置、调试与发布
gpt·大模型·智能体·ai智能体·nexent
科研小刘带你玩学术6 天前
【科研快讯】OpenAI推出ChatGPT Wallet:AI Agent不再只会推荐商品,还能替用户完成支付
人工智能·数字经济·智能体·科技前沿·aiagent·ai支付·智能商务
指尖时光.6 天前
【Agent】个人 Agent 工作台建设指南
agent·知识库·智能体·skill·agent开发
贾伟康10 天前
HarmonyOS API 26 HMAF Skill 可解释任务计划与失败回退
harmonyos·arkts·智能体·skill·hmaf
贾伟康10 天前
HarmonyOS API 26 HMAF 2.0 意图解析的可解释动作图
harmonyos·arkts·智能体·a2a·hmaf
贾伟康11 天前
HarmonyOS API 26 HMAF Skill 多 Skill 冲突仲裁与可恢复执行
harmonyos·arkts·智能体·skill·hmaf
OxYGC12 天前
智能体项目复盘 · 智能客服篇:对话栈、Flow 与策略集成器——LLM 是怎么嵌进传统多轮对话架构的
对话系统·智能客服·rag·智能体