Feishu Group → Agent Binding
Route a Feishu group to a specific agent with isolated workspace.
Prerequisites
- - Agent must exist in
agents.list (create via openclaw agents add <id>) - Agent must have its own workspace (NOT shared with main)
- Gateway running
Steps
1. Ensure agent has independent workspace
CODEBLOCK0
If workspace is shared with main (~/.openclaw/workspace), create a dedicated one:
CODEBLOCK1
Write at minimum SOUL.md and AGENTS.md into the new workspace. Then update config:
CODEBLOCK2
2. Add group to channels.feishu.groups (optional but recommended)
CODEBLOCK3
3. Add binding with accountId (CRITICAL)
Must include accountId matching the Feishu account (usually "main"), otherwise the binding is silently ignored during route matching.
CODEBLOCK4
Or via CLI:
CODEBLOCK5
4. Clean up stale sessions
If the group was previously handled by another agent, delete its old session to avoid cache issues:
CODEBLOCK6
5. Restart gateway
CODEBLOCK7
6. Verify
CODEBLOCK8
Pitfalls (learned the hard way)
- 1. Missing
accountId in binding: Binding without accountId defaults to matching account "default", not "main". The Feishu plugin passes its actual account ID (e.g. "main"), so the binding is never matched. Always set accountId explicitly.
- 2. Shared workspace: If multiple agents share the same workspace, they read the same SOUL.md/BOOTSTRAP.md and confuse identities. Always use separate workspaces.
- 3. Stale sessions: Old sessions cached under a different agent persist after binding changes. Delete them manually.
- 4. Gateway restart required: Binding changes need a full gateway restart to take effect.
- 5.
openclaw agents bind CLI pitfall: The CLI command openclaw agents bind --agent X --bind feishu:<chat_id> sets accountId=<chat_id> instead of peer.id=<chat_id>. This is wrong for group routing. Use config set --json bindings directly instead.
- 6. Binding order matters: When multiple bindings match, first one wins. Put specific peer bindings before account-level bindings.
飞书群组 → 智能体绑定
将飞书群组路由到具有独立工作空间的特定智能体。
前置条件
- - 智能体必须存在于 agents.list 中（通过 openclaw agents add 创建）
- 智能体必须拥有自己的工作空间（不与主空间共享）
- 网关正在运行
步骤
1. 确保智能体拥有独立工作空间
bash
检查当前配置
openclaw config get agents.list | jq .[] | select(.id==
) | .workspace
如果工作空间与主空间共享（~/.openclaw/workspace），请创建一个专用工作空间：
bash
mkdir -p ~/.openclaw/workspace-/memory
至少将 SOUL.md 和 AGENTS.md 写入新工作空间。然后更新配置：
python
import json
with open(os.path.expanduser(~/.openclaw/openclaw.json)) as f:
c = json.load(f)
for a in c[agents][list]:
if a[id] == :
a[workspace] = os.path.expanduser(f~/.openclaw/workspace-)
break
with open(os.path.expanduser(~/.openclaw/openclaw.json), w) as f:
json.dump(c, f, indent=2, ensure_ascii=False)
2. 将群组添加到 channels.feishu.groups（可选但推荐）
python
添加群组配置
fs_groups = c[channels][feishu].setdefault(groups, {})
fsgroups[id>] = {requireMention: False}
3. 使用 accountId 添加绑定（关键）
必须包含与飞书账号匹配的 accountId（通常为 main），否则绑定在路由匹配时会被静默忽略。
python
bindings = c.get(bindings, [])
bindings.append({
agentId: ,
match: {
channel: feishu,
peer: {kind: group, id: },
accountId: account
id> # 例如 main
}
})
c[bindings] = bindings
或通过命令行：
bash
先获取现有绑定
openclaw config get bindings
设置所有绑定（现有 + 新增）
openclaw config set --json bindings [...existing..., {agentId:,match:{channel:feishu,peer:{kind:group,id:},accountId:main}}]
4. 清理过期会话
如果该群组之前由其他智能体处理，请删除其旧会话以避免缓存问题：
bash
查找旧会话
openclaw sessions --all-agents --json | grep
从旧智能体的会话存储中删除
python3 -c
import json, glob
for f in glob.glob(os.path.expanduser(~/.openclaw/agents/*/sessions/sessions.json)):
with open(f) as fh: d = json.load(fh)
keys = [k for k in d if in k]
if keys:
for k in keys: del d[k]
with open(f,w) as fh: json.dump(d, fh)
print(f已清理 {f}: {keys})
5. 重启网关
bash
openclaw gateway restart
6. 验证
bash
检查绑定
openclaw config get bindings
检查会话是否命中正确的智能体
openclaw status | grep
应显示 agent::feishu:group:
常见陷阱（经验教训）
- 1. 绑定中缺少 accountId：没有 accountId 的绑定默认匹配账号 default，而非 main。飞书插件传递的是实际账号 ID（例如 main），因此绑定永远不会被匹配。始终显式设置 accountId。
- 2. 共享工作空间：如果多个智能体共享同一工作空间，它们会读取相同的 SOUL.md/BOOTSTRAP.md 并混淆身份。始终使用独立工作空间。
- 3. 过期会话：旧会话缓存在不同智能体下，绑定更改后仍然存在。需手动删除。
- 4. 需要重启网关：绑定更改需要完全重启网关才能生效。
- 5. openclaw agents bind 命令行陷阱：CLI 命令 openclaw agents bind --agent X --bind feishu:id> 会将 accountId 设置为 id> 而非 peer.id=。这对于群组路由是错误的。请直接使用 config set --json bindings。
- 6. 绑定顺序很重要：当多个绑定匹配时，第一个优先。将特定的对等绑定放在账号级绑定之前。
