OpenClaw 飞书 ACP 会话配置详解

林森见鹿2026-03-27 11:11

本文档详细介绍 OpenClaw 中飞书（Lark）通道的 ACP（Agent Client Protocol）会话配置，以及 ACP 协议的核心概念与架构设计。

一、什么是 ACP？

1.1 ACP 协议定位

ACP（Agent Client Protocol） 是一种标准化通信协议 ，用于规范代码编辑器/IDE 与 AI 编程 Agent 之间的通信。它由 agentclientprotocol.com 提出，定位类似于 LSP (Language Server Protocol)，但专注于 AI Agent 的集成场景。

核心使命：打破编辑器与 Agent 的厂商锁定，实现"任意编辑器 + 任意 Agent"的自由组合。

1.2 为什么需要 ACP？

当前 AI 编程工具生态存在严重的碎片化问题：

问题 具体表现 ACP 解决方案
集成开销大 每个编辑器要为每个 Agent 写定制集成代码 标准化协议，一次实现到处运行
兼容性受限 Agent 只能支持部分编辑器 支持 ACP 的 Agent 可在所有兼容编辑器工作
开发者锁定 选择某个 Agent 意味着被迫使用其指定界面 用户自由选择工具组合

1.3 OpenClaw 中的 ACP

在 OpenClaw 中，ACP 让你能够在飞书会话 中直接调用外部编程 AI 工具（如 Claude Code、Codex 等）完成编程任务。OpenClaw 作为 ACP 的 Client 端，负责：

  • 接收飞书用户消息

  • 通过 ACP 协议与外部 Agent 通信

  • 将 Agent 的执行结果返回飞书

1.4 支持的 ACP 工具

工具 说明 厂商
pi Anthropic Pi Anthropic
claude Claude Code Anthropic
codex OpenAI Codex OpenAI
opencode OpenCode OpenCode
gemini Google Gemini CLI Google
kimi Kimi CLI Moonshot AI

二、ACP 架构与通信模式

2.1 核心架构假设

ACP 基于编辑器中心化的设计理念：

用户主要待在编辑器（或 OpenClaw 飞书会话）内，需要调用外部 Agent 协助完成特定任务。

2.2 通信模式对比

ACP 协议支持两种运行模式，OpenClaw 飞书集成主要使用 远程模式：

模式 通信方式 适用场景 OpenClaw 支持
本地模式 JSON-RPC over stdio Agent 作为编辑器子进程，低延迟 ❌
远程模式 HTTP / WebSocket 云端 Agent、企业私有部署 ✅

2.3 与 MCP 的关系

协议 定位 通信方向 与 ACP 关系
LSP 语言服务器 ↔ 编辑器 服务端 → 客户端 ACP 的灵感来源
MCP AI 模型 ↔ 上下文源 双向 ACP 复用其 JSON 数据格式
ACP AI Agent ↔ 编辑器/Client Agent → Client 本文主角，专注编程 Agent 交互

关键区别：

  • MCP 解决"AI 如何获取上下文"（数据层）

  • ACP 解决"Agent 如何与编辑器交互"（交互层）

2.4 数据格式规范

ACP 协议规范定义以下内容格式：

元素 格式 说明
用户可读文本 Markdown 足够灵活，无需编辑器支持 HTML
代码变更 Unified Diff 标准化代码差异展示
结构化数据 JSON 与 MCP 兼容的数据交换
协议传输 JSON-RPC / HTTP 本地用 stdio，远程用 HTTP/WebSocket

三、飞书 ACP 支持的场景

飞书支持以下 ACP 场景：

场景 说明 会话隔离
私信 DM 用户与机器人的一对一对话中启动 ACP 每个用户独立会话
群组话题 飞书群中的话题（thread）会话中启动 ACP 每个话题独立会话

注意 ：飞书 ACP 由文本命令驱动，没有原生斜杠命令菜单，需使用 /acp ... 消息格式。

四、两种使用方式

方式一：持久化 ACP 绑定（静态配置）

通过配置文件将飞书私信或话题会话固定绑定到持久化 ACP 会话。适合长期协作场景。

4.1 Agent 定义

json

复制代码 
{
  "agents": {
    "list": [
      {
        "id": "codex",
        "runtime": {
          "type": "acp",
          "acp": {
            "agent": "codex",
            "backend": "acpx",
            "mode": "persistent",
            "cwd": "/workspace/openclaw"
          }
        }
      }
    ]
  }
}

参数说明：

参数 说明 默认值
runtime.type 运行时类型，固定为 acp -
runtime.acp.agent ACP 工具 ID（如 codex/claude） -
runtime.acp.backend 后端插件名称 acpx
runtime.acp.mode 会话模式：persistent（持久化）或 oneshot（一次性） persistent
runtime.acp.cwd Agent 工作目录 -
4.2 绑定配置

json

复制代码 
{
  "bindings": [
    // 绑定私信到 ACP 会话
    {
      "type": "acp",
      "agentId": "codex",
      "match": {
        "channel": "feishu",
        "accountId": "default",
        "peer": { "kind": "direct", "id": "ou_1234567890" }
      }
    },
    // 绑定群组话题到 ACP 会话
    {
      "type": "acp",
      "agentId": "codex",
      "match": {
        "channel": "feishu",
        "accountId": "default",
        "peer": { "kind": "group", "id": "oc_group_chat:topic:om_topic_root" }
      },
      "acp": { "label": "codex-feishu-topic" }
    }
  ]
}

绑定参数说明：

参数 说明
type 固定为 "acp"，标记持久化 ACP 绑定
agentId 拥有此绑定的 OpenClaw Agent ID
match.channel 固定为 "feishu"
match.accountId 飞书账号 ID
match.peer.kind "direct"（私信）或 "group"（话题）
match.peer.id 用户 open_id 或群组话题 ID
acp.mode 覆盖 Agent 默认的 mode
acp.label 会话标签名，便于识别和管理
acp.cwd 覆盖默认的工作目录
4.3 完整配置示例

json

复制代码 
{
  "agents": {
    "list": [
      {
        "id": "codex",
        "runtime": {
          "type": "acp",
          "acp": {
            "agent": "codex",
            "backend": "acpx",
            "mode": "persistent",
            "cwd": "/workspace/openclaw"
          }
        }
      },
      {
        "id": "claude",
        "runtime": {
          "type": "acp",
          "acp": {
            "agent": "claude",
            "backend": "acpx",
            "mode": "persistent",
            "cwd": "/workspace/ai-projects"
          }
        }
      }
    ]
  },
  "bindings": [
    {
      "type": "acp",
      "agentId": "codex",
      "match": {
        "channel": "feishu",
        "accountId": "default",
        "peer": { "kind": "direct", "id": "ou_1234567890" }
      }
    },
    {
      "type": "acp",
      "agentId": "claude",
      "match": {
        "channel": "feishu",
        "accountId": "default",
        "peer": { "kind": "group", "id": "oc_group_topic:topic:om_xxx" }
      },
      "acp": { "label": "claude-topic" }
    }
  ]
}

方式二：动态生成（/acp spawn）

在飞书私信或话题会话中，直接发送命令动态启动 ACP 会话。适合临时任务场景。

5.1 基础命令

text

复制代码 
/acp spawn codex --thread here
5.2 命令参数详解
参数 说明 示例
<agent> ACP 工具类型 codex, claude, pi, opencode, gemini, kimi
--thread here 绑定到当前话题（私信或话题会话可用） --thread here
--thread auto 自动选择是否绑定话题 --thread auto
--thread off 不绑定话题（独立会话） --thread off
--mode persistent 创建持久化会话（长期保持） --mode persistent
--mode oneshot 创建一次性会话（执行完即销毁） --mode oneshot
--cwd /path 指定 Agent 工作目录 --cwd /workspace/project
--label <name> 为会话设置标签名 --label bugfix-session
5.3 常用命令示例

text

复制代码 
# 创建持久化 ACP 会话并绑定到当前话题
/acp spawn codex --mode persistent --thread here

# 创建一次性 ACP 会话（适合单次任务）
/acp spawn codex --mode oneshot --thread off

# 指定工作目录并创建会话
/acp spawn codex --cwd /workspace/project --thread here --label project-a

# 使用 Claude 处理复杂重构任务
/acp spawn claude --mode persistent --cwd /workspace/legacy-code --thread here

六、ACP 命令速查表

命令 功能 使用场景
/acp spawn 创建新的 ACP 会话 启动 Agent 处理任务
/acp cancel 取消当前执行中的任务 任务卡住或需要中断
/acp steer 发送 steering 指令调整行为 实时调整 Agent 策略
/acp close 关闭会话并解除绑定 结束协作
/acp status 查看当前会话状态和运行时选项 排查问题
/acp set-mode 设置运行时模式（plan/act等） 切换 Agent 工作模式
/acp model 切换使用的 AI 模型 更换模型版本
/acp permissions 设置权限策略 调整安全级别
/acp timeout 设置任务超时时间（秒） 控制执行时长
/acp cwd 设置/切换工作目录 多项目协作
/acp sessions 列出最近的 ACP 会话 会话管理
/acp doctor 诊断 ACP 健康状态 故障排查
/acp install 打印 ACP 工具安装步骤 首次配置

七、会话路由与会话键

飞书 ACP 会话的会话键（Session Key）映射遵循 ACP 协议的会话隔离原则：

会话类型 Session Key 格式 说明
普通私信 agent:<agentId>:main 标准 OpenClaw 私信会话
群聊 agent:<agentId>:feishu:group:<chat_id> 标准 OpenClaw 群聊会话
群组话题 agent:<agentId>:feishu:group:<chat_id>:topic:<topicId> 话题级隔离
ACP 绑定后 agent:<agentId>:acp:<uuid> ACP 专用会话键

💡 设计原理：ACP 会话键的独立设计确保 Agent 状态与普通聊天会话完全隔离，符合 ACP 协议的编辑器-Agent 解耦理念。

八、开启 ACP 所需配置

8.1 全局 ACP 配置

json

复制代码 
{
  "acp": {
    "enabled": true,
    "dispatch": { "enabled": true },
    "backend": "acpx",
    "defaultAgent": "codex",
    "allowedAgents": ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    "maxConcurrentSessions": 8,
    "stream": {
      "coalesceIdleMs": 300,
      "maxChunkChars": 1200
    },
    "runtime": {
      "ttlMinutes": 120
    }
  }
}

参数详解：

参数 说明 默认值
acp.enabled 全局启用 ACP 功能 true
acp.dispatch.enabled 允许从普通消息触发 ACP 分发 true
acp.backend 默认 ACP 后端插件 acpx
acp.defaultAgent 未指定时的默认 ACP 工具 -
acp.allowedAgents 允许使用的 ACP 工具白名单 -
acp.maxConcurrentSessions 最大并发 ACP 会话数 8
acp.stream.coalesceIdleMs 流式输出合并间隔（毫秒） 300
acp.stream.maxChunkChars 单条消息最大字符数 1200
acp.runtime.ttlMinutes 会话空闲超时时间（分钟） 120

8.2 插件配置

json

复制代码 
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        // 可选：覆盖默认权限配置
        "config": {
          "permissionMode": "approve-all",
          "nonInteractivePermissions": "fail"
        }
      }
    }
  }
}

8.3 安装插件

bash

复制代码 
# 安装 acpx 后端插件
openclaw plugins install acpx

# 验证安装
openclaw plugins list

九、权限配置（关键安全设置）

ACP 运行时无交互式 TTY，必须预先配置权限策略。

9.1 permissionMode

控制工具可以执行哪些操作而无需提示：

值 行为 适用场景
approve-all 自动批准所有文件写入和 shell 命令 可信环境、自动化流水线
approve-reads 自动批准读取；写入和执行需要提示 开发环境（但无 TTY 时会失败）
deny-all 拒绝所有权限提示 高度受限环境

9.2 nonInteractivePermissions

控制无交互式 TTY 时如何处理权限提示（飞书场景必配）：

值 行为 结果
fail 中止会话并报错（默认） 任务中断，错误提示
deny 静默拒绝并继续 任务继续，但部分操作被跳过

9.3 配置示例

json

复制代码 
{
  "plugins": {
    "entries": {
      "acpx": {
        "config": {
          "permissionMode": "approve-all",
          "nonInteractivePermissions": "fail"
        }
      }
    }
  }
}

或通过命令行快速配置：

bash

复制代码 
# 设置自动批准所有操作（适合自动化场景）
openclaw config set plugins.entries.acpx.config.permissionMode approve-all

# 设置权限被拒绝时失败（严格模式）
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

# 或设置为 deny 实现优雅降级
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions deny

⚠️ 重要提示 ：飞书 ACP 会话默认 nonInteractivePermissions: fail，任何写入或执行操作触发权限提示时会导致会话失败。生产环境建议设置为 approve-all 或 deny。

十、ACP 协议在 OpenClaw 中的实现特点

10.1 协议适配层

OpenClaw 作为 ACP Client，实现了以下适配：

ACP 协议元素 OpenClaw 飞书实现
Markdown 输出 自动转换为飞书富文本消息
Unified Diff 渲染为代码块或文件卡片
JSON-RPC 传输 通过 acpx 插件转换为 HTTP API 调用
会话状态管理 映射到飞书会话键系统
流式响应 支持打字机效果输出

10.2 与标准 ACP 的差异

标准 ACP OpenClaw 飞书适配 原因
编辑器为主界面 飞书聊天为主界面 场景转换
本地 stdio 优先 远程 HTTP 优先 飞书为远程场景
用户直接操作 文本命令驱动 聊天界面限制

十一、常见问题排查

错误信息 原因 解决方法
ACP runtime backend is not configured 缺少 acpx 插件 运行 openclaw plugins install acpx
ACP is disabled by policy ACP 全局禁用 设置 acp.enabled: true
ACP dispatch is disabled by policy 消息触发被禁用 设置 acp.dispatch.enabled: true
ACP agent "<id>" is not allowed 工具不在白名单 添加到 acp.allowedAgents
Unable to resolve session target 会话目标解析失败 运行 /acp sessions 查看正确标识
--thread here requires an active thread 不在话题中使用 --thread here 创建话题或使用 --thread off
Permission prompt unavailable 权限被阻止且无 TTY 设置 permissionMode: approve-all
Sandboxed sessions cannot spawn ACP 沙盒环境限制 从非沙盒会话启动 ACP

十二、相关命令参考

bash

复制代码 
# 查看飞书配对列表（获取用户/群组 ID）
openclaw pairing list feishu

# 查看网关状态
openclaw gateway status

# 查看飞书通道健康状态
openclaw channels status --probe

# 查看实时日志（调试用）
openclaw logs --follow

# 查看 ACP 诊断信息
/acp doctor

# 查看所有配置
openclaw config get
相关推荐
Alter12302 小时前
华为吴辉：AI正在重构生产系统，“大增量时代”已经到来
人工智能·华为·重构
pp起床2 小时前
Part01：大语言模型设置
人工智能·语言模型·自然语言处理
昨夜见军贴06162 小时前
透析用水与消毒供应中心检测如何更可靠？AI审核与IACheck守住医疗安全底线
人工智能·安全
数据皮皮侠2 小时前
1095 《中国城市统计年鉴》面板数据整理
大数据·数据库·人工智能·算法·制造
cd_949217212 小时前
可信数字身份筑牢安全底座，护航“十五五”智慧医疗新生态
大数据·人工智能·物联网
无忧智库2 小时前
数字中国新引擎：产业经济大脑的全景式解构与深度洞察（PPT）
人工智能
. . . . .2 小时前
AI资源集
人工智能
小码农吗2 小时前
AI CAD应用场景实战分析
人工智能·cad·ai应用场景·图纸设计
热门推荐
012026年3月AI领域大事件：DeepSeek引领开源风暴02GitHub 镜像站点03围棋-html版本04Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南05班级宠物园部署指南06小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）07UV安装并设置国内源08OpenClaw 使用和管理 MCP 完全指南09【计算机一级WPSoffice】小黑课堂题库软件下载安装教程（2026年3月最新版）10PostgreSQL 超详细安装与使用教程：从入门到实战