AppChat 是 Codex App Server 的本机多渠道、多机器人、多项目网关。一个共享核心同时服务 WebUI、Telegram 和飞书；渠道只负责交互，项目、会话、历史、模型、审批、排队、附件、文件浏览和状态均复用 BridgeCore。源码、会话和密钥留在用户电脑，WebUI 与 App Server 只监听回环地址。
支持三种部署形态：
| 使用环境 | 首次一键部署 | 日常启动 WebUI | 后台机制 | 验证状态 |
|---|---|---|---|---|
| Windows 10/11 + WSL 2 | deploy-appchat-wsl.bat（兼容旧名 deploy-appchat.bat） |
start-webui-wsl.bat（兼容旧名 start-webui.bat） |
WSL systemd 用户服务 | 当前维护环境完整实测 |
| 纯 Windows 10/11 | deploy-appchat-windows.bat |
start-webui-windows.bat |
Windows 任务计划程序 | Windows CI 校验；需要真机完成账号/渠道验收 |
| macOS 13+ | deploy-appchat-macos.command |
start-webui-macos.command |
macOS LaunchAgent | macOS CI 校验；需要真机完成账号/渠道验收 |
推荐 Windows 用户优先选择 Windows + WSL。它是当前最完整的生产路径，支持 WSL/Windows 项目转换、Windows 与 WSL VS Code Codex 会话同步，以及已部署的 systemd 自动恢复。纯 Windows 模式不会读取 WSL 内的 Codex 会话数据库。
项目目录示例：
- WSL：
/home/用户名/code，Windows 中可通过\\wsl.localhost\发行版\home\用户名\code查看。 - 纯 Windows：
C:\code、D:\projects等原生绝对路径，不转换成/mnt/c。 - macOS：
/Users/用户名/code等原生绝对路径。 - 其他目录：通过 WebUI 或
/path <绝对路径>登记已有项目；EXTRA_PROJECT_ROOTS可增加允许新建项目的根目录。
- 扫描、搜索、切换 WSL 和 Windows 根目录下的项目
- 从聊天中新建项目并自动执行
git init - 每个 WebUI、Telegram/飞书聊天分别记住当前项目、当前会话和订阅会话
- 同时运行多个项目；同一会话的消息自动串行，避免两个通道重复启动任务
- 查看和恢复 Codex CLI、WSL VS Code 插件产生的项目会话
- 流式显示进度，处理命令/文件审批和 Codex 提问
- 共享美观展示层：运行、完成、失败、审批和历史使用稳定视觉主题，按钮按用途分组
- Telegram 使用安全 HTML 排版，并在 Codex 处理期间持续显示“机器人正在输入”状态
- 查看 Git Diff、上下文 Token 用量以及账号/中转站可用额度
- Telegram 与 VS Code/Codex 双向同步文字、图片、音频、视频和普通文件；Codex 查看或生成的验收图片会推送到 Telegram
- 每个对话使用独立有界顺序队列；慢渠道、平台限流或网络重试不会阻塞其他机器人和 Codex 事件
- 支持任务排队、会话归档、重命名、压缩、Fork、Review、Goal、Fast、Plan 和 Codex 扩展查询
- 超长回复自动发送预览与完整 Markdown；素材使用流式限额、原子落盘和图片内容校验
- App Server 与聊天 Gateway 独立常驻，日常重启渠道不会中断正在运行的 Codex Turn
- 查看 Git 分支、未提交文件和最近一次提交
- WebUI 只监听本机回环地址，Telegram 使用长轮询，飞书使用 WebSocket 长连接，均不需要公网端口、域名或 webhook
- 旧版单 Telegram 状态文件启动时自动迁移，不丢会话映射
所有平台都需要：
- 从可信来源取得完整项目目录；不要只复制某个 BAT 或 command 文件。
- 安装 Git。
- 安装 Node.js 22.12 或更高版本，并确认终端中
node -v、npm -v可用。 - 首次部署会运行
npm install、中文配置向导和 WebUI 构建。准备好 Telegram/飞书凭据也可以稍后在 WebUI 添加。 - Codex 必须在运行 AppChat 的同一环境登录。密钥只写入本机
.env；不要上传或提交.env、data/。
安装依赖后，在对应环境运行：
npx codex loginWSL 模式必须在 WSL 终端登录；纯 Windows 必须在 PowerShell/CMD 登录；macOS 必须在 Terminal 登录。三个环境的登录状态与会话目录不是自动互通的。
- Windows 10 22H2 或 Windows 11。
- 管理员 PowerShell 执行
wsl --install，重启后完成 Ubuntu 初始化。 - 在 WSL 中安装 Node.js 22.12+、Git，并运行
npx codex login。 - 项目可以放在 WSL 文件系统（性能更好）或 Windows 磁盘；BAT 会从自身位置定位项目。
双击：
deploy-appchat-wsl.bat
兼容入口 deploy-appchat.bat 做同一件事。脚本会：
- 检查
wsl.exe和 WSL 是否完成安装。 - 检查 WSL 内 Node.js 版本。
- 在 WSL 中运行
npm install。 - 缺少
.env时运行npm run setup。 - 构建 WebUI。
- 安装并启动
appchat-app-server.service与appchat.service。 - 检查 App Server、WebUI、全部 Telegram 机器人和飞书长连接。
- 打开 WebUI。
命令行等价操作：
cd /path/to/appchat
npm install
npm run setup
npm run deploy双击 start-webui-wsl.bat；旧入口 start-webui.bat 继续可用。它只唤醒已安装服务、等待 WebUI 就绪并打开浏览器，不会重复安装依赖。
- AppChat、Codex App Server、Telegram、飞书和 WebUI 全部由 Windows 原生 Node.js 运行。
- 项目路径保持
C:\...、D:\...；不能直接使用 WSL 的/home/...会话。 - 后台注册两个当前用户的任务计划：
AppChat App Server与AppChat Gateway，不要求管理员权限，登录 Windows 后自动启动。 - Windows 原生 Codex/VS Code 会话可以使用相同项目路径；它们不会自动合并 WSL 中已有的会话。
- 安装 Windows x64/arm64 对应的 Node.js 22.12+ 和 Git，重新打开终端确认 PATH 生效。
- 在项目目录运行
npx codex login。 - 双击
deploy-appchat-windows.bat。 - 首次出现配置向导时按提示选择渠道和默认项目目录。
- 等待窗口显示
DEPLOY_RESULT=success，浏览器会自动打开。
部署器使用 PowerShell 注册任务计划，不会调用 wsl.exe。后台日志位于：
data\logs\native-app-server.log
data\logs\native-gateway.log
data\deploy-status.log
只做安全校验、不安装任务计划：
deploy-appchat-windows.bat -ValidateOnly双击 start-webui-windows.bat。脚本会启动两个任务计划、等待 App Server/WebUI，再打开浏览器。若提示找不到任务，请重新运行首次部署文件。
- macOS 13 或更高版本。
- 安装 Xcode Command Line Tools：
xcode-select --install。 - 通过 Node.js 官网或 Homebrew 安装 Node.js 22.12+。
- 在 Terminal 进入项目目录，运行
npx codex login。
Finder 双击 deploy-appchat-macos.command，或在 Terminal 运行：
./deploy-appchat-macos.command脚本会安装依赖、运行首次配置、构建 WebUI，并在 ~/Library/LaunchAgents/ 安装：
com.appchat.app-server.plist
com.appchat.gateway.plist
两个 LaunchAgent 会在当前用户登录后自动恢复。日志位于 data/logs/，最终结果位于 data/deploy-status.log。
如果 Finder 因下载隔离阻止运行，只对确认来源可信的项目执行：
xattr -d com.apple.quarantine deploy-appchat-macos.command start-webui-macos.command
chmod +x deploy-appchat-macos.command start-webui-macos.command只验证脚本、LaunchAgent plist 与 WebUI 构建，不安装服务：
./deploy-appchat-macos.command --validate-only双击 start-webui-macos.command。它会唤醒两个 LaunchAgent、等待 WebUI 就绪，然后使用默认浏览器打开页面。
默认地址：http://127.0.0.1:4580。端口可在“系统”页修改；主机只允许 127.0.0.1、localhost 或 ::1，不能配置成公网监听。
- 输入文字并按 Enter 发送；Shift+Enter 换行。
- 回形针可上传图片、音频、视频和文件。
- “控制面板”可视化打开项目、会话、模型、思考强度、文件浏览和审批操作。
- Codex 运行中发送的新消息默认作为 steer 引导；使用
/queue可明确排到下一轮。
- “项目”扫描当前系统项目根目录和额外根目录。
- “文件浏览”是只读、按 WebUI scope 隔离的共享文件浏览器，支持目录分页、树、名称搜索、文本预览和下载。
- “会话/历史”读取真实 App Server 会话，包括 CLI、VS Code 和 App Server 来源。
- 常用命令可在“系统”页增删，保存在当前浏览器。
这里集中展示模型、思考强度、Fast、Goal、Plan、用量、Skills、MCP、Plugins、权限、规则、Git、Diff 和运行中任务。点击卡片会通过共享 BridgeCore 执行，与 Telegram/飞书命令行为一致。
渠道页由三部分组成：
- 已配置渠道：逐个列出 Telegram 主机器人、所有额外机器人和飞书应用；“刷新状态”会用服务端现有密钥调用官方接口。浏览器只接收公开名称、用户名、检测结果、默认项目和安全链接，不接收 Token、Secret 或临时访问令牌。
- 快捷入口：Telegram 显示“打开机器人”，直接进入
t.me/<username>；飞书在取得机器人 Open ID 时显示“打开机器人”，并始终提供“管理应用”打开飞书开放平台。 - 添加与设置：点击“一键添加”进入完整创建、权限、凭据验证、授权和部署向导；高级手动设置用于迁移已有配置。平台错误会明确显示，不把“已配置”静默标成“在线”。
保存渠道配置后，需要在“运维”运行部署或重新执行对应平台部署文件才能让后台进程读取新 .env。
- 设置默认工作目录、当前系统项目根目录、WSL/Windows 兼容根目录和额外根目录。
- 设置模型、沙箱、审批策略、代理和 WebUI 端口。
- 密钥字段为只写：已有值不会返回浏览器，留空会保留原值。
- 可运行静态检查、自动测试、协议检查、依赖审计和部署。
- WSL 正式部署会使用独立 systemd 任务，即使当前 WebUI 因重启短暂断开，部署仍会继续并写入
data/deploy-status.log。 - 纯 Windows/macOS 请优先使用对应的一键部署文件更新后台任务定义。
- WebUI 设置仅允许同源、本机回环访问，并使用 HttpOnly 会话 Cookie。
.env、Token、Secret、授权用户和代理凭据不会通过配置摘要返回前端。- 文件上传限制大小、校验图片文件头，使用
.part原子落盘并在失败时清理。
保留 .env 和 data/，更新源码后执行当前平台的首次部署文件即可。不要跨平台复用包含绝对路径的 .env；迁移系统时建议重新运行配置向导，只手动迁移必要的渠道凭据和项目路径。
配置向导会用中文逐步询问 Telegram 和飞书。Token、App Secret 只输入到本机终端，内容不会回显；Unix 系统设置 .env 为 600。不要把 .env 发给别人或提交到 Git。
- 在 Telegram 打开官方
@BotFather。 - 发送
/newbot，按提示创建机器人。 - 运行
npm run setup，输入 BotFather 给出的 Token。 - 向导会生成一次性配对码；启动后发送
/pair 配对码，机器人会自动识别并授权你的数字用户 ID。
机器人只接受已授权账号的私聊，不接受群聊。
- 打开 飞书开放平台，新建“企业自建应用”。
- 启用“机器人”能力。
- 在权限管理添加消息读取与机器人发送权限，至少包含
im:message和im:message:send_as_bot对应权限；再添加im:message.reactions:write_only，用于任务运行期间显示和清理飞书原生Typing动态表情。 - 在“事件与回调”中选择“使用长连接接收事件”，添加
im.message.receive_v1。 - 如需使用审批按钮，添加
card.action.trigger回调。 - 创建并发布应用版本，把机器人加入可用范围。
- 运行
npm run setup，在终端输入 App ID 和 App Secret。 - 启动服务后私聊机器人，发送向导显示的
/pair 配对码。Open ID 会自动保存在本机，无需使用第三方查 ID 机器人。
飞书群聊默认关闭。开启 FEISHU_ALLOW_GROUPS=true 后，仍只响应授权用户明确 @机器人 的消息。
/help 查看帮助
/panel 打开按钮控制面板（也支持 /menu）
/roots 查看允许新建项目的根目录
/projects [关键词] 浏览或搜索项目
/project <序号|名称|绝对路径> 切换项目
/project_new <根目录ID> <名称> 新建项目并 git init
/path <已有绝对路径> 登记并切换任意已有目录
/files [文件夹路径] 逐级浏览当前项目或指定文件夹
/file <文件路径> 预览或下载指定文件
/tree [深度1-5] [文件夹路径] 查看简化文件夹树
/find <名称关键词> 搜索当前浏览目录中的文件和文件夹
/threads 查看当前项目的历史会话
/history [序号|thread_id] 查看会话历史（不会自动切换）
/use <序号|thread_id> 切换并订阅会话
/new [会话名] 新建会话
/queue <要求> 排到当前任务完成后作为下一轮执行
/rename <名称> 重命名当前会话
/compact 压缩当前会话上下文
/fork [名称] 复制当前会话并切换
/archive 归档当前会话
/archived 查看归档会话
/unarchive <序号|thread_id> 恢复归档会话
/review [uncommitted|branch|commit] 启动 Codex 代码审查
/goal [set <目标>|clear] 查看、设置或清除 Goal
/models 查看并选择当前可用模型
/model <序号|模型ID> 选择模型
/effort [强度] 查看或选择模型思考强度
/fast [on|off|status] 切换 Fast 模式
/plan 查看 App Server 实时 Plan
/skills [refresh] 查看项目和用户 Skill
/mcp 查看 MCP Server
/plugins 查看本机已安装 Plugin
/permissions 查看当前权限与可选档案
/rules [init|check] 生成或检查项目安全命令规则
/watch <序号|thread_id> 订阅另一个会话的进度
/unwatch <序号|thread_id> 取消订阅
/running 查看已订阅的运行中任务
/status 查看服务、项目和会话状态
/where 同时查看友好路径和 WSL 执行路径
/git 查看 Git 状态
/diff 查看未提交代码 Diff
/usage 查看当前会话上下文与 Token 用量
/limits 查看账号或中转站额度（取决于 Provider 支持）
/more 查看高级命令
/stop [thread_id] 中止任务
/refresh 刷新项目并重连 App Server
文件浏览是共享核心功能，Telegram 使用内联按钮，飞书使用交互卡片，权限和结果保持一致。整个功能只读，不会因为浏览、预览或下载而修改电脑文件。
飞书和 Telegram 都提供共享按钮控制面板。飞书另外启用机器人原生菜单“开发 / 对话 / 设置”，可直接打开项目、会话、文件、模型和思考强度，状态等操作在控制面板卡片中一键进入；项目等长列表按页展示并点击切换。输入“查看项目”“切换对话”“选择模型”等简短中文也会直接打开对应卡片，不再生成需要手输命令的纯文本列表。菜单布局修改后运行 npm run feishu:menu:sync 同步并发布飞书应用。
控制面板按“工作区 / 对话 / 配置 / 工具”分组，更多工具中可直接打开 Git、代码改动、代码审查、执行计划、上下文压缩和连接刷新。任务完成后，最终回复只保留“文件 / Git / 对话 / 面板”四个高频入口，并在页脚显示用时、模型、思考强度和缓存命中等可用信息，避免每条消息堆满按钮。
任务运行中发送引导要求时，AppChat 会固定引导前的过程消息，在你的引导消息之后新建处理段，并把最终回复更新到新段中。这样 Telegram 和飞书的消息顺序与 Codex 原生时间线一致。Shell 命令、文件列表和工具调用等技术过程默认收进折叠区：飞书使用原生折叠面板，Telegram 使用可展开引用；正文只显示“正在运行命令”等简短状态，最终回复不保留这些过程细节。
常用示例：
/files
/files D:\dapaoAI\my-project
/files \\wsl.localhost\Ubuntu-26.04\home\upboy\code
/tree 3
/tree 2 D:\dapaoAI
/file src/index.js
/find package.json
功能与限制：
/files默认打开当前项目；也接受 Windows、WSL、WSL UNC 和其他已有绝对路径。相对路径以当前项目或当前浏览根目录为边界，不能通过..悄悄越界。- 文件夹按“目录优先、名称排序”显示，每页 10 项，支持上级、浏览根目录、翻页、刷新以及显示/隐藏依赖和特殊目录。
/tree支持 1–5 层，最多展示 300 项；不会递归展开.git、node_modules、构建目录和缓存目录。/find按名称递归搜索当前浏览目录，最多访问 5,000 项、返回 50 项并分页；自动跳过隐藏、依赖、构建、缓存和符号链接目录。- UTF-8 文本在聊天中按页预览，并显示大小、修改时间和行范围；预览中的 Token、私钥、JWT、API Key 和认证字段自动脱敏。
- 图片、音频和视频使用渠道原生预览；其他文件可以下载原文件。单个下载文件上限为 50 MB。
.env、私钥、凭据、授权状态等敏感文件禁止预览和下载；内容检测到真实密钥特征时，也会拒绝发送原文件。- 不跟随最终符号链接，并校验真实路径仍位于本次浏览根目录，防止链接或路径穿越访问其他位置。
- 浏览状态按机器人和聊天隔离，按钮只保存短期服务端 ID，30 分钟过期；完整电脑路径不会写入按钮回调数据。
- 目录和文本翻页会尽量更新原消息，减少聊天刷屏；媒体预览和文件下载作为后续附件发送。
所有平台都把 Codex App Server 与 WebUI/Telegram/飞书 Gateway 分成两个后台进程，避免渠道重启中断正在运行的 Codex Turn：
- WSL：
appchat-app-server.service与appchat.servicesystemd 用户服务。 - 纯 Windows：
AppChat App Server与AppChat Gateway当前用户任务计划。 - macOS：
com.appchat.app-server与com.appchat.gatewayLaunchAgent。
部署定义始终使用当前仓库和 Node.js 的绝对路径，不嵌入开发者用户名。三个平台的最终健康结果都写入忽略版本控制的 data/deploy-status.log。WSL 的 npm run deploy 还会创建独立延时 systemd 单元，因此当前连接断开后仍能完成验证。
直接发送文字、图片、音频、视频或文件时：如果 Codex 正在处理，会自动作为“引导要求”加入当前任务；如果上一轮已经结束，则自动开始新任务。模型和思考强度由 App Server 动态提供，适配当前 Codex 账号或中转站，并从下一轮任务开始生效。
Telegram 消息会明确区分身份和阶段：从 VS Code 同步的要求标记为 👤 你的要求；处理中只保留一条 🧠 Codex 正在思考 动态消息，用于临时展示思考摘要、过程说明和当前工具操作；任务结束时，同一条消息会被 🤖 Codex 最终回复 完整替换，不残留思考过程或重复的“处理中”消息。
发送 /threads 后，每个会话都有“查看”和“继续”两个按钮。“查看”只读取历史，不改变当前会话；历史按每页 10 轮展示，可翻看更早记录，并过滤思考过程和工具日志。“继续这个对话”才会切换并订阅该会话。发送 /history 可直接查看当前会话。
路径按运行平台处理。WSL 能转换 Windows 盘符、WSL UNC 和 Linux 路径；纯 Windows 保留盘符/UNC；macOS 接受 POSIX 绝对路径并明确拒绝无法访问的 Windows 盘符。例如：
/project D:\dapaoAI\my-app
/path \\wsl.localhost\Ubuntu-26.04\home\upboy\other-project
/project_new wsl new-api
/project_new windows new-web
/path /Users/name/code/my-app
一个中央 App Server 可以同时加载多个项目和多个 thread。项目用 cwd 隔离，每个聊天作用域保存“每个项目最后使用的 thread”，所以从项目 A 切到 B 再切回来，会回到 A 原来的会话。
推荐规则：
- 不同项目并行：直接为每个项目创建/选择不同 thread，可同时工作。
- 同一项目不同任务：使用不同 thread；如果两项任务会修改相同文件，最好先创建 Git worktree，让每个任务使用不同目录，避免互相覆盖。
WebUI、Telegram、飞书和以后新增的渠道共用 BridgeCore。项目/会话切换、历史记录、引导模式、停止任务、模型与思考强度、处理中状态、最终回复、素材折叠、审批策略和跨端同步都只在核心实现一次；渠道适配器只负责平台消息、按钮和素材 API 的转换。
每个适配器必须通过 src/channel-contract.js 的启动契约，完整提供消息编辑、按钮、原消息回复、活动状态、附件收发、折叠素材和共享展示语义能力。缺少其中任何一项时服务会在启动阶段明确报错，避免某个渠道悄悄缺功能。新增渠道的实现与验收清单见 docs/channel-adapters.md。
多个 VS Code 窗口同步说明：
- WSL Remote 窗口和 Windows 原生窗口可连接同一个 WSL App Server。
- WSL 模式运行
npm run configure:vscode-windows可让 Windows VS Code 通过wsl.exe使用共享包装器；连接失败不会静默回退到隔离 Codex。 - 纯 Windows模式使用 Windows 原生项目路径和会话目录，不与 WSL 历史自动合并。
- 实时双向事件要求两个界面打开同一个 thread。Telegram 用
/threads和/use选择；VS Code 从历史中打开相同 thread。
Windows 独立 Codex 桌面客户端不会读取 VS Code 的 chatgpt.cliExecutable 设置，目前不能替代上述插件接入链路。只打开桌面客户端不会触发 VS Code 包装器；Telegram、飞书和共享 App Server 由 WSL 用户服务独立运行，不依赖任何 VS Code 窗口保持开启。
Telegram 私聊本身只有一个聊天作用域。需要同时盯住多个任务时，用 /watch 订阅多个 thread，用 /running 查看；用 /use 决定下一条普通消息发给哪个 thread。Telegram 和飞书也可以同时订阅同一个 thread，完成事件会广播到两个渠道。
- Telegram 可直接发送截图、图片、语音、音频、视频和普通文件，附带的说明文字会一起交给当前 Codex 会话。
- 图片和音频使用 Codex App Server 原生输入；视频和普通文件以本机文件引用进入会话，Codex 可按文件类型读取、抽帧或分析。
- VS Code 在同一 thread 中发送的图片、音频和文件会同步到 Telegram；Codex 验收时查看或生成的图片也会同步。
- 素材保存在本机
data/attachments，以便重启和恢复会话后仍可访问。Telegram 机器人单个素材下载上限为 20 MB，向 Telegram 回传单个文件上限为 50 MB。
- App Server 只允许
127.0.0.1、localhost或[::1]，配置成公网监听会拒绝启动。 - 新建项目只能是已配置根目录的直接子目录；
/path只能登记已存在目录。 - 没有项目删除命令，避免聊天误删源码。
- 审批消息会显示项目、环境、目录、thread 和操作内容；不理解时请选择拒绝。
- 飞书和 Telegram 都使用明确的用户允许列表；飞书配对码使用一次后，授权身份持久化在
data/state.json。 - WSL 模式中的 Windows 项目由 WSL 进程通过
/mnt/<盘符>修改，权限和性能遵循 WSL 挂载规则；纯 Windows 模式直接使用 NTFS 路径。
npm run check
npm test
npm audit
npm run protocol:check
npm run doctor跨平台部署器验证：
纯 Windows：deploy-appchat-windows.bat -ValidateOnly
macOS： ./deploy-appchat-macos.command --validate-only
WSL： npm run check && npm test && npm run deploy
仓库包含 .github/workflows/cross-platform-deploy.yml。用户手动提交并推送后，GitHub Actions 会分别在 windows-latest 和 macos-latest 检查原生脚本、路径语义、LaunchAgent plist 和 WebUI 构建。CI 不持有用户 Codex 登录、Telegram Token 或飞书 Secret，因此不能替代真机渠道连接验收。
当前维护环境可完整验证 WSL systemd 部署、App Server /readyz、WebUI、全部本机 Telegram 机器人和飞书长连接。纯 Windows/macOS 的真实任务计划/LaunchAgent、登录恢复和渠道联网，必须在对应真机至少执行一次首次部署，并以本机 data/deploy-status.log 中 DEPLOY_RESULT=success 为准。
常见问题：
/projects看不到D:\dapaoAI：先在 WSL 运行ls /mnt/d/dapaoAI，确认 D 盘已挂载。- 纯 Windows 提示找不到计划任务：重新双击
deploy-appchat-windows.bat，不要运行 WSL 版本。 - macOS 提示服务尚未安装：运行
./deploy-appchat-macos.command；用launchctl print gui/$UID/com.appchat.gateway查看状态。 - WebUI 打不开：先运行对应平台的
start-webui-*文件，再检查data/deploy-status.log和data/logs/。 - 飞书收不到消息：确认应用版本已发布、机器人在可用范围、事件使用长连接、权限已审批。
- Telegram 启动报冲突：同一个 Token 同时只能有一个长轮询进程，关闭旧进程再启动。
- App Server 未登录：在当前运行环境执行
npx codex login，不要在另一个系统环境登录后假设凭据会同步。 - 会话列表为空：路径必须与会话创建时的
cwd完全一致；启用共享包装器之前由 Windows 原生 Codex 创建的旧会话不在 WSL 状态库中。 - Windows VS Code 的 Codex 侧栏完全空白：运行
npm run configure:vscode-windows。这会让 Windows 通过 WSL 启动共享包装器，避免 Windows 直接执行/home/...路径失败。
核心协议按官方 Codex App Server 文档 实现：thread/list 按 cwd 查询，thread/resume 订阅事件，turn/start 和 turn/steer 发送消息。通道架构参考了 OpenClaw、Hermes Agent、Opendray 以及开源 Telegram Codex 桥接项目中的稳定路由键、通道能力、消息去重、串行处理和项目扫描思路；没有复制其代码。
可靠性层借鉴了 codex-channels 的有界事件队列、每 Conversation 顺序投递、关键输出保护、API 退避重试、安全错误边界、操作聚合、协议升级检查和独立 App Server 思路，并重写为 AppChat 的渠道无关实现。Telegram、飞书和以后新增的渠道统一经过同一可靠性层；现有多机器人、Windows/WSL、动态项目和全媒体能力保持不变。
WSL 访问官方文档时会自动使用 .env 中的 APPCHAT_PROXY_URL。运行 npm run docs:refresh 可一次性缓存 App Server 网页、Codex 总手册，并生成与本机 Codex 版本匹配的 App Server JSON Schema；结果保存在 data/docs/。
