1. 为什么 Windows 上接飞书总卡在“最后一步”Codex 接入飞书这件事真正难的不是写代码而是把 CLI、WebSocket 长连接、SDK 和机器人回调这几条链路串起来。我见过太多人卡在同一个地方lark-cli明明装好了Codex 里让它读日程却报missing_scope或者机器人/status能回普通消息发出去石沉大海。问题往往不在模型而在权限、事件订阅方式和本地进程的配合。这篇面向 Windows 10/11 的完整教程会把两种“接入”拆开讲清楚。模式 A 是让 Codex 通过飞书官方 CLI 读取你的日历、文档、任务入口在 Codex App 或 Codex CLI模式 B 是把 Codex 做成飞书里的聊天机器人入口在飞书客户端。两条链路共用一套凭证体系但排错思路完全不同。适合第一次接触 PowerShell、飞书开放平台和 Codex 的读者跟着做大约 30 到 60 分钟能跑通。需要提前说明的是本文所有模型调用都通过 TaoToken 统一 Key 走 API 通道这样你不需要在多个平台之间来回切换账号配置一次就能同时支撑 CLI 和 SDK 两种调用方式。下面从环境准备开始每一步都给可复制的命令和配置骨架。2. 前置准备Node.js、TaoToken 统一 Key 与飞书应用2.1 环境清单一台 Windows 电脑、一个可正常登录的飞书账号、能进入飞书开放平台开发者后台、一个 TaoToken 账号。网络能正常访问飞书开放平台即可。Node.js 建议装 LTS 长期支持版去官网下载页选 Windows Installer安装时确认勾选“Add to PATH”。装完打开 PowerShell执行node -v npm -v两条都能输出版本号就说明成功。如果提示“不是内部或外部命令”关掉 PowerShell 重开仍无效就重装 Node.js 并检查 PATH。2.2 拿 TaoToken 统一 Key登录 TaoToken 控制台在 API Keys 页面创建一个新 Key。这个 Key 会同时用于 Codex CLI 和 Codex SDK所以创建后先复制保存到本地密码管理器不要贴在聊天窗口或截图里。TaoToken 的 API 通道地址是https://taotoken.net/api兼容 OpenAI 风格的调用格式。Codex CLI 和 SDK 都支持通过环境变量指定 base URL 和 API Key所以后面配置里我们会把这两项写进环境变量而不是硬编码在代码里。如果你还没决定用哪种模型可以先在模型对话页面测一下响应速度和输出质量确认可用后再写进配置。长期做编码或 Agent 任务的话Coding Plan 的额度模型更适合高频调用具体可以在控制台里对比。2.3 飞书应用创建进入飞书开放平台开发者后台创建一个企业自建应用。拿到 App ID 和 App Secret 后先放着模式 A 和模式 B 都会用到。注意 App Secret 只显示一次丢了只能重置。3. 模式 A用 lark-cli 让 Codex 读取飞书数据3.1 安装飞书官方 CLI在 PowerShell 里执行npx larksuite/clilatest install第一次会提示是否安装输入y回车。装完检查lark-cli --version如果提示找不到命令关掉 PowerShell 重开或者用完整路径 $env:APPDATA\npm\lark-cli.cmd --version3.2 初始化应用配置与用户授权lark-cli config init --new终端会给出授权链接或二维码用飞书账号确认后完成应用配置。接着做用户登录授权lark-cli auth login --recommend lark-cli auth statusauth status里会出现ou_开头的用户 ID这个后面配机器人白名单要用到。3.3 测试读取日历并处理 missing_scopelark-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和ok: true。再跑一次lark-cli calendar agenda如果返回{ok: true, data: []}说明命令通了只是今天没日程。3.4 在 Codex 里调用 lark-cli新建一个空文件夹比如C:\Codex-Feishu在 Codex App 里选择它作为项目。空文件夹的作用是给 Codex 一个隔离的工作目录它不会存你的日程数据。把下面这段发给 Codex请执行以下只读命令 $env:APPDATA\npm\lark-cli.cmd calendar agenda 读取我今天的飞书日程不创建、修改或删除任何内容。用完整路径能避免 Codex 找不到命令别名也能绕开中文用户名导致的路径识别问题。审批方式初次建议选“请求批准”确认命令安全后再考虑放宽。4. 模式 B飞书机器人 WebSocket 长连接 Codex SDK4.1 配置飞书应用能力与权限在开放平台左侧进入“应用能力 → 添加应用能力 → 机器人”。然后到“开发配置 → 权限管理”至少开通权限代码用途im:message:send_as_bot机器人发送消息im:message.p2p_msg:readonly接收单聊消息im:message.group_at_msg:readonly群聊中 机器人可选再到“事件与回调”先添加im.message.receive_v1事件但订阅方式先别急着保存等本地程序跑起来再选长连接。4.2 项目骨架与 .env 配置建一个项目文件夹结构如下Feishu-Codex-Bot/ ├─ package.json ├─ .env ├─ .gitignore └─ src/ └─ index.js.env内容LARK_APP_ID你的AppID LARK_APP_SECRET你的AppSecret ALLOWED_OPEN_IDou_开头的用户ID OPENAI_API_KEY你的TaoTokenKey OPENAI_BASE_URLhttps://taotoken.net/api CODEX_MODEL CODEX_TIMEOUT_MS120000.gitignore至少包含.env node_modules/4.3 回声机器人验证通道先不接 Codex只做回声把飞书到本地的链路验证通。核心逻辑是监听im.message.receive_v1收到文本后原样回复。启动程序npm install npm run dev看到“正在建立飞书 WebSocket 长连接”后回到开放平台“事件与回调 → 事件配置”选择“使用长连接接收事件”保存并确认im.message.receive_v1已添加。然后创建版本并发布可用范围设为你自己。在飞书里给机器人发“你好”收到“收到你好”就说明这条链路全通了飞书消息 → 事件 → WebSocket → 本地 Node.js → 发送消息 API → 回复。4.4 升级为 Codex 机器人安装 Codex CLI 和 SDKnpm install -g openai/codex npm install openai/codex-sdk首次运行codex会提示登录按引导完成授权后Ctrl C退出。核心调用代码import { Codex } from openai/codex-sdk; const codex new Codex({ apiKey: process.env.OPENAI_API_KEY, baseURL: process.env.OPENAI_BASE_URL, }); 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()就能延续上下文。这里有两个关键设计一是事件回调必须快速返回不能一直awaitCodex否则飞书会判定超时并重推事件二是每个chat_id维护独立 Thread同一会话串行处理避免上下文错乱。void enqueue(chatId, () handleUserText(chatId, text)); return {};收到事件后立即登记去重、把任务放进队列、立刻结束事件处理后台再慢慢调 Codex最后通过发送消息接口回复。5. 连通性验证与成功结果启动机器人后在飞书里先发/status应看到“飞书长连接正常Codex SDK 已初始化”。再发“你好你是谁”机器人会先回“正在处理请稍候……”随后返回 Codex 的回答。测试连续上下文先发“给我解释什么是地震反演”等回答后再发“用更简单的话再解释一遍”。如果机器人理解“再解释一遍”指上一条内容说明 Thread 连续对话正常。发/clear可以清除上下文。回复比直接聊天慢是正常的链路多了飞书 → 本地机器人 → Codex 子进程 → 模型推理 → 本地机器人 → 飞书这几层。提速建议一次只发一条、简短问题用轻量模型、不要让同一chat_id并发多任务、保留“正在处理”提示并设置超时。6. 本篇常见错排查missing_scope反复出现永远先看错误里的missing_scopes按具体 scope 补授权不要盲目一次开满所有权限。按业务域授权更清晰比如lark-cli auth login --domain calendar,docs,task。/status正常但普通消息没反应多半是事件回调里直接await了 Codex 导致超时。检查是否用了后台队列、是否立即回复了“正在处理”、turn.finalResponse是否作为最终文本、Codex 子进程环境是否移除了飞书密钥但保留了PATH、USERPROFILE、APPDATA等系统变量。机器人突然不回复在运行窗口Ctrl C后重新npm start。电脑休眠、关机、断网都会断开 WebSocket 长连接机器人离线。要全天在线得部署到长期运行的主机部署时重新评估凭据和密钥存储方式。Codex 登录失效重新运行codex按提示登录成功后Ctrl C退出再npm start。文档读取报错先跑lark-cli docs fetch --help看本机版本的真实参数缺权限时按missing_scopes补授权。Node.js 调用 CLI 必须用execFile或spawn禁止 shell 拼接只允许合法飞书域名防止命令注入。7. 下一步怎么走跑通之后你得到的不只是一个会聊天的机器人而是一条可扩展的本地 Agent 通道飞书负责入口与协作Node.js 负责连接和权限边界Codex 负责理解与任务执行lark-cli 负责读取飞书数据。想继续扩展的话可以给机器人加/doc命令读取飞书文档并分析或者把日历汇总、任务摘要接进来。所有模型调用继续走 TaoToken 统一 KeyCLI 和 SDK 共用一套配置换模型或调额度都在控制台一处完成。如果要做长期编码或 Agent 任务可以对比一下 Coding Plan 的额度方案只是想验证模型效果先在模型对话里试几条 prompt 更省事。接入过程中遇到权限或回调问题接入文档里有更细的参数说明。先保持私聊、白名单和只读等稳定后再逐步加能力。不要一开始就开满权限也不要把高权限机器人直接放进大群。
Codex 接入飞书全栈指南：CLI、WebSocket、SDK 与机器人（Windows 保姆级完整教程）｜TaoToken 统一 Key 配置
1. 为什么 Windows 上接飞书总卡在“最后一步”Codex 接入飞书这件事真正难的不是写代码而是把 CLI、WebSocket 长连接、SDK 和机器人回调这几条链路串起来。我见过太多人卡在同一个地方lark-cli明明装好了Codex 里让它读日程却报missing_scope或者机器人/status能回普通消息发出去石沉大海。问题往往不在模型而在权限、事件订阅方式和本地进程的配合。这篇面向 Windows 10/11 的完整教程会把两种“接入”拆开讲清楚。模式 A 是让 Codex 通过飞书官方 CLI 读取你的日历、文档、任务入口在 Codex App 或 Codex CLI模式 B 是把 Codex 做成飞书里的聊天机器人入口在飞书客户端。两条链路共用一套凭证体系但排错思路完全不同。适合第一次接触 PowerShell、飞书开放平台和 Codex 的读者跟着做大约 30 到 60 分钟能跑通。需要提前说明的是本文所有模型调用都通过 TaoToken 统一 Key 走 API 通道这样你不需要在多个平台之间来回切换账号配置一次就能同时支撑 CLI 和 SDK 两种调用方式。下面从环境准备开始每一步都给可复制的命令和配置骨架。2. 前置准备Node.js、TaoToken 统一 Key 与飞书应用2.1 环境清单一台 Windows 电脑、一个可正常登录的飞书账号、能进入飞书开放平台开发者后台、一个 TaoToken 账号。网络能正常访问飞书开放平台即可。Node.js 建议装 LTS 长期支持版去官网下载页选 Windows Installer安装时确认勾选“Add to PATH”。装完打开 PowerShell执行node -v npm -v两条都能输出版本号就说明成功。如果提示“不是内部或外部命令”关掉 PowerShell 重开仍无效就重装 Node.js 并检查 PATH。2.2 拿 TaoToken 统一 Key登录 TaoToken 控制台在 API Keys 页面创建一个新 Key。这个 Key 会同时用于 Codex CLI 和 Codex SDK所以创建后先复制保存到本地密码管理器不要贴在聊天窗口或截图里。TaoToken 的 API 通道地址是https://taotoken.net/api兼容 OpenAI 风格的调用格式。Codex CLI 和 SDK 都支持通过环境变量指定 base URL 和 API Key所以后面配置里我们会把这两项写进环境变量而不是硬编码在代码里。如果你还没决定用哪种模型可以先在模型对话页面测一下响应速度和输出质量确认可用后再写进配置。长期做编码或 Agent 任务的话Coding Plan 的额度模型更适合高频调用具体可以在控制台里对比。2.3 飞书应用创建进入飞书开放平台开发者后台创建一个企业自建应用。拿到 App ID 和 App Secret 后先放着模式 A 和模式 B 都会用到。注意 App Secret 只显示一次丢了只能重置。3. 模式 A用 lark-cli 让 Codex 读取飞书数据3.1 安装飞书官方 CLI在 PowerShell 里执行npx larksuite/clilatest install第一次会提示是否安装输入y回车。装完检查lark-cli --version如果提示找不到命令关掉 PowerShell 重开或者用完整路径 $env:APPDATA\npm\lark-cli.cmd --version3.2 初始化应用配置与用户授权lark-cli config init --new终端会给出授权链接或二维码用飞书账号确认后完成应用配置。接着做用户登录授权lark-cli auth login --recommend lark-cli auth statusauth status里会出现ou_开头的用户 ID这个后面配机器人白名单要用到。3.3 测试读取日历并处理 missing_scopelark-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和ok: true。再跑一次lark-cli calendar agenda如果返回{ok: true, data: []}说明命令通了只是今天没日程。3.4 在 Codex 里调用 lark-cli新建一个空文件夹比如C:\Codex-Feishu在 Codex App 里选择它作为项目。空文件夹的作用是给 Codex 一个隔离的工作目录它不会存你的日程数据。把下面这段发给 Codex请执行以下只读命令 $env:APPDATA\npm\lark-cli.cmd calendar agenda 读取我今天的飞书日程不创建、修改或删除任何内容。用完整路径能避免 Codex 找不到命令别名也能绕开中文用户名导致的路径识别问题。审批方式初次建议选“请求批准”确认命令安全后再考虑放宽。4. 模式 B飞书机器人 WebSocket 长连接 Codex SDK4.1 配置飞书应用能力与权限在开放平台左侧进入“应用能力 → 添加应用能力 → 机器人”。然后到“开发配置 → 权限管理”至少开通权限代码用途im:message:send_as_bot机器人发送消息im:message.p2p_msg:readonly接收单聊消息im:message.group_at_msg:readonly群聊中 机器人可选再到“事件与回调”先添加im.message.receive_v1事件但订阅方式先别急着保存等本地程序跑起来再选长连接。4.2 项目骨架与 .env 配置建一个项目文件夹结构如下Feishu-Codex-Bot/ ├─ package.json ├─ .env ├─ .gitignore └─ src/ └─ index.js.env内容LARK_APP_ID你的AppID LARK_APP_SECRET你的AppSecret ALLOWED_OPEN_IDou_开头的用户ID OPENAI_API_KEY你的TaoTokenKey OPENAI_BASE_URLhttps://taotoken.net/api CODEX_MODEL CODEX_TIMEOUT_MS120000.gitignore至少包含.env node_modules/4.3 回声机器人验证通道先不接 Codex只做回声把飞书到本地的链路验证通。核心逻辑是监听im.message.receive_v1收到文本后原样回复。启动程序npm install npm run dev看到“正在建立飞书 WebSocket 长连接”后回到开放平台“事件与回调 → 事件配置”选择“使用长连接接收事件”保存并确认im.message.receive_v1已添加。然后创建版本并发布可用范围设为你自己。在飞书里给机器人发“你好”收到“收到你好”就说明这条链路全通了飞书消息 → 事件 → WebSocket → 本地 Node.js → 发送消息 API → 回复。4.4 升级为 Codex 机器人安装 Codex CLI 和 SDKnpm install -g openai/codex npm install openai/codex-sdk首次运行codex会提示登录按引导完成授权后Ctrl C退出。核心调用代码import { Codex } from openai/codex-sdk; const codex new Codex({ apiKey: process.env.OPENAI_API_KEY, baseURL: process.env.OPENAI_BASE_URL, }); 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()就能延续上下文。这里有两个关键设计一是事件回调必须快速返回不能一直awaitCodex否则飞书会判定超时并重推事件二是每个chat_id维护独立 Thread同一会话串行处理避免上下文错乱。void enqueue(chatId, () handleUserText(chatId, text)); return {};收到事件后立即登记去重、把任务放进队列、立刻结束事件处理后台再慢慢调 Codex最后通过发送消息接口回复。5. 连通性验证与成功结果启动机器人后在飞书里先发/status应看到“飞书长连接正常Codex SDK 已初始化”。再发“你好你是谁”机器人会先回“正在处理请稍候……”随后返回 Codex 的回答。测试连续上下文先发“给我解释什么是地震反演”等回答后再发“用更简单的话再解释一遍”。如果机器人理解“再解释一遍”指上一条内容说明 Thread 连续对话正常。发/clear可以清除上下文。回复比直接聊天慢是正常的链路多了飞书 → 本地机器人 → Codex 子进程 → 模型推理 → 本地机器人 → 飞书这几层。提速建议一次只发一条、简短问题用轻量模型、不要让同一chat_id并发多任务、保留“正在处理”提示并设置超时。6. 本篇常见错排查missing_scope反复出现永远先看错误里的missing_scopes按具体 scope 补授权不要盲目一次开满所有权限。按业务域授权更清晰比如lark-cli auth login --domain calendar,docs,task。/status正常但普通消息没反应多半是事件回调里直接await了 Codex 导致超时。检查是否用了后台队列、是否立即回复了“正在处理”、turn.finalResponse是否作为最终文本、Codex 子进程环境是否移除了飞书密钥但保留了PATH、USERPROFILE、APPDATA等系统变量。机器人突然不回复在运行窗口Ctrl C后重新npm start。电脑休眠、关机、断网都会断开 WebSocket 长连接机器人离线。要全天在线得部署到长期运行的主机部署时重新评估凭据和密钥存储方式。Codex 登录失效重新运行codex按提示登录成功后Ctrl C退出再npm start。文档读取报错先跑lark-cli docs fetch --help看本机版本的真实参数缺权限时按missing_scopes补授权。Node.js 调用 CLI 必须用execFile或spawn禁止 shell 拼接只允许合法飞书域名防止命令注入。7. 下一步怎么走跑通之后你得到的不只是一个会聊天的机器人而是一条可扩展的本地 Agent 通道飞书负责入口与协作Node.js 负责连接和权限边界Codex 负责理解与任务执行lark-cli 负责读取飞书数据。想继续扩展的话可以给机器人加/doc命令读取飞书文档并分析或者把日历汇总、任务摘要接进来。所有模型调用继续走 TaoToken 统一 KeyCLI 和 SDK 共用一套配置换模型或调额度都在控制台一处完成。如果要做长期编码或 Agent 任务可以对比一下 Coding Plan 的额度方案只是想验证模型效果先在模型对话里试几条 prompt 更省事。接入过程中遇到权限或回调问题接入文档里有更细的参数说明。先保持私聊、白名单和只读等稳定后再逐步加能力。不要一开始就开满权限也不要把高权限机器人直接放进大群。
