Codex Remote · 飞书 / Feishu

在飞书中继续本机 VS Code 的 Codex 会话。Codex Remote 为每个会话建立一个专属飞书群，同步可见历史与新回复，并把群内的文字、图片和交互操作送回原会话。连接由你的 Mac 发起和维护；这不是托管在云端的 Codex 代理。

Continue a local VS Code Codex conversation from Feishu. Codex Remote creates a dedicated Feishu group for each conversation, syncs visible history and new replies, and routes text, images, and supported actions back to the original session. Your Mac initiates and maintains the connection; no hosted Codex agent is involved.

工作方式 / How it works

Remote 插件负责飞书连接、群与会话映射、同步和投递；必需的 Codex IO Bridge 插件通过公开 API 读取本机 Codex 会话并提交输入。同一 macOS 用户的多个 VS Code 窗口共享一个本机后台和一条飞书长连接，但各窗口仍保留自己的 Codex 会话路由。

Remote owns the Feishu connection, group-to-session mapping, sync, and delivery. The required Codex IO Bridge extension reads local Codex sessions and submits input through its public API. VS Code windows belonging to the same macOS user share one local background process and one Feishu WebSocket connection, while each window retains its own Codex route.

本扩展与 IO Bridge 专用于 VS Code 官方 Codex。Codex CLI 和 ChatGPT Desktop 的飞书接入在独立产品中开发；本扩展不会启动 Desktop 的 app-server，也不会在会话被其他程序占用时自动切换宿主。

This extension and IO Bridge serve official Codex in VS Code. Feishu connectors for Codex CLI and ChatGPT Desktop are developed as separate products. This extension does not start a Desktop app-server or automatically switch hosts when another program owns a conversation.

  VS Code 窗口 A / Window A           VS Code 窗口 B / Window B
  +-------------------------+         +-------------------------+
  | Remote                  |         | Remote                  |
  | Codex IO Bridge API     |         | Codex IO Bridge API     |
  | 官方 Codex / Codex      |         | 官方 Codex / Codex      |
  +------------+------------+         +------------+------------+
               | 认证本机 IPC / authenticated local IPC |
               +--------------------+-------------------+
                                    |
                   +----------------v----------------+
                   | 本机共享后台 / Local relay        |
                   | 会话路由 / Session routing       |
                   | 历史同步 / History sync          |
                   | 输入队列 / Input queue           |
                   | 有序出站 / Ordered outbox        |
                   | 本机账号状态 / Local account data |
                   +----------------+----------------+
                                    |
                           WebSocket + Feishu API
                                    |
                   +----------------v----------------+
                   | 飞书应用 / Feishu custom app     |
                   | 机器人私聊 + 专属会话群           |
                   | Bot chat + session groups       |
                   +---------------------------------+

模块 / Module	职责 / Responsibility
Remote 控制面板 / Control panel	配置、连接状态、会话、同步和投递维护 / Configuration, status, sessions, sync, and delivery maintenance
Remote 会话引擎 / Session engine	群绑定、命令、历史与实时消息、交互卡片 / Group binding, commands, history and live messages, interactive cards
本机共享后台 / Local relay process	单例飞书连接、跨窗口路由、持久队列和恢复 / Single Feishu connection, cross-window routing, durable queues, and recovery
Codex IO Bridge	Codex 健康和能力检查、历史读取、输入与事件 / Codex health and capability checks, history reads, input, and events
飞书企业自建应用 / Feishu custom app	机器人私聊、会话群、消息、卡片与媒体 / Bot chat, session groups, messages, cards, and media

从飞书发出的消息先经过机器人长连接与本机后台的身份检查，再交给对应窗口的 IO Bridge；Codex 的可见历史和事件沿反方向进入按群有序的投递队列。发送结果不明时会停下并要求核对，避免把同一任务重新提交给 Codex，或把同一回复重复发到群里。

An incoming Feishu message passes through the bot WebSocket and local relay's identity check before reaching IO Bridge in the window that owns the session. Visible Codex history and events travel back through an ordered, per-group delivery queue. An uncertain submission or send result pauses for review instead of risking a duplicate Codex task or group message.

输入 / Input
飞书群        -> 机器人长连接 -> 身份检查与输入队列 -> IO Bridge -> 原 Codex 会话
Feishu group  -> Bot WebSocket -> Auth + input queue  -> IO Bridge -> Codex session

回复与历史 / Replies and history
Codex 可见消息 -> IO Bridge -> 同步与去重 -> 有序出站队列 -> 原飞书群
Codex records  -> IO Bridge -> Sync + dedup -> Ordered outbox -> Same Feishu group

提交或投递结果不明 / Uncertain result -> 暂停并核对 / Pause for review

适用环境 / Requirements

需要 macOS 桌面版 VS Code、已登录且可用的官方 Codex 扩展、Codex IO Bridge，以及你有权限管理的飞书企业自建应用。当前不支持 Windows、Linux、Remote SSH、容器或 Codespaces；电脑关闭或休眠时也无法继续执行和转发。

You need desktop VS Code on macOS, a working signed-in official Codex extension, Codex IO Bridge, and a Feishu custom app you can administer. Windows, Linux, Remote SSH, containers, and Codespaces are not supported. Tasks and relaying cannot continue while the Mac is off or asleep.

IO Bridge 是扩展依赖；安装或更新后，按 VS Code 提示重新加载相关窗口。Remote 会检查 Bridge 的实际健康和能力，不会自行安装或修改 Codex 的桥接补丁。功能需要的能力不可用时，面板会说明原因；现有会话不因缺少“新建会话”能力而失去只读访问。

IO Bridge is an extension dependency. Reload relevant VS Code windows after installing or updating either extension. Remote checks Bridge health and actual capabilities; it does not install or modify the Codex bridge patch. The panel explains unavailable capabilities, and a missing create-session capability does not prevent read-only access to existing sessions.

首次连接 / First connection

1. 准备应用。 在飞书开发者后台创建企业自建应用，启用机器人，将自己纳入应用可用范围，配置下方的消息事件、卡片回调和所需权限，然后发布应用版本。选择“使用长连接接收事件”；不需要为机器人部署公网回调服务器。

1. Prepare the app. Create a Feishu custom app, enable its bot, include yourself in its availability scope, configure the events, card callback, and permissions below, then publish an app version. Select long-connection event delivery; the bot does not need a public callback server.

2. 保存凭据。 打开 VS Code 活动栏中的 Codex Remote · 飞书，在 连接与授权 页填写 App ID 和 App Secret 并保存。全新安装时“已识别用户”留空。密钥保存在 VS Code SecretStorage，密码框不会回显已保存的值。

2. Save credentials. Open Codex Remote · 飞书 in the VS Code Activity Bar. On Connection & Authorization (连接与授权), enter the App ID and App Secret and save. Leave the identified-user field empty on a fresh install. The secret is stored in VS Code SecretStorage and is never echoed back into the password field.

3. 识别本人。 点击 连接飞书并识别账号。面板显示等待私聊后，在此机器人的原私聊发送“菜单”或 /menu。插件只接受本次连接后的真人私聊，取得当前应用下的本人 open_id，保存绑定并发回入口卡片；无需手工填写 ID。

3. Identify yourself. Select Connect to Feishu and identify account. When the panel asks for a direct message, send “菜单” or /menu to this bot. Remote accepts a human direct message from this connection, saves your open_id for this app, and returns the entry card. You do not need to enter the ID manually.

4. 开始会话。 从私聊入口新建会话，或在侧栏选择现有 Codex 会话并打开到飞书。首次同步会在历史投递完成后邀请你进入专属群；以后在群内直接发消息。若 Codex 尚未就绪，先到 IO Bridge 设置查看实际状态。

4. Start a conversation. Create a session from the bot's direct-message entry, or select an existing Codex session in the sidebar and open it in Feishu. Initial history is delivered before you are invited to its dedicated group; then you can message the group directly. If Codex is not ready, inspect the actual status in IO Bridge settings.

保存配置、检查配置和启动连接是不同操作。检查只验证应用凭据与机器人身份；启动才建立连接并发送入口。以后可在侧栏停止本机共享后台；关闭某个侧栏或 VS Code 窗口不会停止其他窗口正在使用的连接。

Saving settings, checking settings, and starting the connection are separate actions. A check validates app credentials and bot identity; starting connects and sends the entry card. The sidebar can stop the shared local process. Closing a sidebar or one VS Code window does not stop a connection used by other windows.

飞书应用清单 / Feishu app checklist

以下是功能所需的应用配置。飞书后台的权限名称和租户策略可能变化，请以相应 API 在开发者后台显示的要求为准；新增权限或事件后需发布新应用版本。

These settings cover the app features. Feishu's permission names and tenant policies may change; use the requirements shown for each API in the developer console. Publish a new app version after adding permissions or events.

项目 / Item	配置或用途 / Setting or use
机器人能力 / Bot	启用并发布，授权用户在应用可用范围内 / Enable and publish; include the operator in the app's availability scope
事件模式 / Event mode	使用长连接接收事件 / Receive events over a long connection
消息事件 / Message event	`im.message.receive_v1`
卡片回调 / Card callback	`card.action.trigger`
机器人发送 / Bot sends	`im:message:send_as_bot` 或更宽的 `im:message`
接收私聊 / Direct messages	`im:message.p2p_msg:readonly`
接收群消息 / Group messages	`im:message.group_msg`；只订阅 @ 机器人消息时，每次操作都要 @ 机器人 / With @-only delivery, mention the bot for each action
读取被回复消息 / Read replied-to messages	本地投递记录找不到原消息时，调用 `im.message.get`；需该接口适用的 `im:message`、`im:message:readonly` 或 `im:message.history:readonly`，且机器人在群内 / When the local record lacks the original, use `im.message.get` with an applicable read scope and bot membership
创建群 / Create groups	`im:chat:create` 或更宽的 `im:chat`
邀请成员 / Invite members	`im:chat.members:write_only` 或更宽的 `im:chat`
更新群名和头像 / Rename groups and update avatars	`im:chat:update` 或更宽的 `im:chat`；部分租户还需 `im:chat:operate_as_owner` / Some tenants also require `im:chat:operate_as_owner`
图片和文件 / Media	上传需要 `im:resource` 或 `im:resource:upload`；读取用户消息中的图片需适用的 `im:message`、`im:message:readonly` 或 `im:message.history:readonly` / Upload needs `im:resource` or `im:resource:upload`; reading incoming images needs an applicable message-resource scope
本人身份代发 / Send as user	可选：`im:message`、`im:message.send_as_user`、媒体用 `im:resource`，自动续期用 `offline_access` / Optional: these scopes support user-authorized sends, media, and renewal

“已识别用户”必须是本人在当前应用下的 open_id，不能填机器人的 bot.open_id 或其他应用的 ID。只安装插件并不会预填你的应用、账号或私有服务地址。

The identified user must be your own open_id for this app, not the bot's bot.open_id or an ID from another app. A fresh installation does not prefill an app, account, or private service address.

功能一览 / Features

下表按实际操作归纳功能。会话群设置彼此独立；标为“本机共用”的选项适用于同一 macOS 用户的所有窗口和会话群。

The table groups features by workflow. Group settings are independent; options marked “local-wide” apply to all windows and session groups for the same macOS user.

功能 / Feature	用户能做什么 / What you can do	范围 / Scope
会话映射 / Session mapping	每个 Codex 会话建立或复用一个私有群；群名跟随会话名 / Create or reuse one private group per Codex session; update its title	按会话 / Per session
历史同步 / History sync	新群选择最近 1、5、10、30、50、100 轮或全量；按原时间顺序导入 / Import the latest 1, 5, 10, 30, 50, or 100 rounds, or all history, in source order	按群 / Per group
增量与重同步 / Catch-up and rebuild	`/sync` 补齐原群新记录；必要时完整同步到新群，保留旧群 / Catch up in the same group, or rebuild in a new group while retaining the old one	按群 / Per group
自动同步新会话 / Auto-sync new sessions	可选地自动为本机新会话建群；普通会话全量，分支会话默认最近 5 轮 / Optionally create groups for new local sessions; all history for ordinary sessions, last five rounds for forks	本机共用 / Local-wide
远程新建 / Create remotely	在已打开工作区新建，或选择目录并打开新 VS Code 窗口 / Create in an open workspace or choose a folder and open a new VS Code window	按请求 / Per request
文字与图片输入 / Text and images	群内发送任务、图片或图文；忙碌时选择立即调整方向、原生排队或取消 / Send tasks, images, or both; while busy, steer now, queue natively, or cancel	按会话 / Per session
回复引用与注释 / Replies and annotations	回复同群消息时把原消息文字交给 Codex 作上下文；Codex 所选文字注释在飞书中简明展示 / Pass replied-to group text as context and display Codex text selections readably	按会话 / Per session
会话控制 / Session controls	选择模型和推理强度、中断当前回合、处理受支持的审批与问题 / Choose model and reasoning effort, interrupt a turn, answer supported approvals and questions	按会话 / Per session
最终回复模式 / Final-reply formats	五种 Markdown 与图片呈现方式，按群选择宽度 / Five Markdown and image formats, with group-specific width	按群 / Per group
图表与宽图 / Diagrams and wide images	Mermaid 渲染、源码查看、手动重发图表和最终回复宽图 / Render Mermaid, inspect source, and request diagram or wide-reply images	按群 / Per group
自动附件 / Automatic attachments	按图片、Markdown、配置、代码、其他五类和回复阶段决定是否发送本地引用文件 / Control referenced local-file sends by five categories and reply phase	本机共用 / Local-wide
历史文件 / History files	`/files` 筛选会话历史引用并手动发送当前本地版本 / Filter referenced files and send their current local versions on demand	按群 / Per group
本人身份 / User identity	可选地授权历史用户消息以本人身份发送；私聊 `/authorize` 可在手机上重新授权 / Optionally send historical user messages as yourself; renew from a phone with `/authorize` in the bot chat	按应用绑定 / Per app binding
会话管理 / Session management	查看同步、离线和归档状态；移除管理时保留飞书群及 Codex 会话 / Inspect sync, offline, and archived states; remove management without deleting groups or Codex sessions	本机共用 / Local-wide
诊断与恢复 / Diagnostics	查看三层连接状态、日志、失败或未知投递并人工核对 / Inspect bridge, local relay, and Feishu status; review logs and failed or uncertain sends	本机共用 / Local-wide

新群默认使用 模式 2：文本 Markdown 自适应、1200 像素图片宽度和全量历史。历史中的普通中间回复默认不导入；正常连接期间的新进度仍可实时同步。自动同步新会话默认关闭，本地文件自动发送默认只包含最终回复中的图片和 Markdown 文件。

A new group defaults to mode 2: adaptive Markdown, 1200 px image width, and all history. Ordinary intermediate replies are omitted from historical imports by default; new progress can still be relayed live. Auto-sync of new sessions is off by default, and automatic local-file sends initially include only images and Markdown files referenced by final replies.

群内回复优先使用本机已保存的同群消息，必要时再从飞书读取原消息。读取失败时当前正文仍照常提交，群里会说明引用没有附上；回复图片或文件只附类型说明，不会悄悄把原媒体重新交给 Codex。Codex 的所选文字注释仅改变飞书里的展示，原始会话内容和发送队列保持不变。

Group replies first use the locally saved message and otherwise read the original from Feishu. If that read fails, the new text still goes to Codex and the group is told that the quote was omitted. Replying to an image or file adds a type description, not the original media. Codex text selections are reformatted only for display in Feishu; stored conversation content and input queue behavior remain unchanged.

本人身份授权可自动续期。遇到确定未发送的断网请求时，联网后会重新尝试；授权确实不可用时，机器人会在私聊提醒。此时确认未送达的历史用户消息由机器人按原顺序继续同步，发送结果不明的消息仍需先在 Remote 面板核对。手机上可在机器人私聊发送 /authorize，打开授权卡片中的链接，再把浏览器最终跳转的完整 localhost 地址填入卡片；授权码只接受本次授权和已绑定的本人账号。

User authorization can renew automatically. A request known not to have reached Feishu is retried after reconnection. If authorization becomes unavailable, the bot sends a direct-message reminder. Historical user messages definitely not sent continue in order as bot messages; uncertain sends still need review in Remote. On a phone, send /authorize to the bot, open the consent link, and enter the complete final localhost redirect URL in the card. The code is accepted only for the current request and bound operator.

五种最终回复模式 / Five final-reply modes

模式按群保存，修改后影响新安排的消息，不改写已经送出的历史。需要生成图片时使用本机 Chrome、Edge 或 Chromium；普通文字在自适应模式下无需启动浏览器。

The mode is saved per group. Changing it affects newly planned messages, not previously delivered history. Image rendering uses a local Chrome, Edge, or Chromium installation; ordinary text in adaptive mode does not launch a browser.

模式 / Mode	呈现方式 / Presentation
1 · 文本 Markdown / Text Markdown	全文文字，代码和 Mermaid 保留源码 / Full text; code and Mermaid stay as source
2 · 自适应 / Adaptive (default)	文字保留 Markdown，表格、代码块和 Mermaid 在原位置转图片 / Keep prose as Markdown; render tables, code blocks, and Mermaid in place
3 · 自适应整图 / Adaptive full image	有宽内容时整篇转图片，否则发送文字 / Render the whole reply only when it contains wide content
4 · 纯图片 / Image only	每条最终回复整篇转图片 / Render every final reply as images
5 · 文本与图片 / Text and image	先发送完整文字，再发送整篇图片 / Send full text, then full-reply images

常用入口 / Common commands

私聊用于选择和管理会话，专属群用于与该会话交互。/help 会按所在位置展示可用命令，群内 /menu 提供快捷操作；卡片也会检查操作者与会话是否匹配。

Use the bot's direct chat to select and manage sessions, and a dedicated group to interact with its session. /help shows commands relevant to the current chat, and /menu opens group shortcuts. Card actions are checked against the operator and session.

位置 / Where	命令 / Command	用途 / Purpose
私聊 / Direct chat	`/menu`, `/sessions`	入口与已同步会话 / Entry and managed sessions
私聊 / Direct chat	`/settings`, `/attachments`	群设置、本机历史与附件策略 / Group settings, local-wide history and attachment policies
私聊 / Direct chat	`/authorize`	打开本人身份授权卡片，在手机上完成授权 / Open the user authorization card and complete consent on a phone
会话群 / Session group	`/sync`, `/files`	补同步、浏览历史文件 / Catch up and browse referenced files
会话群 / Session group	`/model`, `/cancel`	修改后续模型设置、中断当前回合 / Set future model options; interrupt the current turn
会话群 / Session group	`/preview`, `/diagrams`, `/diagram-source`	最终回复宽图、图表、图表源码 / Wide preview, diagrams, diagram source
两处 / Both	`/help`, `/status`	帮助、连接和队列状态 / Help, connection and queue status

机器人与群头像 / Bot and group avatars

在“连接与授权 → 机器人头像”中可以查看机器人当前已经生效的头像，并打开共享头像选择器。选择器提供机器人、猫、狐狸、熊、猫头鹰、鲸鱼、火箭、星球、山峰和叶子共 10 个默认头像，也可以通过本机文件选择器上传 PNG 或 JPEG 图片。图片需不超过 2 MiB，宽、高均为 241–4096 像素；建议使用 512×512、未经圆角裁剪的正方形图片。选中后先预览，再确认应用。

In Connection and authorization → Bot avatar, view the bot's current online avatar and open the shared picker. It includes ten presets—robot, cat, fox, bear, owl, whale, rocket, planet, mountain, and leaf—and supports local PNG or JPEG uploads. Images must be at most 2 MiB, with each dimension between 241 and 4096 pixels; a 512×512 square without rounded cropping is recommended. Preview the selection before applying it.

机器人头像属于飞书应用配置。点击保存只更新头像草稿；随后单独点击“提交发布”，确认将提交该应用当前所有待发布配置。飞书审核通过且头像正式生效后，当前头像预览才会更新。该功能需要应用身份权限 application:application:patch，查询自身应用配置与版本状态需要 application:application:self_manage；不依赖“以本人身份发送”的 OAuth 授权。应用正在审核或提交结果未确认时，先刷新状态核对，再进行下一次操作。

The bot avatar is part of the Feishu application configuration. Saving changes only the avatar draft. Use the separate Submit for release action and confirm that it submits all of the application's current unpublished changes. The online preview updates after approval and the avatar takes effect. This requires the application scope application:application:patch; reading the app's own configuration and version status requires application:application:self_manage. It does not use the optional send-as-user OAuth authorization. Refresh and verify an under-review or uncertain release before performing another operation.

Remote 创建的新会话群会复用机器人当时已经生效的头像，未发布的头像草稿不会用于建群。“会话管理 → 已同步到飞书的会话”中的每个群提供“同步头像”和“设置头像”：前者复制机器人的当前线上头像，后者打开同一个头像选择器，为该群单独选择头像。已有群的独立头像不会因为修改机器人头像而自动覆盖；需要更新时手动同步即可。头像下载和上传结果在本机共用并缓存，空闲时不会持续轮询头像。

New session groups created by Remote inherit the bot's current online avatar; unpublished drafts are never used. Each group in Session management → Synced sessions provides Sync avatar to copy the bot's current avatar and Set avatar to use the same picker for an independent group avatar. Changing the bot avatar does not overwrite existing group avatars automatically; sync them explicitly when needed. Downloads and upload keys are shared and cached locally, with no idle avatar polling.

本机中转服务功能表 / Local relay service inventory

“中转服务”是 Remote 在本机启动的共享后台，不是可供他人访问的公网服务。下面列出它承担的完整职责，便于判断消息经过哪里、状态存放在哪里，以及某一步失败时如何恢复。

The “relay service” is Remote's local shared background process, not a public service. This inventory shows its responsibilities, where messages pass, where state lives, and how each part recovers.

功能 / Function	行为与边界 / Behavior and boundary
单例生命周期 / Single instance	本机内核锁防止多个后台争用同一飞书长连接；最后一个窗口离开后空闲退出 / A kernel lock prevents competing local connections; idle exit follows the last window
认证本机 IPC / Authenticated local IPC	VS Code 窗口通过认证 Unix socket 接入；路由和恢复信息只授予已接入窗口 / Windows connect through authenticated Unix sockets; routes and recovery data stay with attached windows
飞书连接 / Feishu connection	一条 SDK WebSocket 长连接收消息与卡片事件；连接状态依据实际回调 / One SDK WebSocket receives messages and card events; status follows actual connection callbacks
临时身份识别 / Temporary pairing	只在明确发起识别后处理新私聊，识别完成或取消后清理临时状态 / Process a new direct message only during explicit pairing; clear temporary state afterward
账号分区 / Account partition	App ID 与授权用户共同划分群映射、队列和同步状态；切换账号保留旧分区 / Partition mappings, queues, and sync state by app and operator; retain old partitions on switch
跨窗口路由 / Window routing	记录 Bridge 的后端与窗口身份，把会话输入交给正确的可用窗口 / Route session input to the available window for its Bridge backend
桥接能力门禁 / Bridge capability gate	根据公开健康状态与能力决定可用操作，不从扩展版本号推测 / Gate operations by public health and capabilities, not inferred version numbers
入站鉴权与去重 / Inbound authorization and deduplication	仅授权用户可操作；飞书消息 ID 和操作 ID 防止重复事件执行 / Restrict actions to the operator; message and operation IDs prevent duplicate handling
输入持久队列 / Durable input queue	忙碌或明确未提交时等待；提交结果不明时暂停，避免重复模型调用 / Wait for busy or definitely unsubmitted input; pause unknown results to avoid duplicate model calls
会话创建与群绑定 / Session and group creation	保存操作进度，避免重复按钮重开窗口、重建会话或群 / Persist operation progress to prevent duplicate windows, sessions, or groups
历史与实时观察 / History and live observation	按 Bridge 可见 JSONL 消息和事件追赶，同群保存同步位置与去重记录 / Catch up from Bridge-visible JSONL messages and events; retain per-group position and deduplication
顺序出站队列 / Ordered outbound queue	文字、卡片、图片和文件按群有序发送；上传和投递记录持久化 / Send text, cards, images, and files in group order; persist upload and delivery records
重试与人工核对 / Retry and review	限流或明确可重试失败退避；超出去重保护的未知结果等待人工确认 / Back off on retryable failures; require review for uncertain sends beyond deduplication protection
配置与凭据 / Settings and credentials	共享设置存于本机受限文件；App Secret 保留在 SecretStorage 并仅在连接期间供后台使用 / Shared settings use restricted local files; the secret stays in SecretStorage and reaches the process only while connected
可选用户授权 / Optional user authorization	本机浏览器 OAuth、身份校验、加密凭据、自动续期及代发回流去重 / Local-browser OAuth, identity checks, encrypted credentials, renewal, and echo deduplication
诊断与恢复 / Diagnostics and recovery	报告连接层级、投递异常和窗口状态；重启后从持久状态恢复可确认的工作 / Report connection layers, delivery issues, and window state; resume confirmable work from persistent state

本机状态位于 ~/Library/Application Support/CodexRemote/。它包含群映射、聊天正文、同步位置和投递记录，因此卸载插件不等于删除飞书群或本机历史；请按自己的设备备份和访问控制要求管理此目录。App Secret 不写入这些状态文件。

Local state lives under ~/Library/Application Support/CodexRemote/. It contains group mappings, message content, sync positions, and delivery records. Uninstalling the extension does not delete Feishu groups or this local history; manage the directory according to your device's backup and access policy. App Secret is not written to those state files.

可选：以本人身份发送 / Optional: send as yourself

默认由机器人发送同步消息。若要让历史中的用户消息显示为本人，先在飞书应用中开通表格所列用户身份权限，在 Remote 面板复制本机回调地址并加入应用的重定向 URL，然后点击授权。授权使用本机浏览器；助手回复仍由机器人发送，既有消息不会改写。

By default, the bot sends synced messages. To show historical user messages under your own identity, grant the optional user scopes above, copy the local callback URL from Remote into the app's redirect URL list, and authorize in your local browser. Assistant replies still come from the bot, and existing messages are not rewritten.

授权按应用和操作者隔离，可在面板关闭代发或清除本机授权。清除凭据后，已安排但尚未发送的本人身份消息会等待重新授权，不会自动改成机器人身份。此功能不需要公网 OAuth 回调服务。

Authorization is isolated by app and operator. You can turn off user sends or clear local authorization in the panel. Already planned user-identity messages wait for renewed authorization if credentials are cleared; they are not silently switched to bot identity. This feature does not require a public OAuth callback service.

投递、隐私与限制 / Delivery, privacy, and limits

群内历史按原记录顺序发送；飞书消息的系统发送时间仍是同步时刻，正文中的时间才是 Codex 原记录时间。首次建群在选定历史投递完成后邀请本人入群。同步途中断线会保留进度，/sync 可补齐新记录；已发送的旧消息不会原地重排。

History is sent in source order. Feishu's system timestamp remains the time of delivery; timestamps in the content reflect the original Codex records. Initial group creation invites the operator after selected history is delivered. Interrupted sync retains progress, and /sync catches up new records; previously sent messages are not reordered in place.

消息、图片和文件会离开本机并进入你配置的飞书租户。只有已绑定的本人能操作机器人；本地文件自动发送按类别开关控制，/files 只列该会话历史中可见的本地引用。请在同步包含敏感内容的会话前检查飞书应用可用范围、群成员和文件策略。

Messages, images, and files leave your Mac for the configured Feishu tenant. Only the bound operator can control the bot. Automatic local-file sends obey category switches, and /files lists only local references visible in that session's history. Check the app's availability scope, group membership, and file policy before syncing sensitive sessions.

图片输入支持 PNG、JPEG、WebP 和 GIF，单张最多 10 MiB、一条最多 10 张且合计最多 30 MiB；一般文件附件最多 20 MiB。图片回复需要本机可用的 Chrome、Edge 或 Chromium。审批与用户问题可远程处理；未支持的交互需回 VS Code 完成。

Image input supports PNG, JPEG, WebP, and GIF, up to 10 MiB per image, ten images and 30 MiB per message. Ordinary file attachments are limited to 20 MiB. Image replies need local Chrome, Edge, or Chromium. Supported approvals and user questions can be handled remotely; other interactions must be completed in VS Code.

Remote 不是逐 token 流式转发器：它按 Codex 已落盘的可见消息同步，网络、图片渲染、飞书限流和前方积压都可能增加等待时间。面板区分 Bridge、本机后台和飞书长连接状态；对于明确失败的投递可修复后重试，结果未知的投递必须先在飞书核对。

Remote does not stream tokens. It syncs visible Codex messages after they are written locally, so network delays, image rendering, Feishu rate limits, and earlier queued sends can add latency. The panel separates Bridge, local-process, and Feishu connection status. You can retry definitely failed sends after fixing the cause; uncertain sends require checking Feishu first.

选择“立即调整方向”或“发送到 Codex 排队”后，Remote 会立即发起本群的提交提示，同时提交给 Codex。成功或失败回执按顺序跟随提示；这些回执不等待历史宽图渲染。输入已经有结果后，过时的“正在提交”不会在重连时补发。明确的输入界面未就绪错误表示消息没有提交，仍可从原卡片选择排队或取消。

Choosing Steer now or Queue in Codex immediately starts a submission notice in the same group and submits the input to Codex. Success or failure follows that notice in order, independently of historical image rendering. Obsolete submission notices are not replayed after reconnecting. A definite renderer-not-ready refusal means no input was submitted; the original card can still queue or cancel it.

源码构建与安装包 / Building and installation packages

在仓库根目录安装依赖后，执行 npm run package。脚本会自动编译，并按当前插件名称和版本生成 release/codex-remote-<version>.vsix。所有历史安装包都保留在 release/ 并由 Git 管理；发布修改时先升级版本号，脚本会拒绝覆盖已有版本。release/ 不会被嵌套打包进插件。

After installing dependencies in the repository root, run npm run package. The script builds the extension and writes release/codex-remote-<version>.vsix using the current package version. Historical installers remain in release/ under Git management. Bump the version before packaging changes; the script refuses to overwrite an existing installer. The release directory is excluded from the extension package.

npm ci
npm run package

许可证 / License

MIT。Codex Remote 与 Codex IO Bridge 是配合使用的独立 VS Code 扩展；飞书与 Codex 的账号、应用权限及服务条款仍分别由对应平台管理。

MIT. Codex Remote and Codex IO Bridge are separate VS Code extensions designed to work together. Feishu and Codex accounts, app permissions, and service terms remain governed by their respective platforms.

Codex Remote · 飞书

koupualen