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

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

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

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

1.1 安装 ✅

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

📖 其他安装方式： 或 （未验证）

1.2 配置向导 ✅

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

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

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

2.1 在 Wizard 中配置 ✅

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

• Provider URL:
• API Key: 从 https://open.bigmodel.cn/usercenter/apikeys 获取

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

配置完成后会生成 模型。

2.2 修复 Context Window ⚠️ 必做

Wizard 生成的默认配置 contextWindow 只有 4096，会导致错误：

编辑 ，找到 配置并修改：

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

2.3 验证配置 ✅

确认输出显示 而非 context window 错误，并检查 显示 （不是 bootstrapping）。

2.4 关于 Memory Search ✅

可能显示 ，这是正常的。OpenClaw 有两套记忆系统：Session Transcript（已启用，基于 JSONL 文件）和 Semantic Memory（不可用，需要 Embedding Provider）。实测表明 Memory unavailable 不影响核心功能，200k context window 足够日常使用。对话保存在 ，每次加载整个 session 到 context。如果想消openclaw 安装除警告，可在配置中添加 。

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: ），复制 Token（格式：）。此 token 只显示一次，务必保存。

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

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

权限说明：

• ：接收 @mention 事件
• ：在公开频道发送消息
• ：在未加入的频道发送消息
• , , , ：读取各类频道的消息历史
• , ：DM（私信）场景必需，缺少会导致 missing_scope
• , ：私密频道场景必需
• ：读取用户信息
• ：App Agent 功能

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

3.4 配置 Event Subscriptions ⚠️ 坑点

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

, , , ,

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

3.5 安装 App ✅

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

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

3.6 配置 OpenClaw ✅

编辑 ，添加或修改 部分：

配置说明： 使用 Socket Mode； 表示频道需要 @mention； 表示 DM 需要批准配对。

3.7 验证连接 ✅

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

4.1 启动 Gateway ✅

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

4.2 使用 TUI ✅

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

4.3 在 Slack 中使用 ✅

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

频道方式： 在频道中运行 邀请 bot，然后 与 bot 对话。

4.4 查看日志 ✅

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

4.5 停止服务 ✅

5.1 TUI 卡在 “twiddling thumbs” / “noodling” ⚠️

现象： 显示 或 ，长时间无响应。

排查： 运行 查看 Agents 状态，如果显示 说明 agent 未启动成功。运行 查看模型状态。

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

解决： 修改 中 provider 的 contextWindow 为 和 maxTokens 为 （见 2.2 节），重启并验证 。

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

5.2 Slack Bot 不回复 – missing_scope ⚠️

场景 A – 公开频道正常，DM 无响应： 日志显示 。原因是缺少 scope， 只能在频道用。解决方案：添加 和 → Reinstall to Workspace → 。

场景 B – 日志完全没有消息记录： 在 Slack 发消息， 完全无输出。原因是 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 失败

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

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

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

解决（如频繁出现）： 测试网络 ，检查 DNS ，如需要设置为 Google DNS 。如果不需要 web 搜索功能，可运行 。

6.1 Agent 一直 “bootstrapping”

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

诊断步骤： → →

6.2 Context Window 错误

症状：

解决：编辑 （不是 models.json）的 provider 配置，设置 contextWindow 为 和 maxTokens 为 （见 2.2 节），重启并验证 。

6.3 Slack missing_scope

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

6.4 配对（Pairing）

DM bot 时收到配对码请求是正常安全机制。运行 查看请求， 批准。如想禁用配对（不推荐），运行 。

6.5 常用诊断命令

7.1 长期记忆系统 🔬

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

7.2 Skills 配置 🔬

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

7.3 多 Agent 系统 🔬

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

7.4 其他方向 🔬

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

安装验证： 显示版本 | 显示 running | 无 CRITICAL 错误

GLM-5 验证： API Key 已配置 | 中 contextWindow 为 、maxTokens 为 | 显示 ok | Agent 状态为

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

功能验证： TUI 能正常对话 | Slack DM 和频道能正常对话 | 能看到消息记录 | 没有持续的 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
参考资源：

• 官方文档：https://docs.openclaw.ai/
• 智谱AI：https://open.bigmodel.cn/ | https://docs.bigmodel.cn/
• Slack API：https://api.slack.com/docs

🦞 祝配置顺利！