OpenClaw飞书渠道ACP功能启动的实现方式步骤实用指南

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“OpenClaw飞书渠道ACP功能启动的实现方法步骤”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

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

一、理解 ACP 与飞书渠道的关系

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

结合项目来看，飞书渠道（无论是官方插件还是内置插件）只负责消息的收发和路由，ACP 功能在顶层 acp 设置块中独立启用。只要飞书渠道正常连接，你就能够在飞书对话中借助 /acp 命令驱动 Codex、Claude、Gemini 等外部 Harness，就像在 Discord 或 T@elegrimm 中一样。

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

二、前置条件：确保飞书渠道已正常接入

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

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

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

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

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

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

{
  "scopes": {
    "tenant": [
      "im:ch@t",
      "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:[email protected]_event.bot_p2p_ch@t:read"
    ]
  }
}

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

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

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

三、启用 ACP 功能

飞书渠道就绪后，在 ~/.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 控制操作权限范围：

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

建议根据实际场景选择设置：

# 方案一：完全开放权限（适合受信任的个人开发环境）
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 会话

落到代码里，设置完成后，打开飞书，找到你的机器人，直接发送 /acp 命令即可开始采用。

5.1 基础启动流程

# 启动一个持久化 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 处理这个任务”

5.2 一次性任务 vs 持久化会话

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

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

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

5.3 恢复历史会话

理解这一步时，若之前的 ACP 会话因网关重启或超时中断，能够借助 resumeSessionId 续接，完整保留上下文：

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

六、完整命令速查

七、沙箱兼容性注意事项

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（国际版）用户的特殊说明

从实现思路看，Lark 国际版不兼容 WebSocket 长连接，需改用 Webhook 模式，设置上有所不同：

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

理解这一步时，Webhook 模式需将本地端口暴露到公网，建议采用 Cloudflare Tunnel（免费且与 、V2Ray 等代理工具完全兼容）：

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

将生成的公网 URL（如 （链接已移除））填入 Lark 开发者后台的 Request URL 即可。ACP 功能的设置与采用方式与飞书国内版完全相同，无需额外适配。

九、常用问题排查

十、总结

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

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

落到代码里，总的来说，OpenClaw飞书ACP启动适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。