Codex Remote Feishu: 把 Codex 工作现场带到飞书，轻松跨平台协同

在这篇详细描述中，我们把 Codex Remote Feishu 的整体目标、组成、功能、安装与使用要点整理成一篇可直接落地的指南。它将帮助你在飞书里接管工作区、切换对话线索、继续正在进行的任务、上传和分享图片，以及在需要时无缝接入 VS Code 的编辑场景。核心思路是保持原有对话、模型配置和工作目录语义的连续性，同时让“飞书端 + 本地 Codex”成为一个更高效的工作流。

核心目标场景与设计原则

• 目标场景

• Codex 运行在本机或远端 Linux 上，默认在飞书里直接按工作区和已有会话继续对话。

• 只有在需要紧随编辑器焦点时，才按需把接入扩展到 VS Code。

• 尽量保留原有对话的 thread、模型配置和工作目录的语义，避免不必要的切换或丢失上下文。

• 设计原则

• 以 Feishu（飞书）为中心的工作流，尽量让用户不必离开聊天就能继续工作。

• 将复杂的底层实现隐藏在统一的事件流中，前端体验简单、直观。

• 将 VS Code 的接入作为可选增强，而不是默认前提，以便先在飞书内高效工作，再逐步接入编辑器上下文。

组件概览与发布形态

当前版本发布的是一个统一二进制集合，涵盖以下角色与职责：

• codex-remote（daemon 角色）

• 常驻服务，负责管理实例、线程、消息队列、Feishu 投影和状态接口，以及与前端的统一事件流。

• app-server（wrapper 角色）

• 封装真实的 codex 应用服务器，将原生 app-server 协议翻译成统一的事件流，确保各模块之间的互操作性。

• install（引导安装器角色）

• 负责安装稳定二进制、写统一配置，并启动 WebSetup，用于后续配置与管理。

当前官方发布的模型与资产说明如下：

• GitHub Releases 的平台包内只包含最终用户需要的运行资产：

• codex-remote / codex-remote.exe

• README.md、QUICKSTART.md、CHANGELOG.md

• 以及 deploy/ 子目录下的在线安装脚本 install-release.sh / install-release.ps1（单独作为 release 资产和仓库入口提供）

• 发行渠道与跟踪

• GitHub Releases 现在区分 production / beta / alpha 三条 track。

• 默认在线安装入口始终指向最新的 production 版本，必要时可显式安装 beta/alpha。

• 发布流程通过 GitHub Actions 的 Release workflow 完成。

• WebSetup 是全面的产品配置入口

• 通过 WebSetup / Admin UI 完成飞书 App 的新增、验证、启停，运行环境检查，自动启动等操作。

• 也支持按需执行 VS Code detect、editorsettings、managedshim、reinstall-shim 等步骤。

关键功能亮点

• 在飞书内列出可接管的工作区，直接继续已有对话或开启新会话，方便快速进入工作状态。
• 在统一目标选择卡中直接添加工作区，可接入本地目录或导入 Git 仓库。
• 支持从最近会话、全部会话列表中继续对话，减少重复工作。
• 需要时可让飞书跟随当前编辑器焦点进入 VS Code 的对话场景，增强一致性。
• 文本消息排队、typing 指示、以及 stop 中断；对当前执行的源消息提供 steer 操控，/steerall 一次性合并进入执行。
• 排队中的文本消息支持通过点赞提升为对当前执行的跟进项。
• 支持暂存图片，在下一条文本中与文本一起发送给 Codex，实现多媒体协作。
• 支持 /sendfile，从当前工作区直接挑选文件并发送回飞书聊天。
• /compact 手动整理当前 thread 的上下文，提升可读性和可追溯性。
• 支持查看当前生效的模型和推理强度，并提供飞书侧临时覆盖。
• /cron 为 daemon 实例打开专属定时任务表，任务来源可来自本地工作区或 Git 仓库。
• 在飞书中可看到计划更新、工具调用、Web 搜索、命令执行等共享进度卡，便于群聊协作。
• 区分系统提示、过程消息和最终回复；最终回复直接回到触发它的消息下方，便于理解上下文。
• 旧卡片、旧按钮与旧命令会明确提示已过期或移除，避免混淆。
• 最终回复中的本地 .md 和单文件 .html 链接可自动替换为飞书云空间预览链接，提升可浏览性。

安装前准备

在正式安装前，请确保具备以下条件与资源：

1) 目标机器上真实的 codex 能够正常运行。 2) 如需与 VS Code 联动，建议安装 VS Code 的 ChatGPT / Codex 扩展。 3) 搭建并配置好飞书自建应用（App）所需权限和设置。 4) 如果你在源码构建或仓库联调，需要 Go 1.24+ 的运行环境。 5) 准备飞书应用所需的基本凭证与权限（App ID、App Secret、消息接收、reaction、机器人菜单等）。 6) 如要启用 /cron 定时任务，推荐额外开通 bitable:app。 7) 如要启用本地文档预览，推荐开通 drive:drive，并理解本地文档预览的工作方式。

• 配置示例与模板

• 部署相关配置范例位于：deploy/feishu/app-template.json、deploy/feishu/README.md

• 这些模板帮助你理解所需的最小权限、事件接收、机器人菜单等配置要点。

• 预览与云端资源

• 当前实现会在发送最终回复前自动创建目录、上传文件、查询访问链接，并为当前对话用户或群体补充协作者权限。若不开启本地文档预览，此部分能力可按需禁用，但主对话功能仍可使用。

一条命令即可安装（macOS / Linux、Windows）

• macOS / Linux：
• curl -fsSL https://raw.githubusercontent.com/kxn/codex-remote-feishu/master/install-release.sh | bash
• Windows PowerShell：
• irm https://raw.githubusercontent.com/kxn/codex-remote-feishu/master/install-release.ps1 | iex

该安装脚本会自动完成以下步骤：

• 识别平台并下载 GitHub 构建好的 Release 包

• 解压到本地 release 缓存目录

• 安装稳定路径下的 codex-remote

• 启动本地 daemon

• 打开或打印 WebSetup 链接

• 如果要安装特定的 prerelease track 的最新版本：

• bash -fsSL install-release.sh | bash -s -- --track beta

• 或 PowerShell 版本的 Track 指定为 beta

• 安装指定版本：

• bash -fsSL install-release.sh | bash -s -- --version v1.0.0

• PowerShell 相应参数也有同等效果

手动安装 release 包

从 GitHub Releases 下载对应平台归档后，直接运行归档内的统一二进制。

• macOS / Linux：
• ./codex-remote install -bootstrap-only -start-daemon
• Windows PowerShell：
• .\codex-remote.exe install -bootstrap-only -start-daemon

启动后，请打开输出中的 /setup 链接，后续飞书配置、normal 模式使用准备、以及按需的 VS Code detect/apply 和 shim 重装都在 WebSetup / Admin UI 完成。

当前用户升级与维护

• 用户升级入口：
• 在已接入的飞书会话中发送 /upgrade latest，即可触发升级流程。
• 注意事项
• daemon 不会在后台自动检查 Release，也不会主动弹出升级提示。升级只通过手动输入 /upgrade latest 来触发。
• 这使升级更具可控性，也避免了自动化行为对现有对话的干扰。

WebSetup 与按需接入 VS Code 的工作流

• WebSetup 的定位

• 它是真正的产品配置入口，统一处理飞书 App 的新增、验证、启停，以及运行环境检查、自动启动等任务。

• 还支持按需执行 VS Code 的 detect、editorsettings apply、managedshim apply、reinstall-shim 等步骤，从而实现对编辑器的无缝衔接。

• 外部使用顺序与体验 1) 首先完成飞书 App 的接入与环境检查，确保基础能力就绪。 2) 进入飞书默认的 normal 模式工作，直接从对话中持续生产力。 3) 如有明确需要“飞书跟随 VS Code 当前焦点走”的场景，回到 WebSetup 页面开启 VS Code 的接入。 4) 在 VS Code 场景下，有两种接管模式：

  • editor_settings：修改 settings.json 中的 chatgpt.cliExecutable，更适合本机桌面 VS Code。
  • managed_shim：直接替换扩展 bundle 里的 codex，原始入口保留成 codex.real，更适合 VS Code Remote 场景。 5) 代码联调与仓库调试时，可以使用 go build 构建本地二进制，并用 setup 流程进行 bootstrap。

• 源码仓调试入口

• go build -o ./bin/codex-remote ./cmd/codex-remote

• ./bin/codex-remote install -bootstrap-only -start-daemon

• ./setup.ps1（Windows 平台的同等流程）

• 需要绑定本地工作区时的绑定策略

• 如果工作区下存在 .codex-remote/install-target.json，则 repo-local 的命令会优先绑定全局实例与 baseDir；没有绑定时，默认回退到 stable。

• stable 的默认路径包括：

  • ~/.config/codex-remote/config.json
  • ~/.local/share/codex-remote/install-state.json
  • ~/.local/share/codex-remote/logs/codex-remote-relayd.log

• 命名实例会写入 namespace 路径，例如 master：

  • ~/.config/codex-remote-master/codex-remote/config.json
  • ~/.local/share/codex-remote-master/codex-remote/install-state.json
  • ~/.local/share/codex-remote-master/codex-remote/logs/codex-remote-relayd.log

• 配置入口的更新

• 当前磁盘配置入口只保留 config.json；旧的 config.env、wrapper.env、services.env 不再自动读取或迁移。

• 不再支持 Docker 部署

• 为简化运维与提升性能，当前项目取消 Docker 部署入口，改为 Go 单二进制的本机安装与运行，成本更低、体验更直观。

飞书端的使用场景与常用命令

• 常见用法

• 继续当前项目：/list 选中要接管的工作区，然后 /use 继续已有会话，或直接 /new 开启新会话。

• 添加新工作区：/list -> “添加工作区”，可接入本地目录，也可拉取 Git 仓库。

• 直接回到最近对话：/use

• 需要跟随编辑器焦点走时：/mode vscode -> /list -> /follow

• 拍照后说明：先发图片，下一条文本会把图片一起带给 Codex

• 对当前执行的任务补充说明：直接回复正在执行的消息，或发送 /steerall 将队列内容合并入当前执行

• 将当前工作区文件发回聊天：/sendfile

• 手动整理上下文：/compact

• 获取模型与推理覆盖：/model、/reasoning（bare 版返回参数卡）

• 控制执行权限：/access（别名 /approval）

• 控制前端显示详细程度：/verbose（quiet / verbose）

• 定时任务菜单：/cron，/cron edit 打开表格配置，/cron reload 生效

• 机器人菜单与入口

• 常用前端入口：menu、stop、steerall、new、reasoning、model、access、verbose、cron 等

• WebSetup 与 Feishu 模板统一定义，/help 提供文本帮助，/menu 的参数卡以紧凑按钮卡片呈现

• 本地文档预览

• 主要处理最终回复中的 Markdown 链接，如 README 或 mock

• 仅对单文件 .html 进行预览处理，不打包其它本地资源

• 预览文件默认上传到应用云空间目录 Codex Remote Previews/

• 单聊授权给当前用户；群聊授权给当前用户与当前群

• 失效与过期处理

• 如果遇到旧卡片、旧按钮或旧菜单项已过期，将给出明确提示，需重新发送对应命令

• Troubleshooting 快速入口

• 若遇到网络或代理相关问题，先排查本地链路是否被代理污染：

  • unset httpproxy httpsproxy HTTPPROXY HTTPSPROXY ALL_PROXY

• 依次检查关键状态接口与配置：

  • curl --noproxy '*' -sf http://127.0.0.1:9501/api/admin/bootstrap-state | jq .
  • curl --noproxy '*' -sf http://127.0.0.1:9501/v1/status | jq .

• 核对 config.json 中 relay.serverURL、wrapper.codexRealBinary，以及飞书凭证与监听地址

• 检查 VS Code 是否通过 wrapper 启动 Codex

• 查看日志：~/.local/share/codex-remote/logs/codex-remote-relayd.log

文档、资源与开发指引

• 官方文档索引

• 变更记录（CHANGELOG.md）

• 用户使用说明书（docs/general/user-guide.md）

• 文档索引（docs/README.md）

• 架构说明（docs/general/architecture.md）

• 协议说明（docs/general/relay-protocol-spec.md）

• 飞书产品行为（docs/general/feishu-product-design.md）

• 飞书 Markdown 预览设计（docs/implemented/feishu-md-preview-design.md）

• 安装与部署设计（docs/general/install-deploy-design.md）

• 测试策略（docs/general/go-test-strategy.md）

• 开发者入口

• 开发者文档请参见 DEVELOPER.md（仓库内的开发者说明）

• 代码与构建要点

• 如果你在源码仓调试，不依赖 Release 包，可以使用 go 构建生成本地二进制：

  • go build -o ./bin/codex-remote ./cmd/codex-remote
  • ./bin/codex-remote install -bootstrap-only -start-daemon

• Windows 下相应的 setup.ps1 也可用来生成本地二进制并执行相同安装流程

• 版本与升级的发布路径

• Release 流程会将 admin UI、各平台二进制、checksums、GitHub Release 的发布统一在 GitHub 端完成

• 本地命令行的升级入口是 /upgrade latest，保持简洁与可控

• 不再提供的部署形态

• Docker 部署不再受支持，这是因为单二进制 Go 程序在本机安装运行的体验更简单、配置也更易控。

实践中的使用建议

• 初次使用时，建议先在飞书内以 normal 模式工作，熟悉对话、上下文传递、消息队列与模型覆盖的基本行为。
• 若你确实需要“飞书端跟随 VS Code 当前焦点走”的工作流，可以在后续阶段通过 WebSetup 逐步接入 VS Code，逐步把对话从飞书扩展到编辑器。
• 对于多工作区与多对话场景，推荐使用 /list、/use、/history、/status 等命令进行有序切换与上下文追踪。
• 在需要可追溯和协同的场景中，充分利用 /cron 提供的定时任务表，以及对计划更新、工具调用、Web 搜索、命令执行等状态卡的共享，以提升团队协作效率。

总结

Codex Remote Feishu 将原本分散在不同工作流中的能力统一到飞书端的协作场景中，提供从会话管理到点对点文件传输、从模型配置到推理强度覆盖、再到可选的 VS Code 接管等多维度能力。它以保持对话上下文和工作目录语义的一致性为核心目标，尽量让用户在不离开飞书的情况下完成“大部分工作”，并在需要时以最小代价接入编辑器来实现更深层的代码级协作。

这是一套继续演进的产品线，强调可控升级、清晰的状态管理、以及直观的用户体验。无论你是来自本地 Linux 的开发者、还是依赖云端协作的团队成员，Codex Remote Feishu 都旨在成为你日常工作流中的核心棋子，帮助你把“工作现场”带到通讯工具里，提升生产力与协作效率。若你正在搭建或优化你的工作流，这份指南将为你提供清晰的实施路径与实操要点。