OpenClaw 自托管 AI Agent：钉钉/飞书/企业微信多渠道网关实战

时间锚点：2025-09——OpenClaw 2026.4.x 时代，已支持 Discord/飞书/钉钉/企业微信/WhatsApp/Telegram/Slack 多通道

一、OpenClaw 是什么

OpenClaw（社区昵称"小龙虾"）是 2024 年底兴起的 自托管 AI Agent 网关——把 LLM 能力通过聊天工具（飞书、钉钉、Discord 等）暴露给最终用户，自己控制配置、数据、记忆。

定位差异：

工具	定位	是否自托管	通道
OpenClaw	自托管多 Agent 网关	是	飞书/钉钉/企微/Discord 等
Coze / 扣子	云端 Bot 平台	否（字节云）	多通道
Dify	自托管 LLM 应用平台	是	API
OpenAI GPTs	云端 Bot	否	API

OpenClaw 的核心卖点：

配置 + 记忆 + 工作区全部存在 ~/.openclaw/，可 git 版本控制
多 Agent 路由——不同 Agent 不同人格（SOUL.md），不同工作区
通道抽象——一套命令同时管理飞书/钉钉/Discord/Telegram/Slack

二、安装与初始化

2.1 系统要求

Node.js 22+
端口 18789（可改）

2.2 macOS / Linux 一键安装

1
curl -fsSL https://openclaw.ai/install.sh | bash

2.3 Windows 一键安装（PowerShell）

1
iwr -useb https://openclaw.ai/install.ps1 | iex

2.4 升级

1
npm install -g openclaw@latest

2.5 源码安装（开发者）

1
2
3
4
5
6
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm openclaw onboard --install-daemon

2.6 启动向导

1
openclaw onboard --install-daemon

向导中会依次询问：

模型 / 鉴权 provider（Skip for now 也可）
默认模型（如 anthropic/claude-opus-4-6）
通道（Skip for now 也可）
搜索 provider
技能配置（No 也可）

启动后核心目录结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
~/.openclaw/
├── openclaw.json              # 主配置（JSON/JSON5）
├── openclaw.json.bak          # 自动备份
├── workspace/                 # 默认 AI "灵魂" 文件夹（推荐 git）
│   ├── SOUL.md                # 人格设定（语气、风格）
│   ├── USER.md                # 用户信息
│   ├── MEMORY.md              # 长期记忆
│   ├── IDENTITY.md            # Agent 名称、形象
│   ├── AGENTS.md              # 多 Agent 路由规则
│   ├── BOOT.md                # 启动提示词
│   ├── HEARTBEAT.md           # 每日检查清单
│   └── skills/                # 已安装技能
├── agents/<cid>/              # 每个 Agent 的独立状态
├── memory/<cid>.sqlite        # 向量记忆库
├── credentials/               # API Key、OAuth（旧版）
├── skills/                    # 全局技能包
├── extensions/                # 插件安装目录
└── secrets.json               # 加密凭证

三、关键路径速查

路径	用途
`~/.openclaw/openclaw.json`	主配置文件
`~/.openclaw/workspace/`	默认工作区
`~/.openclaw/agents/<cid>/`	Agent 状态
`~/.openclaw/agents/<cid>/agent/auth-profiles.json`	OAuth / API Key
`~/.openclaw/memory/<cid>.sqlite`	向量记忆库
`~/.openclaw/skills/`	全局技能
`/tmp/openclaw/*.log`	网关文件日志

四、网关管理与诊断

1
2
3
4
5
6
7
8
9
openclaw gateway status    # 查看网关服务状态
openclaw gateway start     # 启动
openclaw gateway stop      # 停止
openclaw gateway restart   # 重启
openclaw gateway run       # 前台运行（调试用）
openclaw gateway health    # 健康信息
openclaw doctor            # 一键健康检查 + 自动修复
openclaw status            # 会话健康 + 最近联系人
openclaw logs              # 实时日志

改完配置后必须 openclaw gateway restart 让改动生效。

五、配置详解（openclaw.json 实战）

完整 openclaw.json 核心结构（基于 2026.4.x 版本）：

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
{
  "meta": {
    "lastTouchedVersion": "2026.4.14",
    "lastTouchedAt": "2026-04-15T03:09:21.569Z"
  },
  "auth": {
    "profiles": {
      "anthropic:cn": {
        "provider": "anthropic",
        "mode": "api_key"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "anthropic": {
        "baseUrl": "https://api.anthropic.com",
        "api": "anthropic-messages",
        "authHeader": true,
        "models": [
          {
            "id": "claude-opus-4-6",
            "contextWindow": 204800,
            "maxTokens": 131072
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-opus-4-6" },
      "workspace": "/root/.openclaw/workspace",
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4,
      "subagents": { "maxConcurrent": 8 },
      "memorySearch": { "provider": "ollama" },
      "thinkingDefault": "high"
    },
    "list": [
      {
        "id": "writer",
        "workspace": "/root/.openclaw/workspace-writer",
        "identity": { "name": "维特", "emoji": "👍" }
      },
      {
        "id": "coding",
        "workspace": "/root/.openclaw/workspace-coding",
        "identity": { "name": "扣定", "emoji": "✌️" }
      }
    ]
  },
  "bindings": [
    { "agentId": "main", "match": { "channel": "feishu", "accountId": "default" } },
    { "agentId": "main", "match": { "channel": "dingtalk", "accountId": "default" } }
  ],
  "session": {
    "dmScope": "per-channel-peer"
  },
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "boot-md": { "enabled": true },
        "bootstrap-extra-files": { "enabled": true },
        "command-logger": { "enabled": true },
        "session-memory": { "enabled": true }
      }
    }
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "<FEISHU_APP_ID>",
      "appSecret": "<FEISHU_APP_SECRET>",
      "connectionMode": "websocket",
      "domain": "feishu",
      "groupPolicy": "open"
    },
    "dingtalk": {
      "enabled": true,
      "clientId": "<DINGTALK_CLIENT_ID>",
      "clientSecret": "<DINGTALK_CLIENT_SECRET>",
      "messageType": "card",
      "cardStreamingMode": "all"
    },
    "discord": {
      "enabled": true,
      "token": "<DISCORD_BOT_TOKEN>",
      "groupPolicy": "open"
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "<GATEWAY_TOKEN>"
    },
    "http": {
      "endpoints": {
        "chatCompletions": { "enabled": true }
      }
    }
  },
  "plugins": {
    "enabled": true,
    "allow": ["feishu", "dingtalk", "discord"]
  }
}

5.1 关键配置项

字段	推荐值	说明
`session.dmScope`	`per-channel-peer`	按"渠道 + 发送者"隔离私聊
`agents.defaults.thinkingDefault`	`high`	默认开启深度思考
`agents.defaults.compaction.mode`	`safeguard`	自动压缩上下文（保关键）
`channels.*.groupPolicy`	`open` / `allowlist`	群消息策略
`gateway.auth.mode`	`token`	网关鉴权用 token
`gateway.bind`	`loopback`	仅本机访问

5.2 `dmScope` 4 种模式对比

参数	含义	适用场景
`main`	所有私聊共用主会话	单用户、强调跨渠道连续性
`per-peer`	按发送者 ID 隔离	多用户收件箱
`per-channel-peer`	按渠道 + 发送者隔离	多渠道多用户
`per-account-channel-peer`	按账号 + 渠道 + 发送者	多账号多机器人

dmScope 只解决"私聊历史会不会串"，不决定消息最终进入哪个 Agent。后者由 bindings 路由。

六、SOUL.md：Agent 的人格化

SOUL.md 是 OpenClaw 的灵魂——给 Agent 设定语气、风格、性格：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# SOUL.md

## 语气
- 直接、严谨、不废话
- 涉及技术问题，给方案 + 代码 + 风险评估
- 涉及生活问题，给数据 + 行动建议

## 风格
- 中文优先，技术术语保留英文
- 回答分点、结构化
- 关键结论加粗

## 边界
- 不回答政治敏感问题
- 不提供医疗 / 法律最终建议
- 不主动询问隐私信息

每个 Agent 可以有独立的 SOUL.md，实现"一鱼多吃"——同一个 OpenClaw 实例，挂不同 SOUL.md 就是不同"人"。

七、通道管理

7.1 飞书接入

飞书开放平台创建自建应用，获取 App ID 和 App Secret：

1
2
3
4
5
6
openclaw channels add
# 选择 Feishu/Lark
# 输入 App Secret / App ID
# 选择连接模式：WebSocket
# 域：Feishu (feishu.cn) - China
# 群策略：Open - respond in all groups (requires mention)

启用权限（最小集）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:send_as_bot",
      "im:message.group_at_msg:readonly",
      "im:chat.access_event.bot_p2p_chat:read",
      "contact:user.employee_id:readonly"
    ],
    "user": ["im:message", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

飞书 Bot 首次启动会发"配对码"，需在 OpenClaw 端批准：

1
openclaw pairing approve feishu <PAIRING_CODE>

7.2 钉钉接入

钉钉开放平台创建企业内部应用：

1
2
3
4
5
6
openclaw channels add
# 选择 DingTalk
# 输入 clientId / clientSecret
# 启用 AI 互动卡片模式
# 卡片流式模式：All
# 私聊/群消息策略：Open

启用"AI 互动卡片"需要在钉钉开发者后台创建 AI 卡片模板（https://open-dev.dingtalk.com/fe/card），复制 Template ID 填入。

7.3 企业微信接入

1
2
3
4
5
openclaw plugins install @sunnoy/wecom
openclaw plugins update wecom
openclaw channels add
# 选择 WeCom
# 输入 AgentId / Secret / 企业ID

企业微信 Bot 首次使用需要"配对码"流程。

7.4 Discord 接入（推荐开发自用）

Discord Developer Portal 创建 Bot：

创建 Application
Bot → Reset Token → 复制
Privileged Gateway Intents 全开（Message Content Intent 必须）
OAuth2 → URL Generator → scopes: bot + applications.commands
邀请到服务器

1
2
3
openclaw channels add
# 选择 Discord
# 输入 Bot Token

八、ClawHub 技能市场

ClawHub 是 OpenClaw 的"技能商店"——第三方 AI 技能包。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# 推荐方式（npx 无需全局安装）
npx clawhub@latest --version

# 全局安装
npm install -g clawhub

# 登录
clawhub login

# 搜索
clawhub search "postgres backups"

# 安装
clawhub install my-skill-pack

# 批量更新
clawhub update --all

九、插件管理

1
2
3
4
5
openclaw plugins list                          # 查看已加载
openclaw plugins install @openclaw/voice-call  # 装官方插件
openclaw plugins install @sunnoy/wecom         # 装企微插件
openclaw channels add                          # 装新通道
openclaw gateway restart                       # 重启生效

十、多 Agent + Discord 频道路由（高级模式）

OpenClaw 的杀手锏是用 Discord 频道做 Agent 路由——每个 Agent 对应一个频道：

1
2
3
4
5
6
7
8
| 频道 ID | 频道名 | Agent | 用途 |
|---|---|---|---|
| <YOUR_DISCORD_SERVER_ID> | 服务器 | - | 容器 |
| <YOUR_DISCORD_WRITER_CHANNEL_ID> | 写作 | writer | 写文章 |
| <YOUR_DISCORD_CODING_CHANNEL_ID> | 编程 | coding | 写代码 |
| <YOUR_DISCORD_FITNESS_CHANNEL_ID> | 强身 | jiaolian | 减肥教练 |
| <YOUR_DISCORD_LEARNING_CHANNEL_ID> | 学习 | main | 主代理 |
| <YOUR_DISCORD_PERSONAL_CHANNEL_ID> | 个人 | main | 个人事务 |

配置 3 件事：

定义 Agent——每个 Agent 一个 workspace，放不同 SOUL.md
开启 Discord——requireMention: false（自用免 @）
写 bindings——频道 ID → Agent 路由规则

1
2
3
4
5
6
7
8
{
  "bindings": [
    { "agentId": "main", "match": { "channel": "feishu" } },
    { "agentId": "main", "match": { "channel": "dingtalk" } },
    { "agentId": "writer", "match": { "channel": "discord", "peer": { "kind": "channel", "id": "<YOUR_DISCORD_WRITER_CHANNEL_ID>" } } },
    { "agentId": "coding", "match": { "channel": "discord", "peer": { "kind": "channel", "id": "<YOUR_DISCORD_CODING_CHANNEL_ID>" } } }
  ]
}

10.1 频道 Topic = AI 行为

Discord 频道的"topic"是频道名下面的小字——OpenClaw 会把它读进来当作这个频道的上下文提示。

1
2
3
频道 -减肥 的 topic：
"你是一个严格的健身教练，回复风格直接、不废话、数据驱动。
用户说吃了什么就帮他算热量，不要安慰，不要鼓励，直接说超没超。"

10.2 线程 = 任务隔离

频道解决了"谁干什么"，但同一个频道里任务还是会打架——两个任务的上下文会污染。

Discord 线程 = 频道的子房间，OpenClaw 把每个线程当独立 session：

1
2
3
4
5
6
7
8
"channels": {
  "discord": {
    "<写作频道ID>": {
      "requireMention": false,
      "autoThread": true
    }
  }
}

autoThread: true 后，每次主频道发消息，Bot 自动创建线程回复。主频道只剩线程标题（像目录），任务上下文完全隔离。

两层隔离模式：

频道做"职能分层"——写作、编程、减肥、个人，各管各的
线程做"任务分层"——每篇文章、每个项目独立上下文

十一、Exec Approvals（命令执行审批）

Agent 执行 shell 命令前可弹按钮让用户确认：

1
2
3
4
5
6
7
8
"channels": {
  "discord": {
    "execApprovals": {
      "enabled": true,
      "approvers": ["<YOUR_DISCORD_USER_ID>"]
    }
  }
}

自用场景建议开启——多一层保险，避免 Agent 误删文件。

十二、WSL2 安装坑

Windows 上 OpenClaw 经常遇到端口占用问题（Hyper-V 独占端口段）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# 查看保留端口段
netsh int ipv4 show excludedportrange protocol=tcp

# 重置 NAT
net stop winnat
net start winnat

# 用别的端口启动
openclaw gateway --port 17889 --verbose

# 永久改端口
openclaw config set gateway.port 17889
openclaw onboard --install-daemon --gateway-port 17889

十三、故障排除

症状	原因	解决
无 DM 回复	未配对	`openclaw pairing approve <channel> <code>`
群组中静默	未配置 mention 策略	`requireMention: false`
认证过期	token 失效	`openclaw models auth setup-token`
网关关闭	服务挂了	`openclaw doctor --deep`
内存 Bug	sqlite 索引损坏	重建内存索引
钉钉卡片失败	未配置 AI 卡片模板	钉钉卡片后台创建模板

十四、卸载

1
2
3
4
5
6
# 交互式
openclaw uninstall

# 非交互式（自动化 / CI）
openclaw uninstall --all --yes --non-interactive
npx -y openclaw uninstall --all --yes --non-interactive

十五、总结

OpenClaw 把"自托管 AI Agent 网关"这件事做对了——配置 / 记忆 / 工作区全部 git 化，多 Agent 路由用 SOUL.md 切人格，频道 → Agent 路由把 Discord 变成 AI 控制中心。

适合：

想完全控制 LLM 数据 / 记忆的团队
已经重度使用飞书 / 钉钉 / Discord 的组织
需要"一个 Bot 多个 Agent"的复杂场景

不适合：

只想简单问个问题（直接用 ChatGPT 更快）
没有 DevOps 能力维护（OpenClaw 配置文件复杂）

下一步：可参考 2025-12-15《Hermes Agent》了解 OpenClaw 生态的演进——Hermes 是 2025 年新出的"OpenClaw 平替 + 升级"，可平滑迁移。