OpenClaw飞书渠道ACP功能启动的实现步骤

目录

• 一、理解 ACP 与飞书渠道的关系
• 二、前置条件：确保飞书渠道已正常接入
• 三、启用 ACP 功能
• 四、权限配置（重要，不配必踩坑）
• 五、在飞书中启动 ACP 会话
• 5.1 基础启动流程
• 5.2 一次性任务 vs 持久化会话
• 5.3 恢复历史会话
• 六、完整命令速查
• 七、沙箱兼容性注意事项
• 八、Lark（国际版）用户的特殊说明
• 九、常见问题排查
• 十、总结

在完成飞书渠道的基础接入之后，很多用户希望进一步在飞书对话中调用 Codex、Claude Code、Gemini CLI 等外部编程工具。OpenClaw 的 ACP（Agent Client Protocol）正是为此而生。本文将结合飞书渠道的具体配置，完整讲解如何在飞书环境中启动并使用 ACP 功能。

很多人第一次接触 ACP 时会有一个疑问：飞书插件文档里为什么没有专门的 ACP 章节？答案是：ACP 是 OpenClaw 的通用运行时功能，与具体渠道插件完全解耦。

飞书渠道（无论是官方插件还是内置插件）只负责消息的收发和路由，ACP 功能在顶层 acp 配置块中独立启用。只要飞书渠道正常连接，你就可以在飞书对话中通过 /acp 命令驱动 Codex、Claude、Gemini 等外部 Harness，就像在 Discord 或 Telegram 中一样。

这种设计意味着：你不需要为飞书做任何 ACP 专属配置，只需确保飞书渠道已正常接入，再启用全局 ACP 即可。

在启用 ACP 之前，飞书渠道必须处于正常工作状态。以下是快速验证方法：

# 查看网关状态
openclaw gateway status
# 实时查看日志，确认飞书连接正常
openclaw logs --follow

日志中出现 feishu ws connected 或 feishu provider ready 即表示飞书渠道连接成功。

如果飞书还未接入，需要先完成以下步骤：

第一步：创建飞书自建应用并开启机器人能力，在飞书开放平台创建企业自建应用，进入「应用能力 > 机器人」开启机器人功能。

第二步：配置权限，在权限管理中批量导入以下 JSON（涵盖消息、文档、文件等所有必要权限）：

{
  "scopes": {
    "tenant": [
      "im:chat",
      "im:message",
      "im:message.p2p_msg:readonly",
      "im:message.group_msg",
      "im:message:send_as_bot",
      "im:message:readonly",
      "im:resource",
      "docs:document.content:read",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

第三步：配置事件订阅，在「事件与回调 > 事件配置」中选择「使用长连接接收事件」（国内版飞书无需公网服务器），添加 im.message.receive_v1 事件。

第四步：在 OpenClaw 中添加飞书渠道：

# OpenClaw ≥ 2026.2 已内置飞书插件，无需额外安装
openclaw channels add
# 选择 Feishu → 粘贴 App ID → 粘贴 App Secret
openclaw gateway restart

飞书渠道就绪后，在 ~/.openclaw/openclaw.json 中加入 ACP 全局配置：

{
  "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
    }
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "accounts": {
        "main": {
          "appId": "cli_xxxxxxxxx",
          "appSecret": "你的AppSecret"
        }
      }
    }
  }
}

然后安装 acpx 后端插件并重启网关：

# 安装 acpx 后端插件
openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true
# 重启网关使配置生效
openclaw gateway restart
# 验证后端健康状态
/acp doctor

ACP 会话运行在非交互模式下，没有 TTY 来响应文件写入或 shell 执行的权限提示。默认配置下，任何写入或执行操作都会因无法响应权限提示而直接报错崩溃（AcpRuntimeError: Permission prompt unavailable in non-interactive mode）。

acpx 插件提供两个关键配置项来解决这个问题：

permissionMode 控制操作权限范围：

值	行为
approve-all	自动批准所有文件写入和 shell 命令
approve-reads	仅自动批准读取（默认值，写入和执行会触发提示）
deny-all	拒绝所有权限提示

nonInteractivePermissions 控制无 TTY 时的处理方式：

值	行为
fail	以 AcpRuntimeError 中止会话（默认值）
deny	静默拒绝权限并继续执行（优雅降级）

推荐根据实际场景选择配置：

# 方案一：完全开放权限（适合受信任的个人开发环境）
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
# 方案二：保守策略，写入被静默拒绝而不崩溃（适合对权限有顾虑的场景）
openclaw config set plugins.entries.acpx.config.permissionMode approve-reads
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions deny
# 修改后必须重启网关
openclaw gateway restart

配置完成后，打开飞书，找到你的机器人，直接发送 /acp 命令即可开始使用。

# 启动一个持久化 Codex 会话，绑定到当前对话
/acp spawn codex --mode persistent --thread auto
# 查看当前会话状态
/acp status
# 按需调整运行时参数
/acp model anthropic/claude-opus-4-5
/acp permissions approve-all
/acp timeout 300
# 向运行中的会话发送引导指令（不替换上下文）
/acp steer 重点关注性能优化，继续
# 停止当前轮次（保留会话）
/acp cancel
# 关闭会话并解除绑定
/acp close

你也可以直接用自然语言，OpenClaw 会自动解析意图并路由到 ACP 运行时：

• “用 Codex 帮我看一下这个仓库里的失败测试”
• “用 Claude Code 做一次性代码审查并总结结果”
• “用 Gemini CLI 处理这个任务”

–mode 参数决定会话的生命周期：

• oneshot（一次性）：执行完任务后自动结束，适合单次代码生成、文件分析等场景。
• persistent（持久化）：会话保持活跃，后续消息继续路由到同一会话，适合需要多轮交互的编码任务。

–thread 参数决定线程绑定方式：

模式	行为
auto	在活跃线程中绑定该线程；在线程外则自动创建并绑定子线程（如果渠道支持）
here	要求必须在活跃线程中，否则失败
off	不绑定，会话以无绑定状态启动

如果之前的 ACP 会话因网关重启或超时中断，可以通过 resumeSessionId 续接，完整保留上下文：

# 先查看近期会话列表
/acp sessions
# 续接指定会话
# 在飞书中告诉机器人：
# "用 sessions_spawn 工具续接我之前的 Codex 会话，resumeSessionId 是 <session-id>"

命令	作用
/acp spawn codex –mode persistent –thread auto	启动持久化 Codex 会话并绑定线程
/acp spawn claude –mode oneshot	启动一次性 Claude Code 会话
/acp status	查看当前会话状态和运行时参数
/acp model <provider/model>	设置模型覆盖
/acp permissions <profile>	设置权限审批策略
/acp timeout <seconds>	设置运行超时
/acp cwd <path>	设置工作目录
/acp steer <message>	向运行中的会话发送引导指令
/acp cancel	取消当前轮次（保留会话）
/acp close	关闭会话并解除线程绑定
/acp sessions	列出近期 ACP 会话
/acp doctor	后端健康检查与修复建议
/acp reset-options	清除所有运行时覆盖参数

ACP 会话目前运行在宿主机运行时，不在 OpenClaw 沙箱内部。这带来一个重要约束：

如果你的飞书渠道对应的 Agent 配置了沙箱模式（sandbox.mode: "all"），则该 Agent 会话将无法启动 ACP，报错信息为：

Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host.
Use runtime="subagent" from sandboxed sessions.

解决方案：为需要使用 ACP 的 Agent 关闭沙箱，或从非沙箱会话中发起 ACP。如果需要沙箱隔离执行，请改用 runtime: "subagent"。

Lark 国际版不支持 WebSocket 长连接，需要改用 Webhook 模式，配置上有所不同：

{
  "channels": {
    "feishu": {
      "domain": "lark",
      "connectionMode": "webhook",
      "webhookPort": 3000,
      "webhookPath": "/feishu/events",
      "accounts": {
        "main": {
          "appId": "cli_xxxxxxxxx",
          "appSecret": "你的AppSecret"
        }
      }
    }
  }
}

Webhook 模式需要将本地端口暴露到公网，推荐使用 Cloudflare Tunnel（免费且与 Clash、V2Ray 等代理工具完全兼容）：

# 安装 cloudflared（macOS）
brew install cloudflared
# 暴露本地 3000 端口
cloudflared tunnel --url http://localhost:3000

将生成的公网 URL（如 https://xxx-yyy.trycloudflare.com/feishu/events）填入 Lark 开发者后台的 Request URL 即可。ACP 功能的配置与使用方式与飞书国内版完全相同，无需额外适配。

症状	可能原因	解决方法
/acp 命令无响应	ACP 未启用或 acpx 插件未安装	检查 acp.enabled=true，运行 /acp doctor
ACP agent "codex" is not allowed	Agent 不在白名单	更新 acp.allowedAgents 配置
AcpRuntimeError: Permission prompt unavailable	权限配置阻止写入/执行	设置 permissionMode=approve-all 或 nonInteractivePermissions=deny
ACP 会话无限挂起	Harness 进程结束但未上报完成状态	运行 ps aux | grep acpx 排查并手动终止残留进程
沙箱 Agent 无法启动 ACP	ACP 运行在宿主机，与沙箱不兼容	关闭该 Agent 的沙箱配置，或改用 runtime: "subagent"
飞书机器人无反应（与 ACP 无关）	事件订阅未配置或应用未发布	检查「事件与回调」是否添加 im.message.receive_v1 并发布新版本

OpenClaw 在飞书渠道中启用 ACP 功能的核心逻辑很简单：飞书渠道负责消息路由，ACP 负责外部 Harness 调度，两者独立配置、协同工作。只需确保飞书渠道正常接入，在顶层启用 ACP 并安装 acpx 插件，就可以在飞书对话中用自然语言或 /acp 命令驱动 Codex、Claude Code、Gemini CLI 等专业编程工具，实现真正的聊天驱动代码工作流。

对于国内用户来说，飞书的 WebSocket 长连接模式无需公网服务器，配置门槛极低，是将 ACP 能力落地到日常工作流中最便捷的渠道之一。

到此这篇关于OpenClaw飞书渠道ACP功能启动的实现步骤的文章就介绍到这了,更多相关OpenClaw飞书ACP启动内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！