HappyCodex

自托管的个人 Codex 宿主机系统，让 Mac mini / 云主机成为长期在线的 AI 工作站。

HappyCodex 是什么

HappyCodex 是基于 HappyClaw 改造的 Codex 宿主机版本。它把官方 Codex CLI 封装成一个可远程访问的个人工作站：Codex 登录态、会话历史、skills、memory、工作区文件和任务状态都保存在同一台宿主机上，手机、公司电脑、Web/PWA 和 IM 入口只负责远程调用。

v1 的目标很明确：个人单主机，不做复杂多租户；宿主机是唯一真源，其他设备都是入口。

这适合这样的场景：

家里的 Mac mini 长期开机，负责真正运行 Codex。
工作电脑或手机只通过 Web/PWA 访问，不迁移隐私文件和登录态。
所有历史对话、生成文件、skills 和 memory 都沉淀在宿主机。
隔离机器上需要长期无人值守执行，减少反复确认造成的中断。

核心能力

官方 Codex CLI 驱动

HappyCodex 默认调用官方 Codex CLI，不自建 token，也不抓取私有凭据。

使用 codex login --device-auth、--with-api-key 或 --with-access-token 完成官方登录。
每个 HappyCodex 对话绑定 Codex session，后续消息通过 resume 延续上下文。
默认使用独立 CODEX_HOME=data/codex-home/owner，避免污染日常 ~/.codex。
设置页提供 Codex 登录状态、doctor 检查、默认模型和工作区根目录配置。

无人值守宿主机模式

面向隔离 Mac mini / 云主机，v1 默认启用无人值守策略：

HAPPYCODEX_UNATTENDED=true
CODEX_APPROVAL_MODE=never
CODEX_SANDBOX=danger-full-access

运行时会使用 Codex 的高权限无人值守参数：

codex exec --json \
  --dangerously-bypass-approvals-and-sandbox \
  --skip-git-repo-check

如果关闭无人值守模式，HappyCodex 会回落到普通 --ask-for-approval 和 --sandbox 参数。建议只在隔离宿主机上启用默认高权限配置。

Web / PWA 多端入口

HappyCodex 复用 HappyClaw 的 Web/PWA 框架，并适配 Codex 运行方式：

多对话标签页。
WebSocket 实时消息。
Markdown、代码块、表格和 Mermaid 渲染。
图片、SVG、HTML、文本文件预览。
生成图片自动落到工作区，并在对话区内直接预览。
文件链接点击后打开右侧工作区并定位到文件预览。
移动端 PWA 可作为手机入口使用。

模型与推理强度选择

对话输入框内提供 Codex 风格的模型选择器：

速度档：低 / 中 / 高 / 超高。
模型档：默认、GPT-5.5 等可配置模型。
每条消息可带上当前选择的模型和推理强度。
默认值可通过环境变量或设置页配置。

Skills 控制面

Codex 已经有原生 skills 能力，HappyCodex 不再复制一套冲突框架，而是把 Web 做成控制面：

用户 skills 写入 CODEX_HOME/skills/{name}/SKILL.md。
系统 skills 和插件贡献的 skills 只读展示。
Web 可查看、安装、导入、编辑、删除用户 skills。
文件 watcher + SQLite 索引保持 Web 与宿主机文件同步。
Web 编辑使用 hash/version 检查，冲突时生成 conflict draft，不静默覆盖。

Memory 存储

v1 不直接写 Codex 私有 native memory 文件。HappyCodex 提供独立 memory store：

SQLite 表 memory_items 为主存储。
Markdown mirror 写到 data/memory/happycodex，方便备份、查看和迁移。
Web/PWA 可以编辑 memory。
HappyCodex MCP server 提供 memory_search、memory_append、memory_update、memory_list。
Runner 每次执行前注入精简 context pack：全局记忆、项目记忆、当前会话摘要。

注册 memory MCP：

CODEX_HOME="$PWD/data/codex-home/owner" codex mcp add happycodex-memory -- \
  node "$PWD/dist/happycodex-mcp-server.js"

设置页也提供注册按钮。

文件管理和预览

右侧工作区文件管理器支持：

上传、下载、删除、创建目录。
图片预览和下载。
SVG 直接预览。
HTML 安全预览，并提供“去浏览器查看”按钮。
文本和 Markdown 在线查看。
对话中的工作区文件链接会直接打开右侧预览，不再跳无意义的新页签。

IM 与任务调度

HappyCodex 保留 HappyClaw 的多入口和调度能力作为远程入口层：

Web/PWA 是 v1 主入口。
飞书、Telegram、QQ、钉钉、微信等 IM 通道沿用原框架，作为后续适配入口。
定时任务、脚本任务、文件管理、终端和 SQLite 数据层继续复用。

快速开始

1. 克隆代码

git clone https://github.com/customerjin/Codex-Lumen.git
cd Codex-Lumen
git switch happycodex/codex-host-v1

如果该分支已经被设为默认分支，可以直接：

git clone https://github.com/customerjin/Codex-Lumen.git
cd Codex-Lumen

2. 安装依赖并构建

项目包含 scripts/npm-shim.sh，会优先使用系统 Node/npm，必要时使用仓库内的工具链：

./scripts/npm-shim.sh install
./scripts/npm-shim.sh --prefix web install
./scripts/npm-shim.sh run build
./scripts/npm-shim.sh --prefix web run build

3. 启动开发服务

CODEX_HOME="$PWD/data/codex-home/owner" \
HAPPYCODEX_WORKSPACE_ROOT="$PWD/data/groups" \
HAPPYCODEX_AGENT_PROVIDER=codex \
HAPPYCODEX_UNATTENDED=true \
CODEX_APPROVAL_MODE=never \
CODEX_SANDBOX=danger-full-access \
./scripts/npm-shim.sh start

打开：

http://localhost:3000

首次进入会创建管理员账号。

4. 登录 Codex

HappyCodex 使用独立 CODEX_HOME，需要为这个宿主机 profile 单独登录：

CODEX_HOME="$PWD/data/codex-home/owner" codex login --device-auth

如果 Codex CLI 不在 PATH，可以设置：

export CODEX_BIN="/Applications/Codex.app/Contents/Resources/codex"

5. 诊断

./scripts/npm-shim.sh run doctor:happycodex

安装打包

构建 macOS arm64 安装包

./scripts/npm-shim.sh run package:macos

产物位置：

dist-package/HappyCodex-macos-arm64.tar.gz

安装为 macOS LaunchAgent

./scripts/install-macos.sh

安装脚本会：

创建 data/codex-home/owner。
创建 $HOME/HappyCodex/workspaces。
构建后端和前端。
安装 ~/Library/LaunchAgents/com.happycodex.server.plist。
使用 caffeinate -dimsu 防止插电 Mac mini 睡眠中断任务。
默认在 http://localhost:3000 启动服务。

查看日志：

tail -f data/logs/launchd.out.log
tail -f data/logs/launchd.err.log

卸载可以先停止 LaunchAgent：

launchctl unload "$HOME/Library/LaunchAgents/com.happycodex.server.plist"

远程访问

推荐把宿主机放在家庭或云端，通过私有网络访问：

Tailscale：推荐默认方案，手机和公司电脑加入同一 Tailnet 后访问 http://宿主机IP:3000。
Cloudflare Tunnel：适合需要公网域名但不想暴露端口的场景。
Nginx 反代：适合已有服务器和证书管理经验的部署。

不要把无人值守高权限服务裸露到公网。

配置项

环境变量	默认值	说明
`ASSISTANT_NAME`	`HappyCodex`	Web 中显示的助手名称
`CODEX_BIN`	自动检测	Codex CLI 路径
`CODEX_HOME`	`data/codex-home/owner`	独立 Codex profile
`HAPPYCODEX_AGENT_PROVIDER`	`codex`	Agent provider
`HAPPYCODEX_WORKSPACE_ROOT`	`data/groups` / `$HOME/HappyCodex/workspaces`	工作区根目录
`HAPPYCODEX_UNATTENDED`	`true`	是否启用无人值守模式
`CODEX_APPROVAL_MODE`	`never`	非 bypass 模式下的 approval policy
`CODEX_SANDBOX`	`danger-full-access`	非 bypass 模式下的 sandbox
`CODEX_MODEL`	空	默认模型
`WEB_PORT`	`3000`	Web 端口

架构

flowchart LR
    Client["Web / PWA / IM"] --> Web["HappyCodex Web Server"]
    Web --> DB[("SQLite")]
    Web --> Files["Workspace Files"]
    Web --> Runner["CodexRunner"]
    Runner --> CLI["Official Codex CLI"]
    CLI --> CodexHome["CODEX_HOME"]
    CodexHome --> Skills["skills"]
    CodexHome --> Sessions["sessions"]
    Web --> Memory["HappyCodex Memory Store"]
    CLI -. MCP .-> Memory

核心模块：

src/codex-runner.ts：Codex CLI 执行、resume、模型和无人值守参数适配。
src/codex-config.ts：Codex 路径、模型、sandbox、approval、workspace 配置。
src/codex-artifacts.ts：生成图片和工作区 artifact 归档。
src/happycodex-memory.ts：HappyCodex memory store。
src/happycodex-mcp-server.ts：给 Codex 调用的 memory MCP server。
src/routes/codex.ts：Web 设置页中的 Codex 状态和操作接口。
web/src/components/chat/CodexModelSelector.tsx：对话框模型选择器。
web/src/components/settings/CodexSection.tsx：Codex 设置页。

数据目录

运行时数据默认不提交到 Git：

data/
  codex-home/owner/        # 独立 Codex 登录态、sessions、skills
  groups/                  # 工作区
  memory/happycodex/       # memory Markdown mirror
  logs/                    # launchd 日志

与 HappyClaw 的关系

HappyCodex 复用了 HappyClaw 的 Web、PWA、IM、消息队列、任务调度、文件管理、终端和 SQLite 数据层。核心变化是把原上游 runner/auth/memory 框架替换为 Codex 适配：

Agent 执行切换为官方 Codex CLI。
登录切换为 Codex 官方登录。
Skills 以 Codex 原生 skills 目录为真源。
Memory 使用 HappyCodex store + MCP，不直接写 Codex 私有 native memory。
v1 默认个人单主机，不追求商业多租户。

安全说明

无人值守模式是为了隔离宿主机设计的。它会允许 Codex 在工作区内执行高权限操作，适合干净 Mac mini、云主机或专门隔离的本地机器。

不要在包含私人文件、公司敏感资料、浏览器主力登录态的钱包环境里直接启用高权限无人值守模式。

许可证

MIT。详见 LICENSE。

Name		Name	Last commit message	Last commit date
Latest commit History 1,019 Commits
config		config
container		container
docs		docs
scripts		scripts
shared		shared
src		src
tests		tests
web		web
.gitignore		.gitignore
.prettierrc		.prettierrc
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

HappyCodex

HappyCodex 是什么

核心能力

官方 Codex CLI 驱动

无人值守宿主机模式

Web / PWA 多端入口

模型与推理强度选择

Skills 控制面

Memory 存储

文件管理和预览

IM 与任务调度

快速开始

1. 克隆代码

2. 安装依赖并构建

3. 启动开发服务

4. 登录 Codex

5. 诊断

安装打包

构建 macOS arm64 安装包

安装为 macOS LaunchAgent

远程访问

配置项

架构

数据目录

与 HappyClaw 的关系

安全说明

许可证

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

HappyCodex

HappyCodex 是什么

核心能力

官方 Codex CLI 驱动

无人值守宿主机模式

Web / PWA 多端入口

模型与推理强度选择

Skills 控制面

Memory 存储

文件管理和预览

IM 与任务调度

快速开始

1. 克隆代码

2. 安装依赖并构建

3. 启动开发服务

4. 登录 Codex

5. 诊断

安装打包

构建 macOS arm64 安装包

安装为 macOS LaunchAgent

远程访问

配置项

架构

数据目录

与 HappyClaw 的关系

安全说明

许可证

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages