codex-loop

codex-loop 是一个本地优先的长任务循环控制台。

它的目标不是替代真实对话窗口，而是把“持续续跑、可见状态、聊天镜像、优雅停止、任务管理”这些长期使用时真正重要的能力补齐，让你可以更稳定地把 Codex 用在项目开发里。

它解决什么问题

• 运行循环后，不确定到底有没有真的开始
• 长任务期间看不到持续状态，容易误以为卡死
• 希望自动续跑的记录出现在真实对话窗口里
• 一个项目想管理多个任务，而不是所有东西堆在首页
• 想在本地保留摘要、聊天镜像和运行痕迹，便于恢复

当前体验重点

• 首页尽量简洁，只看当前任务与关键状态
• 左侧统一管理所有任务
• 任务详情只关心状态、最近进展、聊天记录
• 停止时优先走优雅收尾，而不是直接中断
• 可以从控制台直接关闭整组服务，方便重启

适合谁

• 已经在用 Codex 做项目开发的人
• 希望把长任务跑得更稳、更可见的人
• 需要一个项目里管理多个自动任务的人
• 希望后续接入本地模型增强续跑质量的人

当前能力边界

• 不直接接管官方内部接口
• 不承诺完全无人值守开发
• 不绕过权限、提交、验证这些真实开发约束
• 本地模型增强当前优先支持 Ollama

架构概览

整体分成 4 层：

1. 启动层

• start-codex-loop.bat
• scripts/start-codex-loop.ps1
• scripts/dev.mjs

负责检查环境、分配端口、启动前后端、记录服务状态、关闭整组进程。

2. 服务层

• app/server/

负责：

• 任务启动 / 停止 / 手动续跑
• 任务列表与切换
• 对话式创建任务
• 自动续跑设置
• 聊天镜像、摘要、健康状态导出

3. 界面层

• app/web/

负责：

• 首页任务总览
• 左侧任务列表
• 对话式创建任务
• 当前任务详情
• 管理区折叠设置

4. 本地状态层

• runtime/
• settings/
• config.local.json

负责保存：

• 任务运行状态
• 聊天镜像
• 当前任务列表
• 用户覆盖设置
• 本机专属配置

目录说明

app/
  server/        本地接口、任务控制、健康状态、模型接口
  web/           本地控制台前端
docs/            设计文档、说明文档
projects/        通用项目适配模板
scripts/         启动、检查、初始化、绑定等脚本
tests/           核心测试
runtime/         本地运行产物（git 忽略）
settings/        本地任务状态（git 忽略）
dist/            前端构建产物（git 忽略）

环境要求

最低要求：

• Windows
• Node.js 18 或更高版本
• npm
• 已安装并可使用的 Codex 工作环境

建议准备：

• Git
• 一个真实项目目录
• 一个用于持续续跑的真实对话窗口

可选增强：

• Ollama

安装

1. clone 仓库
2. 进入仓库根目录
3. 执行 npm install

本地配置

仓库默认配置是通用模板，不绑定任何人的私有项目。

你自己的机器配置请写到：

• config.local.json

推荐做法：

1. 复制 config.local.example.json 为 config.local.json
2. 把 workspaceRoot 改成你自己的项目目录

这些本地配置不会进入开源仓库。

快速开始

1. npm install
2. npm run loop:check
3. npm test
4. npm run build:web
5. start-codex-loop.bat
6. 打开控制台
7. 在左侧创建任务
8. 连接真实对话窗口
9. 开始循环

日常使用方式

日常只需要记住三件事：

1. 在首页看当前任务是否在运行
2. 在任务详情里看最近进展和聊天记录
3. 需要调整时再打开左侧管理区

也就是说，大多数时候你不需要面对一大堆设置表单。

创建任务

当前已经支持对话式创建任务。

流程是：

1. 输入项目路径
2. 自动识别项目线索
3. 生成首版任务建议
4. 逐项确认项目名、任务名、分支
5. 创建任务并放入左侧列表

如果开启本地模型增强，创建体验会更像对话助手。

如果没有开启本地模型，也可以正常使用默认创建链路。

运行任务

当前支持：

• 开始循环
• 手动续跑一轮
• 停止并收尾
• 查看最近摘要
• 查看聊天记录

任务运行时，界面会持续刷新状态，避免误判卡死。

连接真实对话窗口

控制台支持把任务续跑记录显示到真实窗口中。

通常只需要做一次：

1. 打开左侧管理区
2. 进入“连接窗口”
3. 填入目标窗口信息
4. 保存连接

日常运行时，这一块可以一直收起。

关闭与重启

控制台已经支持直接在界面里关闭整组服务。

如果当前任务还在运行：

• 会先提示确认
• 然后优雅停止当前任务
• 最后再关闭整组服务进程

这样重启更安全，不容易把任务直接切断。

默认模式

不开启任何本地模型时，codex-loop 仍然可以正常工作：

• 默认中文续跑
• 根据当前任务状态继续推进
• 状态、聊天镜像、摘要都可见
• 停止、重启、切换任务都可用

也就是说，不装 Ollama 也能直接投入使用。

Ollama 增强模式

如果你希望续跑内容更像真人接话，可以安装 Ollama。

启用后，系统会结合这些信息生成下一条续跑内容：

• 当前任务设置
• 已识别的项目规则与文档
• 上一轮摘要
• 最近一次任务上下文

基本步骤：

1. 安装 Ollama
2. 启动 Ollama
3. 拉取一个模型，例如：

ollama pull qwen2.5:7b

4. 打开控制台
5. 在“自动续跑 -> 智能增强”里启用

如果没装 Ollama：

• 不会影响默认模式
• 仍然可以继续使用

当前移动端进度

目前移动端已经具备基础数据能力：

• 最近摘要
• 聊天镜像
• 当前状态
• 建议动作

但当前优先级仍然是桌面端。

也就是说：

• 现在已经能为移动端提供查看数据
• 但专门的移动端任务详情界面还在后续阶段

主要命令

• npm run loop:check
• npm run loop:init
• npm run loop:heartbeat
• npm run loop:finalize
• npm run loop:summary
• npm run loop:scaffold
• npm run loop:bind-thread
• npm run loop:start
• npm run dev
• npm run build:web
• npm test

新机器验证建议

建议在新机器上按这个顺序验证：

1. npm install
2. npm run loop:check
3. npm test
4. npm run build:web
5. start-codex-loop.bat

如果以上都通过，再开始连接真实窗口和创建任务。

开源使用注意事项

• 不要把自己的真实项目配置提交进仓库
• 本地状态只保存在 runtime/、settings/、config.local.json
• 这些文件应当只留在本机
• clone 本仓库的人，看到的应该始终是通用版本的 codex-loop

当前适合的定位

如果要对外介绍，比较准确的说法是：

• 一个面向项目开发的本地循环控制台
• 一个让长任务更可见、更可控的辅助层
• 一个把任务续跑、状态可视化、聊天镜像整合在一起的工具

License

MIT