RocYan98/CodexBoard · 上手攻略
- 仓库：RocYan98/CodexBoard
- 链接：https://github.com/RocYan98/CodexBoard
- 分类：Mac 任务看板 · Codex 控制层
- 作者：Jay
- 更新：2026-09-19
这是什么
CodexBoard 是一个 macOS 桌面应用，将项目任务看板与本机 Codex 连接起来。它的核心用途是：让你用看板（Kanban）的方式管理任务，把任务提交给本机 Codex 执行，然后在看板里实时查看进度、处理审批和补充信息——相当于给 Codex 加了一层任务管理层。
项目支持两种接入方式：Web 浏览器（ HTTPS 登录） 和 飞书（Lark/Feishu）。两种方式可同时启用，共用同一份看板和本机 Codex 数据。当前版本为 v0.1.11（预览版），仅支持 Apple Silicon Mac + macOS 13+，不支持 Intel Mac、Windows 或 Linux。
⚠️ CodexBoard 不是通用项目管理工具，它的设计目标高度聚焦在"用看板控制 Codex 执行"这一件事上。
解决什么问题
Codex 本身是一个对话式编程 Agent，执行单位是"对话"——没有任务状态管理、没有看板视图、没有审批节点。当你有一个大型重构需求时，用 Codex 只能开一个长对话自己跟进，无法和其他人协作、无法拆分任务、无法追踪哪些做完哪些没做。
CodexBoard 填补了这个空白：
1. 任务化 Codex 执行 把需求拆成看板任务，每个任务对应一次 Codex 执行（或继续）。任务有状态（待办/进行中/已完成）、优先级、标签、评论、附件。
2. 审批节点 Codex 执行过程中需要人介入时（如确认改动范围、补充需求），任务会暂停等待审批，而不是在对话里反复确认。
3. 远程监控 通过 Web 浏览器（公网 HTTPS）或飞书移动端，可以远程查看 Codex 执行进度，在手机上处理审批、补充信息。
4. Agent 自动化操作
配套的 manage-codexboard Skill 可安装到 Codex，让 Codex 自己查询和操作任务看板，实现"任务驱动型 Agent 工作流"。
快速安装
系统要求
| 要求 | 说明 |
|---|---|
| macOS 版本 | macOS 13（Ventura）或更新版本 |
| CPU 架构 | 仅 Apple Silicon（M1/M2/M3/M4 系列）；Intel Mac 不支持 |
| Codex | 已安装并在 Mac 上登录，可以正常使用 |
| 网络（可选） | 公网 frp 隧道服务（用于 Web/飞书远程访问） |
| 飞书（可选） | 飞书客户端 + 自建应用（仅飞书接入方式需要） |
安装步骤
1. 下载安装包
前往 Releases 页面，下载 CodexBoard-VERSION-macos-arm64.dmg（Source code 压缩包不是安装包）。
推荐同时下载 .dmg.sha256 文件做完整性校验：
# 在两个文件所在目录执行
shasum -a 256 -c CodexBoard-0.1.11-macos-arm64.dmg.sha256
# 显示 OK 表示校验通过
2. 安装应用
打开 DMG，将 CodexBoard.app 拖入 /Applications（应用程序）文件夹，然后从应用程序中打开。
⚠️ 当前版本尚未完成 Apple Developer ID 签名和公证。首次打开可能被 macOS 拦截。确认下载来源可信后，按 Apple 官方说明 处理，不需要关闭系统的整体安全检查。
3. 完成设置引导
首次启动会显示"使用引导"，按页面提示依次完成： - 填写 frp 隧道配置（用于远程访问） - 选择 Web 或飞书流程（或两者同时） - 配置 Web 账号或飞书应用凭据 - 验证 Codex 连接状态
核心用法
1. Web 看板访问
配置好 HTTPS 公网入口（frp 隧道 + 域名 + DNS）后： 1. 在 CodexBoard 应用中创建 Web 账号（应用设置 → Web 账号） 2. 密码 8–256 位，仅本机可创建，网页端不提供公开注册 3. 在浏览器打开自己的公网地址，用账号登录
⚠️ Web 账号密码登录不支持 HTTP/TCP 明文入口，必须配置 HTTPS。HTTPS 入口还需要公网 443 能到达本机 Caddy。
2. 飞书接入
- 在飞书开发者后台创建企业自建网页应用
- 填写 App ID 和 App Secret 到"连接配置"
- 按引导设置桌面与移动主页、H5 可信域名和重定向 URL
- 开通"获取用户 user ID"权限（
contact:user.employee_id:readonly） - 在飞书后台发布版本并设置可用范围
飞书登录验证通过的用户可以操作同一看板。请按实际需要设置应用可用范围。
3. 在 Codex Desktop 管理项目
- 在 Codex Desktop 中打开要管理的项目
- 在 CodexBoard 看板中选择同步出的项目
- 创建任务并描述需求
- 发起 Codex 执行后，在任务详情查看进度、结果、审批和待补充输入
- 执行结束后检查结果并验收
4. 移动端 Remote
通过飞书移动端或移动浏览器访问看板： - 实时查看 Codex 流式输出 - 处理审批节点 - 发送附件和图片补充执行所需信息 - 查看代码 diff 并审查改动
5. Codex Skill 安装（manage-codexboard）
配套 Skill 让 Codex 通过应用内置命令行查询、修改任务，无需克隆源码或安装 Node.js。
首次启动且未安装时，应用会提示安装到 Codex（~/.agents/skills/manage-codexboard）。也可在 应用设置 → Agent Skill 中手动安装。
安装后，在 Codex 中使用：
请使用 $manage-codexboard，先查看我的项目和任务，再帮我处理指定任务。
⚠️ Skill 安装或浏览器登录不等于已授权 CLI。CLI 操作需要先在授权页配对：Web 用户在浏览器授权页登录确认；飞书用户在飞书看板中确认。
6. 数据存储位置
配置、数据库和附件保存在：
~/Library/Application Support/CodexBoard/
⚠️ 升级首次启动时，若新目录尚不存在，应用会自动迁移已有数据。正常替换应用会保留数据。不要把这个目录当安装缓存清理，删除会影响配置和任务数据。
典型适用场景
| 场景 | 为什么适合 CodexBoard |
|---|---|
| 大型重构需求管理 | 把重构拆成多个任务，每个任务一次 Codex 执行，看板追踪整体进度 |
| Codex + 团队协作 | 飞书接入后，非技术成员可通过飞书审批和补充信息 |
| 远程工作流 | 出门在外通过手机飞书查看 Codex 执行进度，无需远程桌面 |
| Agent 自动化任务编排 | 通过 manage-codexboard Skill 让 Codex 自己查询和管理任务 |
| 需求变更管控 | 审批节点确保每次代码改动经过人工确认 |
坑与注意
⚠️ Apple Silicon 独占 - 当前安装包不支持 Intel Mac、Windows 或 Linux - 如果你用的是 Intel Mac，这个应用目前无法使用
⚠️ 公网访问依赖配置 - Web 方式需要配置 frp 隧道（需要自己的 frp 服务端或服务商） - HTTPS 入口需要公网 443 端口可达 + DNS 配置 - HTTP 和 TCP 模式使用明文 HTTP，会话内容不经过 HTTPS 加密，不推荐生产环境使用 - 不清楚域名解析不代表能读取看板数据——未登录请求受保护，Web 账号必须由本机创建
⚠️ 未完成 Apple 签名公证 - macOS 可能报告"无法验证开发者" - 确认来源可信后按 Apple 官方说明处理，不需要关闭系统安全检查
⚠️ 飞书应用发布状态 - 飞书凭据检查通过只代表凭据可用，不代表应用已发布或可用范围正确设置 - 发布状态、可用范围和实际登录都需要在飞书中确认
⚠️ Codex 连接状态 - 基础登录检查不保证在线请求和 API 额度可用 - Codex 检查未通过时先在 Codex Desktop 确认登录和项目状态
⚠️ 账号安全 - Web 账号共用看板，新建任务归当前登录用户，目前不提供按项目隔离的账号权限 - 只给信任的人创建账号；停用或重置密码会使已有登录和 CLI 配对失效
⚠️ 退出行为 - 关闭窗口：应用保留在菜单栏，服务继续运行 - 退出应用或点击停止服务：本机服务停止，浏览器和飞书看板暂时无法访问 - Mac 关机/休眠/断网：公网访问中断，使用 Remote 功能时需要保持 Mac 在线
与同类对比
| 维度 | CodexBoard | GitHub Projects | Linear | 飞书任务 |
|---|---|---|---|---|
| 核心定位 | Codex 执行控制 + 看板 | 通用项目管理 | 通用项目管理 | 飞书内置任务 |
| 平台 | 仅 macOS Apple Silicon | 通用 | 通用 | 通用 |
| Codex 集成 | 原生，任务即 Codex 对话 | 无 | 无 | 无 |
| 飞书集成 | 是（双向） | 否 | 否 | 原生 |
| 移动端 Remote | 是（通过飞书） | 否 | 是（独立 App） | 是 |
| Agent Skill | manage-codexboard | 无 | 无 | 无 |
| 自托管 | 是（本地 Mac） | GitHub.com | cloud/自托管 | 飞书云 |
| 成熟度 | v0.1.11 预览版 | 正式版 | 正式版 | 正式版 |
一句话总结：CodexBoard 是目前唯一专门为 Codex 设计的任务看板工具，如果你用 Codex on Mac 且希望用看板方式管理任务和协作，它是最匹配的选择；如果只需要通用项目管理，飞书任务或 GitHub Projects 更成熟。
推荐结论
CodexBoard 精准填补了"Codex 执行缺乏任务管理层"的空白：本地看板 + 飞书双入口 + 审批节点 + 移动端 Remote，让 Codex 从单人对话工具变成可协作的任务执行系统。适合 Apple Silicon Mac 用户、飞书协作团队、以及希望通过任务看板给 Codex 工作流增加结构化管控的开发者。当前 v0.1.11 仍为预览版，生产使用前建议关注 Release 更新。