Codex 接入飞书全栈指南：CLI、WebSocket、SDK 与机器人（Windows / macOS 保姆级完整教程）

适合读者：飞书开放平台接入 Codex 的用户。

运行环境：Windows 10/11（PowerShell）、macOS（Terminal / zsh）、Node.js LTS、飞书国内版、Codex CLI/SDK。

阅读约定：本文每个操作都会先给出 Windows 命令，紧跟一个「macOS」小节给出对应的 Mac 命令。两边命令等价，按你自己的系统选其一即可。

完成本文后，你可以：

  • 在 Codex 中说“读取我今天的飞书日程”，让 Codex 通过 lark-cli 获取数据；
  • 在飞书中直接给自己的机器人发消息，并由 Codex 生成回答；
  • 继续扩展飞书文档、知识库、表格和任务等能力。

一、先理解：其实有两种“接入”

很多教程会把两种需求混在一起，导致初学者越配置越乱。这里先明确两种模式的区别。

模式 A：Codex 访问飞书

入口仍然是 Codex App 或 Codex CLI。你可以对 Codex 说：

读取我今天的飞书日程，只读取，不修改。

执行链路：

Codex → lark-cli → 飞书 OpenAPI → 返回日程、文档或消息

适合场景：

  • 读取个人日历；
  • 搜索和总结飞书文档；
  • 操作多维表格、任务和消息；
  • 让 Codex 处理飞书中的工作数据。

模式 B：在飞书里直接聊天

入口是飞书客户端。你可以给机器人发送：

你好，你是谁？

执行链路：

飞书消息 → 本地 Node.js 机器人 → Codex SDK → 回答发送回飞书

适合场景：

  • 在飞书私聊中直接使用 Codex；
  • 为团队搭建内部智能助手；
  • 后续增加 /doc、/calendar、/task 等命令。

本文会同时介绍两种模式。建议严格按顺序操作：先完成模式 A，再完成模式 B。

二、准备工作

2.1 需要准备什么

  • 一台 Windows 电脑 或 一台 macOS 电脑（macOS 12 Monterey 及以上更省心）；
  • 一个可正常使用的飞书账号；
  • 能进入飞书开放平台开发者后台；
  • 可用的 ChatGPT/Codex 账号；
  • 能访问飞书和 OpenAI 的网络；
  • 约 30～60 分钟。

2.2 安装 Node.js（Windows）

进入 Node.js 官方下载页面，选择 LTS 长期支持版安装。

安装完成后打开 PowerShell：

  1. 按键盘 Win 键；
  2. 搜索 PowerShell；
  3. 打开 Windows PowerShell；
  4. 执行以下命令：
node -v
npm -v

两条命令都能输出版本号，就说明安装成功。

如果提示“不是内部或外部命令”，请关闭 PowerShell 后重新打开。仍然无效时，重新安装 Node.js，并确认安装器已勾选将 Node.js 加入 PATH。

2.2 安装 Node.js（macOS）

macOS 有两种常见安装方式，任选其一。

方式 1：官方安装包（最简单）

进入 Node.js 官方下载页面，下载 macOS 的 .pkg 安装包，双击安装，一路下一步。安装器会自动把 Node.js 加入 PATH。

方式 2：用 Homebrew（推荐给后续要长期折腾的用户）

如果还没装 Homebrew，先在终端执行（建议先到 brew.sh 确认官方安装命令）：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

然后安装 Node.js：

brew install node

打开终端的方式：

  1. Command (⌘) + 空格 呼出聚焦搜索；
  2. 输入 Terminal 或 终端；
  3. 回车打开「终端 / Terminal」应用。

安装完成后验证：

node -v
npm -v

提示：用 Homebrew 装的 Node.js，全局命令会放在 Homebrew 目录（Apple Silicon 是 /opt/homebrew/bin，Intel 是 /usr/local/bin），这两个路径默认就在 PATH 里，后续装全局包通常不需要 sudo，比较省心。

2.3 关于 shell 的小知识

  • Windows 本文统一用 PowerShell；
  • macOS 默认 shell 是 zsh，终端里粘贴的命令以 bash / zsh 语法为准，Windows 用 powershell 语法；
  • 两边语义等价的命令，下文会成对给出，不必两套都执行。

三、模式 A：让 Codex 读取飞书日程和文档

3.1 安装飞书官方 CLI

在 PowerShell 中执行：

npx @larksuite/cli@latest install

第一次运行时可能看到：

Need to install the following packages:
@larksuite/cli@...
Ok to proceed? (y)

输入 y 并回车。安装完成后检查版本：

lark-cli --version

如果提示找不到 lark-cli，请关闭 PowerShell 后重新打开。也可以直接运行：

& "$env:APPDATA\npm\lark-cli.cmd" --version
macOS

在终端执行同样的命令：

npx @larksuite/cli@latest install

同样输入 y 确认安装。检查版本：

lark-cli --version

如果提示找不到 lark-cli，先确认全局命令目录是否在 PATH 中：

# 查看 npm 全局 bin 目录
npm config get prefix
# 通常是 /opt/homebrew（Apple Silicon）或 /usr/local（Intel），bin 子目录需在 PATH 中

也可以直接用完整路径调用：

"$(npm config get prefix)/bin/lark-cli" --version

技巧：如果你只是偶尔用一次，直接用 npx @larksuite/cli@latest --version 也可以，npx 会临时下载并运行。

3.2 配置飞书应用

执行：

lark-cli config init --new

终端会显示二维码或授权链接。打开链接，用飞书账号确认创建或配置应用。成功后会看到类似提示：

OK：应用配置成功！
macOS

命令完全一样：

lark-cli config init --new

终端里若显示二维码，可直接在飞书 App 里扫码；若是链接，Command (⌘) + 点击 终端里的链接即可在默认浏览器打开。

3.3 用户登录授权

执行：

lark-cli auth login --recommend

根据终端中的链接完成授权，然后检查：

lark-cli auth status

用户授权后，CLI 可以以你的飞书用户身份访问你有权查看的日历、文档和消息。

macOS

命令一致：

lark-cli auth login --recommend
lark-cli auth status

3.4 测试读取日历

运行：

lark-cli calendar +agenda

第一次运行可能提示缺少权限：

{
  "ok": false,
  "error": {
    "subtype": "missing_scope",
    "missing_scopes": [
      "calendar:calendar.event:read"
    ]
  }
}

这不是安装失败，而是缺少日历读取权限。根据错误中的 scope 补充授权：

lark-cli auth login --scope "calendar:calendar.event:read"

在浏览器中同意后，检查权限：

lark-cli auth check --scope "calendar:calendar.event:read"

成功结果应包含：

{
  "granted": ["calendar:calendar.event:read"],
  "missing": null,
  "ok": true
}

再次执行：

lark-cli calendar +agenda

如果返回：

{
  "ok": true,
  "data": []
}

说明命令执行成功，只是今天没有日程，并不是报错。

macOS

所有命令一字不差，把 powershell 换成 bash 即可：

lark-cli calendar +agenda
lark-cli auth login --scope "calendar:calendar.event:read"
lark-cli auth check --scope "calendar:calendar.event:read"

3.5 创建一个测试日程

打开飞书客户端：

  1. 点击左侧“日历”；
  2. 点击今天尚未过去的时间段；
  3. 标题填写“Codex 测试日程”；
  4. 时间设置为 30 分钟；
  5. 保存。

回到 PowerShell（或终端），再次执行：

lark-cli calendar +agenda

这次应看到：

  • summary：日程标题；
  • start_time：开始时间；
  • end_time：结束时间；
  • count：日程数量。

至此，飞书 CLI 已经可以读取你的飞书数据。

3.6 以后如何申请其他权限

推荐按业务域申请授权：

# 日历
lark-cli auth login --domain calendar

# 文档
lark-cli auth login --domain docs

# 日历 + 文档 + 任务
lark-cli auth login --domain calendar,docs,task

查看当前状态：

lark-cli auth status

检查指定权限：

lark-cli auth check --scope "某个具体 scope"

遇到 missing_scope 时，应先查看错误中的 missing_scopes，不要为了省事一次开通所有权限。

macOS

命令相同，直接在终端执行即可。

四、让 Codex App 正常调用 lark-cli

4.1 为什么要选择一个空文件夹

Codex App 中的“项目”本质上是一个本地工作目录。即使你只是读取飞书日程，也建议新建一个空文件夹。

Windows 示例路径：

C:\Codex-Feishu

也可以放在桌面：

C:\Users\你的用户名\Desktop\Codex-Feishu

macOS 示例路径：

~/Codex-Feishu

也可以放在桌面：

~/Desktop/Codex-Feishu

在终端里创建并进入：

mkdir -p ~/Codex-Feishu
cd ~/Codex-Feishu

这个空文件夹不会存放你的飞书日程，它只是为 Codex 提供一个安全、隔离的运行目录。

4.2 在 Codex App 中选择项目

打开 Codex App，点击 Choose project，选择刚才创建的空文件夹。

4.3 设置审批方式

在输入框左下角找到“请求批准”下拉菜单。

  • 初次使用：选择“请求批准”；
  • 频繁执行低风险命令：可选择“替我审批”；
  • 不建议为了省事长期授予无限制系统权限。

4.4 使用完整路径调用 lark-cli（Windows）

把下面的内容发给 Codex：

请执行以下只读命令：

& "$env:APPDATA\npm\lark-cli.cmd" calendar +agenda

读取我今天的飞书日程，不创建、修改或删除任何内容。

使用完整路径有两个好处：

  • 避免 Codex 找不到命令别名；
  • 避免中文 Windows 用户名造成路径识别问题。

4.4 使用完整路径调用 lark-cli（macOS）

在 macOS 上，全局命令通常已在 PATH 中，可以直接让 Codex 调用：

请执行以下只读命令：

lark-cli calendar +agenda

读取我今天的飞书日程，不创建、修改或删除任何内容。

如果 Codex 报告找不到 lark-cli，改用完整路径：

请执行以下只读命令：

"$(npm config get prefix)/bin/lark-cli" calendar +agenda

读取我今天的飞书日程，不创建、修改或删除任何内容。

macOS 上用户名一般为英文，路径识别问题较少；但仍建议在不确定时使用完整路径，行为更可预测。

成功后，Codex 会读取并整理日程。以后可以直接说：

使用飞书 CLI 读取我明天的日程，按时间顺序整理，不要修改任何内容。

或者：

使用飞书 CLI 搜索我最近修改的飞书文档，只列标题和更新时间。

注意：“Codex 能访问飞书”不等于“飞书里已经有 Codex 机器人”。下一部分才是把 Codex 放进飞书聊天窗口。

五、模式 B：在飞书里创建 Codex 聊天机器人

本节操作几乎都在飞书开放平台网页后台完成，Windows 与 macOS 没有区别，因此只写一遍。

5.1 打开飞书开放平台

进入飞书开放平台开发者后台，打开刚才配置的自建应用。

5.2 添加机器人能力

在左侧进入：

应用能力 → 添加应用能力 → 机器人

添加成功后，左侧“机器人”会高亮，页面会出现机器人配置。

5.3 开通消息权限

进入：

开发配置 → 权限管理

至少需要以下权限：

im:message:send_as_bot

用途：允许机器人发送消息。

im:message.p2p_msg:readonly

用途：接收用户发给机器人的单聊消息。

如果需要在群聊中 @机器人，再添加：

im:message.group_at_msg:readonly

飞书后台的中文名称可能随版本调整，可直接搜索权限代码或关键词。部分后台会把权限合并为“获取与发送单聊、群组消息”等组合权限，以实际页面为准。

5.4 添加消息事件

进入：

开发配置 → 事件与回调

后续需要添加：

im.message.receive_v1

也就是“接收消息”事件。先不要急着保存长连接订阅方式，我们先在本机启动机器人程序。

5.5 设置可用范围

进入版本或应用发布配置，将可用范围设置为你自己。

个人测试时建议：

  • 仅包含你本人；
  • 关闭“允许机器人被添加到外部群”；
  • 关闭“允许外部用户与机器人单聊”。

六、先做一个回声机器人，验证飞书通道

为什么不直接接入 Codex？因为排错时需要把问题拆开：

  1. 飞书能否把消息推送到电脑；
  2. 电脑能否回复飞书；
  3. Codex 能否生成回答。

先做回声机器人，可以证明前两项正常。

6.1 创建项目文件夹（Windows）

例如在桌面新建：

Feishu-Codex-Bot

进入该文件夹，在资源管理器顶部地址栏输入：

powershell

回车后，PowerShell 会自动在当前文件夹打开。你会看到类似：

PS C:\Users\你的用户名\Desktop\Feishu-Codex-Bot>

6.1 创建项目文件夹（macOS）

在终端里：

mkdir -p ~/Desktop/Feishu-Codex-Bot
cd ~/Desktop/Feishu-Codex-Bot

也可以在 Finder 里进入桌面，新建文件夹后，右键文件夹选择“新建位于文件夹位置的终端窗口”（如没有该菜单项，可在「系统设置 → 键盘 → 快捷键 → 服务」里勾选「新建位于文件夹位置的终端标签页 / 窗口」）。

6.2 准备示例项目

项目结构如下：

sample-bot/
├─ package.json
├─ .env.example
├─ .gitignore
├─ start-bot.bat        # Windows 启动脚本
├─ start-bot.sh         # macOS/Linux 启动脚本
└─ src/
   └─ index.js

进入项目目录后安装依赖（Windows / macOS 命令相同）：

npm install

如果手头没有示例项目，也可以把附录 A 的提示词交给 Codex，让它在空文件夹中创建一个最小可运行的回声机器人（记得提示它同时生成 .bat 和 .sh 两个启动脚本）。

6.3 创建 .env（Windows）

执行：

Copy-Item .env.example .env
notepad .env

填写：

LARK_APP_ID=你的App ID
LARK_APP_SECRET=你的App Secret
ALLOWED_OPEN_ID=你的Open ID
CODEX_MODEL=
CODEX_TIMEOUT_MS=120000

App ID 和 App Secret 位于飞书开放平台的“凭证与基础信息”页面。

Open ID 可以通过以下命令查询：

lark-cli auth status

在输出中寻找以 ou_ 开头的用户 ID。

安全提醒：不要截图 .env。App Secret、Token 和 Codex 登录凭据都不应出现在博客、聊天、GitHub 或工单中。

确认 .gitignore 至少包含：

.env
node_modules/

6.3 创建 .env（macOS）

执行：

cp .env.example .env
nano .env      # 或用 open -e .env 调用“文本编辑”，也可用 code .env 调用 VS Code

填入与 Windows 完全相同的内容：

LARK_APP_ID=你的App ID
LARK_APP_SECRET=你的App Secret
ALLOWED_OPEN_ID=你的Open ID
CODEX_MODEL=
CODEX_TIMEOUT_MS=120000

查询 Open ID：

lark-cli auth status

在输出中寻找以 ou_ 开头的用户 ID。

6.4 先启动程序（Windows）

执行：

npm run dev

看到类似下面的提示，说明程序已经开始连接：

正在建立飞书 WebSocket 长连接。

这个窗口需要保持开启。

6.4 先启动程序（macOS）

命令完全一样：

npm run dev

保持终端窗口开启即可。若想让进程在关闭终端后继续运行，可使用 tmux 或 screen，但初期调试不建议，关掉终端就停正好便于排错。

6.5 回到飞书后台配置长连接

进入：

事件与回调 → 事件配置

选择：

使用长连接接收事件

保存，然后添加事件：

im.message.receive_v1

长连接模式的优点：

  • 本地电脑即可接收事件；
  • 不需要公网 IP；
  • 不需要域名；
  • 不需要内网穿透。

macOS 用户注意：长连接是出站连接，通常不会被系统防火墙拦截。若第一次连接失败，检查是否开启了阻断出站连接的第三方安全软件。

6.6 发布应用

进入：

版本管理与发布 → 创建版本

更新说明可以填写：

新增机器人消息接收与回复能力

提交并发布，确保可用范围包含你本人。

6.7 测试回声

在飞书中搜索机器人并发送：

你好

回声机器人应回复：

收到：你好

收到回复说明以下链路已经打通：

飞书消息
→ im.message.receive_v1
→ WebSocket 长连接
→ 本地 Node.js 程序
→ 飞书发送消息 API
→ 回复出现在飞书

七、把回声机器人升级为真正的 Codex 机器人

7.1 安装 Codex CLI（Windows）

在项目文件夹的 PowerShell 中执行：

npm install -g @openai/codex

然后运行：

codex

首次运行会提示登录。选择使用 ChatGPT 账号登录，并在浏览器中完成授权。出现 Codex 交互界面后，按 Ctrl + C 退出。

登录状态通常会缓存在本地，重启电脑后一般不需要重新登录。

7.1 安装 Codex CLI（macOS）

在项目目录的终端里执行：

npm install -g @openai/codex

然后运行：

codex

首次运行会提示登录。选择使用 ChatGPT 账号登录，浏览器会自动打开（如没有，复制终端里的链接到浏览器）。完成授权后，回到终端按 Ctrl + C 退出交互界面。

权限提示：用 Homebrew 安装的 Node.js，全局目录在你的用户可写范围内，不需要 sudo。若你是用官方 .pkg 安装的 Node.js，全局安装可能需要 sudo npm install -g ...；更推荐的做法是改用 Homebrew，或在 ~/.npmrc 里设置自定义 prefix，避免 sudo。

7.2 安装 Codex SDK

如果示例项目的 package.json 已包含 SDK，执行：

npm install

检查 JavaScript 语法：

npm run check
macOS

命令相同：

npm install
npm run check

7.3 核心代码说明

一个相对完整的机器人应实现：

  • 飞书 WebSocket 长连接；
  • im.message.receive_v1 事件监听；
  • ALLOWED_OPEN_ID 白名单；
  • 消息去重；
  • 忽略机器人自身消息；
  • 每个 chat_id 使用独立 Codex Thread；
  • /status 和 /clear 命令；
  • 长回答自动分段；
  • 同一会话串行处理；
  • Codex read-only 沙箱；
  • approvalPolicy: "never"；
  • 从 Codex 子进程环境中移除飞书密钥；
  • 错误信息脱敏。

最核心的 Codex 调用只有几行：

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread({
  workingDirectory: process.cwd(),
  skipGitRepoCheck: true,
  sandboxMode: "read-only",
  approvalPolicy: "never",
});

const turn = await thread.run("你好，你是谁？");
console.log(turn.finalResponse);

同一个 Thread 再次调用 run()，就可以延续对话上下文。

跨平台提示：process.cwd()、skipGitRepoCheck、sandboxMode、approvalPolicy 在 Windows 与 macOS 行为一致，无需区分系统。

7.4 为什么事件处理器不能一直等待 Codex

飞书长连接事件处理有时限。Codex 生成回答可能需要几十秒，如果在事件回调中一直等待 thread.run()，飞书可能认为处理超时并重新推送事件。

因此应采用类似下面的处理方式：

void enqueue(chatId, () => handleUserText(chatId, text));
return {};

处理逻辑是：

  1. 收到事件后立即登记去重；
  2. 把任务放入队列；
  3. 立刻结束事件处理；
  4. 在后台调用 Codex；
  5. 最后通过飞书发送消息接口回复。

这是避免重复回复和事件超时的关键。

7.5 启动机器人（Windows）

如果旧程序正在运行，先按 Ctrl + C，然后启动：

npm start

保持窗口开启。

7.5 启动机器人（macOS）

命令相同，在终端里：

npm start

保持终端窗口开启。

7.6 在飞书中测试

先发送：

/status

应看到类似回复：

飞书长连接正常；Codex SDK 已初始化。

再发送：

你好，你是谁？

正常情况下，机器人会先回复：

正在处理，请稍候……

随后返回 Codex 的回答。

可以继续测试上下文：

给我解释什么是地震反演。

等机器人回答后再发送：

用更简单的话再解释一遍。

如果机器人知道“再解释一遍”指的是上一条内容，就说明 Thread 连续对话正常。

清除上下文：

/clear

7.7 为什么回复比直接使用 ChatGPT 慢

当前链路比直接聊天多了几个环节：

飞书 → 本地机器人 → Codex CLI 子进程 → 模型推理 → 本地机器人 → 飞书

而且 Codex 是偏工程任务的 Agent，会进行更多上下文和工具准备。

提速建议：

  • 一次只发一条消息，等待回复后再发下一条；
  • 简短问题使用更轻量的模型；
  • 不要让同一个 chat_id 同时执行多个任务；
  • 保留“正在处理”的提示；
  • 设置超时；
  • 不需要文件分析时，保持只读并禁用额外工具。

八、可选增强：读取并分析飞书文档

8.1 先在终端中测试文档读取

先查看当前版本的命令帮助（Windows / macOS 通用）：

lark-cli docs +fetch --help

常见用法类似：

lark-cli docs +fetch --doc "飞书文档链接" --as user --format pretty

由于 CLI 更新较快，请以本机 --help 展示的参数为准。如果缺少权限，根据错误中的 missing_scopes 重新授权。

8.2 在飞书机器人中设计 /doc

理想用法：

/doc https://你的租户.feishu.cn/docx/xxxxx
请总结核心结论，并指出三处逻辑问题。

安全实现必须做到：

  • 只允许合法的飞书/Lark 域名；
  • 使用 execFile 或 spawn 调用 CLI；
  • 禁止把用户输入拼接成任意 shell 命令；
  • 只读，不更新原文档；
  • 不把完整文档写入日志；
  • 长文档分块总结；
  • 缺少权限时明确返回 scope；
  • 为读取和分析设置超时。

跨平台提示：execFile / spawn 在 Windows 上需要正确处理 .cmd 后缀（如 lark-cli.cmd）和路径带空格的情况；在 macOS 上 lark-cli 通常是无后缀的可执行脚本且位于 PATH 中。建议代码里通过 process.platform === 'win32' 判断，分别传不同的可执行文件名，避免在 Mac 上误调 .cmd。

8.3 可直接交给 Codex 的升级提示词

请在当前飞书 Codex 机器人中增加“读取飞书文档并分析”的功能。

要求：
1. 保留现有长连接、Codex Thread、白名单、去重、/status、/clear。
2. 支持 /doc <飞书文档链接> <分析要求>。
3. 普通消息包含飞书 docx/docs/wiki 链接时也自动识别。
4. 先实际运行 lark-cli docs +fetch --help，以本机版本真实参数为准。
5. Node.js 调用 lark-cli 必须使用 execFile 或 spawn，禁止 shell 拼接。
6. 仅允许合法飞书/Lark 文档域名，防止命令注入。
7. 跨平台：根据 process.platform 在 Windows 调用 lark-cli.cmd、在 macOS/Linux 调用 lark-cli，并正确处理带空格的路径。
8. 长文档先分块读取要点，再生成整体分析，不要只截取开头。
9. 缺权限时回复缺少的 scope。
10. 不输出正文到控制台，不输出 .env、Token、App Secret。
11. 完成后做语法检查，不启动程序。

九、电脑重启后如何恢复

正常情况下，不需要重新执行以下操作：

  • 安装 Node.js；
  • 安装 lark-cli；
  • 创建飞书应用；
  • 配置权限和事件；
  • 发布应用；
  • 填写 .env；
  • 登录 Codex。

9.1 每次开机后的启动步骤（Windows）

  1. 打开机器人项目文件夹；
  2. 在地址栏输入 powershell；
  3. 执行：
npm start
  1. 保持 PowerShell 窗口开启；
  2. 在飞书中发送：
/status

也可以双击示例项目中的：

start-bot.bat

9.1 每次开机后的启动步骤（macOS）

  1. 打开「终端」；
  2. 进入项目目录：
cd ~/Desktop/Feishu-Codex-Bot
  1. 执行：
npm start
  1. 保持终端窗口开启；
  2. 在飞书中发送 /status 验证。

也可以双击项目里的启动脚本 start-bot.sh（首次使用前需要赋予执行权限，仅一次）：

chmod +x start-bot.sh
# 以后双击，或在终端执行 ./start-bot.sh

如果 Finder 双击 .sh 打开的是文本编辑器，可右键 → 打开方式 → 终端；或在「终端」偏好设置里把 .sh 关联到终端。

9.2 如果 Codex 登录失效

执行：

codex

按提示重新登录。成功后按 Ctrl + C 退出，再运行：

npm start

macOS 同理：在终端运行 codex，完成登录后 Ctrl + C 退出，再 npm start。

9.3 如果机器人突然不回复

在运行窗口按 Ctrl + C，然后重新执行：

npm start

9.4 电脑休眠的影响

电脑关机、睡眠、休眠或断网时，本地 WebSocket 长连接会断开，机器人也会离线。

如果需要全天在线，应把项目部署到长期运行的主机或服务器。部署到公网服务器时，需要重新评估登录凭据、权限、日志和密钥存储方式，不要直接照搬个人电脑配置。

macOS 补充：Mac 默认合盖即睡眠，会断开长连接。可在「系统设置 → 电池 / 显示器」里调整睡眠策略，或使用 caffeinate -s 命令临时阻止休眠（仅调试期间建议，长期请部署到服务器）。注意：仅防止休眠不能解决断网，网络波动仍会重连。

附录：可直接复制给 Codex 的提示词

以下提示词已更新为跨平台版本，提示 Codex 同时考虑 Windows 与 macOS。

A. 让 Codex 创建回声机器人

请在当前空文件夹中创建一个最小可运行的飞书长连接回声机器人。

要求：
1. 使用 Node.js 和 JavaScript。
2. 使用官方 @larksuiteoapi/node-sdk。
3. 使用 WebSocket 长连接，不用 Webhook，不需要公网服务器。
4. 监听 im.message.receive_v1。
5. 只处理文本消息。
6. 收到私聊后回复“收到：用户原消息”。
7. 忽略机器人自身消息，防止循环。
8. 使用 message_id 去重。
9. 支持 ALLOWED_OPEN_ID 白名单。
10. 使用 dotenv 读取 LARK_APP_ID、LARK_APP_SECRET、ALLOWED_OPEN_ID。
11. 创建 package.json、src/index.js、.env.example、.gitignore、README.md。
12. 同时提供 Windows 的 start-bot.bat 和 macOS/Linux 的 start-bot.sh，.sh 需在说明里提示 chmod +x。
13. 不在日志中输出 App Secret、Token 或完整消息。
14. 自动 npm install 和语法检查。
15. 不读取或填写真实密钥，不启动程序。

B. 将回声机器人升级为 Codex

当前飞书回声机器人已经测试成功。

请升级为 Codex 智能机器人：
1. 安装并使用官方 @openai/codex-sdk。
2. 普通私聊文本提交给 Codex，最终回答回复到原聊天。
3. 每个 chat_id 维护独立 Thread。
4. 支持 /clear 与 /status。
5. 保留白名单、自身消息过滤、message_id 去重。
6. 长回答自动分段。
7. 同一 chat_id 串行处理，禁止上下文并发错乱。
8. 收到普通消息后立即回复“正在处理，请稍候……”。
9. 单次 Codex 调用设置 120 秒超时。
10. 使用 read-only 沙箱、approvalPolicy never、skipGitRepoCheck true。
11. Codex 子进程继承系统环境，但移除 LARK_APP_ID、LARK_APP_SECRET、ALLOWED_OPEN_ID。
12. 跨平台处理 Codex 子进程环境变量：Windows 保留 PATH、USERPROFILE、HOME、APPDATA、LOCALAPPDATA、TEMP、TMP、SYSTEMROOT、COMSPEC；macOS/Linux 保留 PATH、HOME、TMPDIR、USER、SHELL、LANG、LC_ALL。
13. 不输出 .env、Token、App Secret。
14. 完成后语法检查，不启动程序。

C. 排查“/status 正常，普通消息没反应”

飞书能够正常回复 /status，但普通消息调用 Codex 后没有响应。

请检查并修复：
1. thread.run() 前后记录脱敏日志。
2. 立即回复“正在处理，请稍候……”。
3. 使用 turn.finalResponse 作为最终文本。
4. Codex env 从 process.env 复制，只删除飞书密钥。
5. 跨平台保留必要环境变量：
   - Windows：PATH、USERPROFILE、HOME、APPDATA、LOCALAPPDATA、TEMP、TMP、SYSTEMROOT、COMSPEC。
   - macOS/Linux：PATH、HOME、TMPDIR、USER、SHELL、LANG、LC_ALL。
6. 增加 120 秒超时，超时必须回复用户。
7. 保留 read-only、approvalPolicy never、白名单、消息去重。
8. 事件回调快速返回，Codex 调用放到后台队列。
9. 完成后语法检查，不启动程序。

D. 跨平台路径与可执行文件处理（新增）

请把机器人代码中所有调用 lark-cli 的地方改为跨平台安全实现：
1. 通过 process.platform === 'win32' 判断系统。
2. Windows 下调用 lark-cli.cmd（或完整路径 $env:APPDATA\npm\lark-cli.cmd）。
3. macOS/Linux 下调用 lark-cli（优先 PATH，必要时用 $(npm config get prefix)/bin/lark-cli）。
4. 统一使用 execFile / spawn，禁止 shell: true 拼接命令。
5. 路径带空格或中文时使用引号包裹，且对 spawn 的参数以数组形式传入。
6. 保留只读、超时、白名单、去重等既有逻辑。
7. 完成后语法检查，不启动程序。

官方资料

结语

完成本文后，你得到的不只是一个“会聊天的飞书机器人”，而是一个可以继续扩展的本地 Agent 通道：

飞书负责入口与协作
Node.js 负责连接和权限边界
Codex 负责理解、推理与任务执行
lark-cli 负责读取和操作飞书数据

建议先保持私聊、白名单和只读。运行稳定后，再逐步增加文档读取、日历汇总、任务摘要和多维表格能力。不要一开始就开满权限，也不要把高权限机器人直接放入大群。

无论你用的是 Windows 还是 macOS，核心链路与安全原则是一致的：先把通道跑通、再用回声验证、最后再接入 Codex，分步排错最省心。

建议标签： Codex、飞书、WebSocket、Node.js、AI 机器人、Windows、macOS

Logo
DAMO开发者矩阵

DAMO开发者矩阵，由阿里巴巴达摩院和中国互联网协会联合发起，致力于探讨最前沿的技术趋势与应用成果，搭建高质量的交流与分享平台，推动技术创新与产业应用链接，围绕“人工智能与新型计算”构建开放共享的开发者生态。

更多推荐

cover

OpenClaw安装程序下载启动盘，TopClaw三分钟免费满血接飞书

avatar DAMO开发者矩阵
cover

人形机器人具身智能及其实现路线：PaLM-E在实物操作中的zero-shot学习（上）

avatar DAMO开发者矩阵
cover

【CVPR 2026】Motus：一个模型贯通理解、预测与控制｜从统一世界模型架构视角

avatar DAMO开发者矩阵