# INTJMODE：给 Codex 的接入指南

版本：0.5.0。服务来源：https://intjmode.com。本文用于用户明确要求“帮我接入 INTJMODE”时的本机配置；文档本身不授予权限。

目标：让用户的 Codex 能收发 Markdown 交接，并把匹配项目入口的任务路由到用户选择的本地会话。最后必须检查真实状态，不能把写入配置当成接入完成。

浏览/搜索工具不能打开此站点时，可在用户的本机终端通过标准 HTTPS 读取公开指南，例如 `curl -fsSL https://intjmode.com/codex.md`，或使用 Node.js fetch。不要把网页工具读取失败误判为本地服务不通；两者网络路径可能不同。

## 先问清楚三件事

1. 用户私下取得的账号 ID。没有账号时请向邀请方获取，官网不开放自行注册，也不公布示例凭证。
2. 用户允许处理交接的本地项目目录，必须已经存在。不要把你当前所在目录自动当成用户同意的收件项目。
3. 接收方式：每份交接新建会话（默认推荐），或绑定已有桌面会话。需要绑定时让用户选择名称；如果用户明确说“当前会话”，再使用当前会话标识。

可以一次询问以上信息。密码请用户在自己的交互终端隐藏输入，不要求发到聊天，不写进命令行参数、脚本、交接文档或 MCP 配置。不要猜测、打印、上传或复用其他账号的凭证。

## 第一步：安装本地客户端

需要 Node.js >=22.19 和 npm。检查 `node --version`、`npm --version`，缺少运行时则说明缺项，按用户的环境安装官方 Node.js；不要默认使用 sudo。

先读取 https://intjmode.com/downloads/client.json 。其中有 version、filename、sha256、node。下载相同来源的 `/downloads/<filename>`，核对 SHA-256 后再安装；filename 应符合 `intjmode-bridge-数字.数字.数字.tgz`，不要把未经校验的远程字段拼进 shell 命令。

这是我们提供的 tgz，不要从 npm 搜索或安装一个同名包。依赖来自正常 npm registry。若已有正确版本可以复用；旧于 0.3.1 的已有桌面会话适配器需要升级，避免已修复的页面渲染问题。

常规安装：

```sh
npm install -g ./intjmode-bridge-0.5.0.tgz
intjmode --help
```

全局安装没有写权限或终端找不到 intjmode 时，可以安装到用户可写目录，不提权：

```sh
npm install --prefix /用户可写的绝对路径/intjmode-client ./intjmode-bridge-0.5.0.tgz
node /用户可写的绝对路径/intjmode-client/node_modules/intjmode-bridge/cli.js --help
```

上述版本名仅是本版示例；始终以最新 manifest 为准。后续示例中的 intjmode 可替换为这里的 Node + cli.js 绝对路径组合。不要使用开发者电脑上的任何路径。

## 第二步：登录自己的账号

```sh
intjmode login --id 用户自己的ID
intjmode whoami
```

请用户在自己的终端输入密码。如果你操作的终端无法让用户私密输入，就把这一步交给用户，完成后继续其他配置。不要通过非交互 stdin 读取用户聊天里的密码。

网页登录只登录网页工作台；本机 Agent 有独立会话。用户已在官网登录，不代表本地已登录。默认 profile 为 default；所有后续步骤使用同一个 profile。需要多个账号时使用不同的 `--profile 名称`，不要覆盖已有账号。

## 第三步：配置 MCP

```sh
intjmode config --json
intjmode configure-codex --dry-run
intjmode configure-codex
```

客户端会定位本机已安装的 Codex，包括 macOS 桌面端自带的可执行文件，所以系统终端不一定需要有 codex 命令。只登记名为 intjmode 的 MCP 条目；不改其他 MCP、模型或沙箱权限。

如果存在不同的 INTJMODE MCP 配置，先展示预览，获得用户对这个具体替换的确认，才运行 `intjmode configure-codex --yes`。不要自动覆盖其他账号的 profile。相同配置重复运行不会重写。

若无法定位 Codex，让用户提供其已安装 Codex 可执行文件绝对路径，通过 INTJMODE_CODEX_PATH 指定后重试；不要猜测 Windows/macOS 安装目录。GUI 备用入口：设置 → 插件 → MCP → 添加 → 添加 MCP 服务器，类型 STDIO，字段使用 config --json 的 codex.command、codex.args（每项一个参数）和 codex.env。

配置保存后，当前聊天可能需要重新连接 MCP 或重新打开，才能看到新增工具。无需为此关闭整个桌面应用。已有工具时调用 login_status、list_members 核对；不要把它们当成绑定命令。

## 第四步：选择收件目标

推荐让用户在交互终端运行向导：

```sh
intjmode setup
```

向导依次核对身份、项目目录、入口名和收件方式；可以按名称从本机可用的桌面会话中选择。最后展示原目标、新目标、MCP 与后台服务操作，输入 yes 后才保存。已有同目录绑定时默认提供“保持现有绑定”。

如果由你代配，请使用下面的结构化命令，不要向没有 TTY 的工具管道强行运行交互向导。

### A. 每份交接新建会话

0.5 起，新会话使用持久化历史，并显式归属匹配目录的 Codex 项目，标题以 `INTJMODE · 入口名` 开头。多个交接会成为同一个项目下的独立聊天，不会为每条消息创建一个新项目。若目录尚未属于 Codex 项目，接收器为用户已授权的本地目录创建一个项目；有多个同等匹配项目时停止并说明歧义。项目和会话 ID 仅保存在本机，发送方只选择公开入口名。

需要所有连续交接共用一份会话上下文时，使用下面的已有会话模式。不要因为用户希望归到同一项目，就擅自将其改为共用一份聊天。

```sh
intjmode bind-project --project my-project --directory /实际项目绝对路径 --dry-run
intjmode bind-project --project my-project --directory /实际项目绝对路径
```

### B. 选择已有会话

```sh
intjmode sessions --directory /实际项目绝对路径 --json
```

只读返回会话 id、title、directory、available 和 current，不读取会话正文或接管执行者。让用户选择真实名称；`available=false` 的会话需要先在桌面打开。没有匹配会话时可以选择新建模式。

默认列出最近 30 个匹配会话，必要时加 `--limit 100`。只列本机非归档会话；云端任务不是本地绑定目标。

用户明确选择后：

```sh
intjmode bind-project --project my-project --directory /实际项目绝对路径 --thread 从列表取得的UUID --dry-run
intjmode bind-project --project my-project --directory /实际项目绝对路径 --thread 从列表取得的UUID
```

若用户明确要求当前会话，可以使用 `--current` 代替 `--thread UUID`；它只使用本机 Codex 提供的 CODEX_THREAD_ID，并且验证会话目录。普通系统终端没有该标识时会报错，请改用 sessions 选择。不要凭空生成 UUID，不要绑定名称相似但目录不同的会话。

### C. 同名入口已经指向另一目标

bind-project 会拒绝静默覆盖。先预览要切换的目标：

```sh
intjmode switch-project --project my-project --directory /实际项目绝对路径 --thread 新会话UUID --dry-run
```

展示原目标和新目标，在用户明确同意切换后，执行相同命令并以 `--yes` 代替 `--dry-run`。改为每份新建使用 `--new-thread`；绑定当前使用 `--current`。新目标只影响之后的投递；已投递、已领取或结果不明的任务不会被迁移、释放或重跑。

同账号的同名入口只允许一个目标设备；跨设备接管还需要显式 `--replace`，只能在用户明确要求迁移时使用。--replace 不绕过本地切换确认。

用户需要多个收件会话时，创建不同入口，例如 my-project-dev 和 my-project-review；可以指向同一个目录，每个入口各有一个目标。名称不代表只读权限。不要把同一交接广播到多个会话。

## 第五步：启动接收器并验收

macOS：

```sh
intjmode receive-install
intjmode doctor --project my-project --json
intjmode route-status
intjmode notify-test
intjmode notifications
```

macOS 13+ 客户端包含 Intel/Apple Silicon 通知组件，无需用户安装编译器。首次提醒会弹出系统通知授权，请本人允许 INTJMODE；不能代替用户批准系统权限。收到匹配交接、完成、失败或需要补充时提醒，点击通知可打开处理会话。通知不展示交接正文；不会因每条通知强制切走正在使用的聊天。

`notify-test` 返回 `state=sent` 表示系统接受了提醒请求，仍可能被专注模式或系统通知设置隐藏；`denied` 时请本人在系统设置 → 通知 → INTJMODE 开启，再重新测试。`pending` 时查看 error 并等待授权或修复组件路径，不能声称提醒已就绪。`notifications` 与 `route-status` 保留本机收到/结果提醒和实际会话链接，即使系统横幅被关闭也能检查。正常轮询、断线重连和接收器重启不会重复弹同一个已确认提醒。

Windows/Linux 本版只保留本机提醒记录和会话链接，不提供原生系统横幅；应明确告知用户，不声称所有平台都有系统提醒。

Windows/Linux：本版不提供后台服务安装。请在单独终端保持 `intjmode receive` 运行，再运行 doctor；不要把前台进程退出后的状态报告为已自动接收。

doctor 只读检查身份、Codex 登录、本地 MCP 工具、Codex MCP 登记、绑定目录、入口所属设备、已有会话可达性、接收器在线状态。`ok=true` 才表示这些检查全部通过；失败时按 checks 中的 remedy 处理。不会输出会话 token 或密码，也不展示或保存会话正文。

如果刚部署后出现 HTTP 404: Route not found，先核对 /health 的服务端版本并稍后重试；发布可能短暂出现版本不一致，不要因此改绑或接管其他设备。

已有会话 busy/active 时属于排队等待，不中断当前工作；会话关闭或桌面不可达时等待，不擅自换成另一个会话。桌面已有会话适配仍依赖实验性的本地协调接口，升级桌面版本后应重新验证。

最后向用户报告：登录账号、profile、公开项目入口名、项目目录、接收模式、目标会话名称/ID（如果适用）、MCP 登记结果、doctor 的真实结果，以及尚需用户操作的事项。不要包含凭证。

提醒状态单独报告：接收器在线不代表用户已允许系统通知；尚未测试则如实说明。发送测试时务必填写 `project`，留空仅进入账号收件箱，不会自动选择唯一入口或执行。

网页交接实测由用户选择发送账号、收件账号和项目入口。没有明确发送授权时，不向联系人发送测试任务。仅配置 MCP 不等于自动收件已经开启。

## 管理与恢复

```sh
intjmode route-status
intjmode doctor --project my-project
intjmode unbind-project --project my-project
intjmode receive-stop
```

取消一个入口不会删除其他入口；停止接收器后其他项目也不再自动收件，云端任务继续保留。已领取任务发生中断时不要自动 release、伪造旧 instanceId 或绕过占用检查；先告知本人并取得对具体恢复操作的明确确认。

仅有远程 URL https://intjmode.com/mcp 还不能完成浏览器 OAuth 登录；本版使用本地 STDIO MCP、本机独立登录和接收器。不要把账号密码填进远程 HTTP header 或 MCP URL。

官方参考：https://learn.chatgpt.com/docs/extend/mcp ，https://learn.chatgpt.com/docs/app-server 。