简体中文 · English

连接项目与 Codex，让想法成为进展。

用户指南 · 给 Agent 的操作指南

CodexBoard 将项目任务看板与本机 Codex 连接起来。你可以整理项目和任务、提交需求、查看执行进度，并在需要时处理审批或补充信息。桌面应用负责启动和管理本机服务，看板可通过 HTTPS 浏览器账号登录，也可在飞书中使用；两种方式可以同时配置。

两种方式可同时启用，共用同一看板和本机 Codex。

• 按项目管理任务，通过仪表盘、看板和列表查看工作，维护状态、优先级、标签、评论和附件。
• 从任务中发起或继续 Codex 执行，查看进度、执行结果和需要你处理的审批。
• 在桌面或移动浏览器中用独立账号访问看板，无需登录飞书；也支持飞书桌面端与移动端。
• 在本机创建、停用 Web 账号或重置密码；Web 用户可作为任务负责人并以自己的身份评论。
• 管理项目分支和 worktree；连接配置、端口设置支持窗口自适应。
• 通过移动端 Remote 创建或继续 Mac 上的 Codex 对话，实时查看流式结果并处理审批。
• 从手机发送附件和图片、补充执行所需信息，查看代码 diff 并审查改动。
• 通过内置命令行工具，让已授权的 Agent 查询和管理任务。

本机服务与任务数据保存在你的 Mac 上；账号登录、公网访问和 Codex 执行仍需要对应的网络服务。

在飞书自建应用中管理任务；移动端 Remote 支持 Codex 对话、流式结果、附件、审批与代码审查。

桌面看板	移动看板	Remote

通过 HTTPS 和本机创建的 Web 账号登录。点击缩略图可查看大图。

桌面浏览器	移动浏览器

安装包已包含 Node.js、看板前后端、Codex 桥接、SQLite 组件、Caddy 和 frp 客户端。无需另装 Node.js、Docker、Rust 或开发工具。Codex 和公网 frp 服务端需要自行准备；使用飞书方式时另行准备飞书客户端与自建应用。

1. 在 v1.0.0 Release 下载 CodexBoard-1.0.0-windows-x64-setup.exe 和对应 .sha256，用 PowerShell Get-FileHash -Algorithm SHA256 .\CodexBoard-1.0.0-windows-x64-setup.exe 核对校验值。
2. 正常退出旧 CodexBoard，运行安装器。默认程序目录为 %LOCALAPPDATA%\CodexBoard Desktop，数据在独立的 %LOCALAPPDATA%\CodexBoard，不要删除数据目录。已有 Windows Test 版本应先退出；新包沿用数据目录，不要同时启动两套服务。
3. 安装器按需下载 WebView2；启动后在应用中完成连接配置、Web 账号或飞书设置。Codex Desktop 仍需自行安装并登录。
4. Windows 当前通过下载新版安装器升级，不提供应用内自动安装更新。安装包尚无 Authenticode 签名；若系统拦截，请核对来源与校验值，由用户处理提示，不关闭系统保护。

1. 打开本仓库的 Releases 页面，在所选版本的 Assets 中下载 CodexBoard-版本号-macos-arm64.dmg。Source code 压缩包不是安装包。
2. 如果已安装旧版，先结束或妥善处理正在执行的看板任务，再从菜单栏正常退出 CodexBoard。
3. 打开 DMG，将 CodexBoard.app 拖入 Applications（应用程序）。
4. 从“应用程序”打开 CodexBoard，随后推出安装磁盘。

如需校验下载完整性，同时下载对应的 .dmg.sha256 文件，在两个文件所在目录执行。以 1.0.0 为例：

shasum -a 256 -c CodexBoard-1.0.0-macos-arm64.dmg.sha256

显示 OK 表示文件与发布者提供的校验值一致。

当前版本尚未完成 Apple Developer ID 签名和公证。 首次打开可能被 macOS 拦截。确认下载来源可信后，按 Apple 官方说明处理；不需要关闭系统的整体安全检查。

打开应用中的 使用引导，按页面完成以下步骤。

从你的 frp 服务商或自建服务端获取完整的 frpc.toml，在“连接配置”中粘贴。隧道应转发到这台 Mac 的 127.0.0.1 和应用显示的 Caddy 本机端口。

应用会从隧道配置自动识别公网入口。请使用自己的隧道配置，不要直接复制他人的认证参数或公网地址。

DNS 解析已包含在这一步中，应用会根据隧道配置显示对应说明：HTTPS（以及 HTTP）域名入口需要按服务商要求配置 DNS；TCP 公网 IPv4 入口无需 DNS，直接使用公网地址。需要解析时，参考这一步显示的域名和解析目标。

HTTPS 入口需要公网 443 能到达本机 Caddy。HTTP 和 TCP 模式使用明文 HTTP，会话和业务内容不经过 HTTPS 加密。

使用引导可选择 Web 或飞书流程，这只切换引导内容。“连接配置”可以同时保存飞书与公网配置，无需二选一。

1. 配置 HTTPS 公网入口，保存配置并启动或重启服务。Web 账号密码登录不支持 HTTP/TCP 明文入口。
2. 打开 应用设置 → Web 账号（或连接配置中的“管理 Web 账号”），创建账号、显示名称和密码；密码为 8–256 位。仅本机可创建账号，网页不提供公开注册。
3. 在浏览器打开自己的公网地址，用该账号登录。仅使用 Web 时，飞书 App ID 和 App Secret 均可留空。

引导会自动检查运行配置和是否存在启用的 Web 账号；检查通过不代表已完成真实浏览器登录，仍需实际登录确认。

Web 账号是可执行任务的受信任用户，不是只读访客。各账号共用看板，新建任务归当前登录用户，评论署该用户；目前不提供按项目隔离的账号权限。只给信任的人创建账号。停用或重置密码会使该账号已有浏览器登录和 CLI 配对会话失效。

在 飞书开发者后台创建企业自建网页应用，将 App ID 和 App Secret 填入“连接配置”。

按使用引导中的地址设置桌面与移动主页、H5 可信域名和重定向 URL，并开通“获取用户 user ID”权限（contact:user.employee_id:readonly）。随后在飞书后台发布版本并设置可用范围。

飞书应用凭据检查通过，只表示凭据可用；发布状态、可用范围和实际登录仍需要在飞书中确认。任何通过飞书登录验证的账号均可操作同一看板，请按实际需要设置应用可用范围。

确认 Codex 已在这台 Mac 上安装并登录，再运行引导中的检查。

检查不会自动保存配置。 完成填写后保存配置；实际发生修改时，选择立即重启服务或稍后手动重启。未修改内容时不会新增重启提醒。

当“服务概览”显示后端、Caddy 和公网隧道正常后，通过浏览器 Web 账号或飞书完成实际登录并查看看板。若同时启用两种入口，分别验证登录。

在 Codex Desktop 中管理项目，在看板选择同步出的项目，创建任务并描述需求。发起 Codex 执行后，可以在任务详情查看进度、结果、审批和待补充输入；执行结束后再检查结果并验收。

• 关闭 CodexBoard 窗口：应用保留在菜单栏，服务继续运行。
• 退出 CodexBoard 或点击停止服务：本机服务停止，浏览器和飞书中的看板暂时无法访问。
• Mac 关机、休眠或断网：公网访问可能中断；使用远程功能时需要保持 Mac 在线。

退出 CodexBoard 不会关闭 Codex Desktop，但应在更新或停止服务前处理好看板中的执行任务。

配套 Skill 让 Codex 通过应用内置命令行查询、修改任务和协助执行，无需克隆源码或安装 Node.js。目前支持安装到 Codex，技能名称为 manage-codexboard。

首次启动且尚未安装配套技能时，应用会显示 让 Codex 使用 CodexBoard 提示，可以选择 安装到 Codex，也可以稍后从 应用设置 → Agent Skill 安装。安装位置为 ~/.agents/skills/manage-codexboard。

应用启动后会自动比较随包 Skill 与已安装版本，检测到更新时在窗口顶部提示，点击“查看 Skill”可进入更新卡片；也可用“重新检查”刷新。版本号相同但随包内容变化时也会提示，关闭当前提示后再次出现新内容会重新提醒。点击更新后才替换；已有用户修改时，会提示检查修改，须明确选择“使用随包版本”。符号链接、由其他工具管理的目录、旧版名称的技能或旧技能目录中的同名技能，会提示回到原位置或管理器处理，避免重复安装；应用不会检查这些管理器中的远端版本。

“文件已安装”不表示当前 Codex 任务已加载技能。请在 Codex 的技能列表中确认；未识别时可强制重新加载技能，或在方便时重新打开 Codex，再在新任务中使用：

请使用 $manage-codexboard，先查看我的项目和任务，再帮我处理指定任务。

技能安装或浏览器登录不等于已授权 CLI。CLI 查询和写入看板都需要配对：Web 用户在浏览器授权页登录并确认，飞书用户在飞书看板中确认。核对账号、CLI 名称和验证码后，该 CLI 使用确认授权的真实用户身份；不会以本机服务身份操作看板。

需要 Agent 帮你安装应用、完成配置或排查问题时，把本仓库的 AGENTS.md交给它，并说明你要完成的事情，例如：

请阅读 AGENTS.md，检查我的 Mac 是否满足要求，帮我安装并配置 CodexBoard。需要我登录或在飞书后台确认的步骤，请明确告诉我。

Agent 指南提供内置 taskctl 的入口、身份配对、只读检查和常用操作流程，无需为此克隆源码或安装开发依赖。不同 Agent 对指令文件的自动读取方式不同；不能自动读取时，直接提供文件内容或链接。

macOS 在 应用设置 → 应用更新 中，可通过“前往 Release 手动下载”打开最新发布页，也可在此处或菜单栏检查新版本。应用每天自动检查一次，发现新版本后显示提醒和更新说明。下载并验证完成后，点击“安装并重启”，按提示处理正在执行的任务，再确认安装。检查和下载期间服务继续运行；安装时本机服务会暂时停止。

更新包使用独立签名校验。无法自动更新时，可正常退出旧版，再用新版 DMG 替换“应用程序”中的 CodexBoard.app。配置、数据库和附件保存在：

~/Library/Application Support/CodexBoard/

升级首次启动时，若新目录尚不存在，应用会在旧版退出后自动迁移已有数据；遇到目录冲突时会保留原数据并提示处理。正常替换应用会保留数据。删除数据目录会影响配置和任务数据，不要把它当成安装缓存清理，也不要随安装包发送给别人。

知道域名不代表能读取看板数据。未登录请求受保护，Web 账号必须由本机创建，飞书入口由飞书身份登录验证。HTTPS 用于加密传输，不能代替账号授权。请妥善保管密码并按需停用账号，不要把域名本身当作访问限制。

反馈问题时，请提供应用版本、macOS 版本、复现步骤和经过脱敏的报错截图。不要公开 App Secret、隧道认证信息、登录令牌或完整数据目录。

公开仓库保留应用源码、构建与打包所需文件。命令用法可通过 taskctl --help 查看；普通安装不需要执行构建命令。