tellrun 1.0.1 → 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chaoyue1998
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,171 +1,207 @@
-# Tellrun
+# Tellrun — Telegram Bot for OpenAI Codex
 
-通过 IM 与服务器上的编码 Agent 对话，提交开发任务、查看进度、处理审批并继续会话。
+**Tellrun is a self-hosted Telegram bot for remote AI coding with OpenAI Codex CLI, persistent sessions, and streaming replies.**
 
-Tellrun 取自 Tell + Run，意为说出需求、交给 Agent 执行，npm 包名与 CLI 命令均为 `tellrun`。
+Run Tellrun on your server and use Telegram on your phone or desktop to send coding tasks, continue conversations, and read results without keeping an SSH terminal open.
 
-## 首版目标
+**English** | [简体中文](https://github.com/chaoyue1998/tellrun/blob/main/README.zh-CN.md)
 
-- 个人使用，仅授权本人操作。
-- 通过 `npm install -g tellrun` 安装，命令行交互配置后在服务器后台运行。
-- Telegram 私聊接入，采用长轮询。
-- Codex 通过 `app-server` 接入。
-- 支持多会话、任务排队、审批、停止和异常恢复。
-- 暂不提供项目选择，Tellrun 不设置项目目录白名单。
-- 后续逐步接入其他 IM、Claude 等 Agent。
+[npm](https://www.npmjs.com/package/tellrun) · [GitHub](https://github.com/chaoyue1998/tellrun) · [Report an issue](https://github.com/chaoyue1998/tellrun/issues)
 
-## 文档
+[Quick start](#install-and-connect-codex-to-telegram) · [Telegram commands](#telegram-commands) · [Configuration](#configuration-and-data) · [FAQ](#faq)
 
-- [产品需求文档](docs/prd.md)：范围、交互流程、命令、功能和验收要求。
-- [架构与技术选型](docs/architecture.md)：架构图、框架与库、模块、数据模型、协议、恢复和部署方案。
+## Features
 
-当前已接通 Telegram → Codex app-server → 结果回复，支持指定工作目录、单会话续聊、新建会话、停止、任务去重和重启恢复。配置与运行状态使用 JSON 文件保存；多会话选择、任务排队、进度推送和审批界面尚未接入。
+- **Remote coding**: send tasks in a private Telegram chat and let Codex execute them on your server.
+- **Continuous conversations**: keep the current conversation context, select a project with `/cwd`, and start fresh with `/new`.
+- **Live feedback**: see typing indicators and streaming replies, and send additional instructions while a task is running.
+- **Task control**: check status and recent results, stop a task and pause new work, and retain conversation and task records across restarts.
+- **Personal deployment**: only the configured user's private messages are accepted. Long polling requires no webhook or inbound port configuration.
 
-## 安装与使用
+Currently supports **Telegram + Codex** for one user, with one task at a time. A session picker, a queue of separate tasks, approval and structured question interfaces, and image or file input are not yet supported.
 
-先安装 Node.js 24.5.0 或更高版本、Codex，并完成 Codex 登录。CLI、配置向导和 Linux systemd 用户服务管理已接入；本轮未执行 npm 发布，发布后可按以下流程使用。
+
+## Install and connect Codex to Telegram
+
+### 1. Prerequisites
+
+- **Node.js ≥ 24.5.0**.
+- **[Codex CLI](https://github.com/openai/codex)**: install and sign in as the same operating system user that will run Tellrun. Confirm that Codex works in your terminal.
+- **Telegram Bot Token**: send `/newbot` to [@BotFather](https://t.me/BotFather), follow the prompts, and save the token. See the [official Telegram tutorial](https://core.telegram.org/bots/tutorial#obtain-your-bot-token).
+- **Your numeric Telegram user ID**: this is not your `@username`. See [how to find it](#how-do-i-find-my-telegram-user-id).
+
+Background service management requires **Linux with systemd user services**. Use `tellrun run` in the foreground for local development or with another process manager.
+
+### 2. Install and configure
 
 ```sh
 npm install -g tellrun
-tellrun setup       # 交互配置 Telegram 和 Codex，完成后可直接启动后台服务
-tellrun start       # 后续启动
-tellrun status      # 查看后台服务状态
-tellrun logs        # 查看日志
-tellrun logs -f     # 持续跟随日志
-tellrun restart     # 重启服务
-tellrun stop        # 停止后台服务
+tellrun setup
 ```
 
-CLI 采用 Commander，配置向导采用 Clack。Bot Token 使用明文输入，已有配置时留空保留原值。`setup` 校验配置与 Codex 可执行文件后原子保存，取消时保留原配置；可选择立即启动或重启后台服务，并启用开机自启。后续也可使用 `tellrun start --enable` 启用自启。配置、运行状态、单实例锁和服务定义都保存在当前用户的 `~/.tellrun/`，全局 npm 包升级保留这些数据。
+Enter your Bot Token, numeric user ID, and Codex command or executable path. On Linux, the setup wizard can start the background service and optionally enable it at boot.
 
-后台运行需要 Linux systemd 用户服务。启动时检查并启用用户 linger，确保退出 SSH 后继续运行；权限不足会给出需要在服务器执行的命令。`tellrun run` 提供前台运行，适用于本地调试或外部进程管理器。`tellrun service uninstall` 停止并移除服务，保留配置、状态文件和用户 linger 设置。
+If you choose to save the configuration without starting the service, run this later:
 
-使用 nvm 安装 Node.js 时，Tellrun 会把当前 Node 所在目录补到 Codex 子进程的 `PATH` 前面，保证后台启动也能找到 `node`。
+```sh
+tellrun start --enable
+```
 
-尚未发布时，可在源码目录执行 `npm ci`、`npm pack`，再通过 `npm install -g ./tellrun-1.0.1.tgz` 安装本地包。打包自动构建并包含运行依赖声明。升级前停止服务并备份数据，升级后运行 `tellrun restart` 更新 Node 与 CLI 入口路径。具体布局和生命周期见[架构文档](docs/architecture.md#分发与命令行入口)。
+To run in the foreground instead:
+
+```sh
+tellrun run
+```
 
-## 技术方案
+### 3. Start chatting in Telegram
 
-Node.js 24 + TypeScript（ESM）；grammY 接入 Telegram；Node.js 文件接口保存 JSON 配置和状态；Zod 校验配置与状态文件，Pino 输出日志，Biome 负责格式与静态检查。按当前要求，不添加测试文件、测试命令或测试依赖。
+Open a private chat with your bot and send these messages one at a time. Replace the example path with an existing absolute project path on your server:
 
-使用 Node.js 自带的 npm 管理依赖，提交 `package-lock.json`，通过 `npm ci` 安装。需要 Node.js 24.5.0 或更高版本，以使用[内置代理支持](https://nodejs.org/docs/latest-v24.x/api/http.html#built-in-proxy-support)；`.nvmrc` 固定开发环境为 Node.js 24.22.1，使用现有 nvm 切换运行时。
+```text
+/start
+/cwd /home/you/projects/my-app
+Help me understand this project. Explain its main modules and how to run it.
+```
 
-## 目录与扩展
+Send more text to continue the same conversation. Messages sent while a task is running become additional instructions for that task. For example:
 
 ```text
-src/
-├── cli.ts               # 全局命令与交互配置向导
-├── systemd.ts           # systemd 用户服务的启停、状态和日志
-├── main.ts              # 组件组装、启动和退出
-├── config.ts            # 用户配置、环境变量覆盖与校验
-├── logger.ts            # 结构化日志与敏感字段隐藏
-├── agents/
-│   └── codex.ts         # Codex app-server 连接、续聊、执行和中断
-├── im/
-│   └── telegram.ts      # Telegram 鉴权、消息转换和发送
-├── core/
-│   ├── relay.ts         # 命令处理与单任务执行
-│   └── types.ts         # 跨模块共用的消息与 Agent 接口
-└── storage/
-    ├── store.ts         # 状态读写、恢复和单实例锁
-    ├── schema.ts        # JSON 状态结构校验
-    └── json.ts          # 配置与状态共用的原子写入
+Focus on the login flow. Analyze the problem and suggest changes first.
 ```
 
-新增 IM 时，在 `im/` 添加连接器，把授权后的消息转换为 `IncomingMessage` 并调用核心入口。新增 Agent 时，在 `agents/` 实现 `Agent` 的执行和停止接口；审批接口随实际交互能力扩展。核心层不使用 grammY 或 Codex 协议类型，不引入插件注册器、基类或依赖注入框架。
+Without `/cwd`, the working directory defaults to the directory where the service starts. The systemd service starts in the current user's home directory. Changing directories starts a new conversation.
 
-`config.json` 保存 Telegram 凭据、本人 ID、Codex 路径和可选的 `telegram.proxyUrl`。
-`state.json` 保存聊天与当前会话、工作目录、任务输入与最终结果、入站去重标识和待发送回复；发送成功或被永久拒绝后移除回复副本。Codex 自己管理完整会话历史，Tellrun 不保存流式文本、思考过程、工具原始输出或 RPC 等待状态。
+## Telegram commands
 
-JSON 更新先写同目录临时文件，刷盘后原子替换。`state.json.lock/` 是临时单实例锁目录；正常退出清理，崩溃后检查原进程已退出再回收。文件损坏或写入失败会停止服务，不自动覆盖成空状态。
+| Command               | Purpose                                                      |
+| --------------------- | ------------------------------------------------------------ |
+| `/start`, `/help`     | Show usage instructions                                      |
+| `/cwd`                | Show the current working directory                           |
+| `/cwd /absolute/path` | Change the working directory and start a new conversation    |
+| `/new`                | Start a new conversation while keeping the working directory |
+| `/status`             | Show connection, conversation, directory, and task status    |
+| `/last`               | Show the latest task's status and result                     |
+| `/stop`               | Request that the current task stop and pause new tasks       |
+| `/resume`             | Accept new tasks again without rerunning an interrupted task |
 
-## 当前源码开发启动
+Wait for the current task to finish before changing directories or starting a new conversation. After `/stop`, check the final status, then send `/resume` followed by your next task.
 
-先安装 nvm，并确保 `codex --version` 可以运行。
+## Background service
 
-```sh
-nvm install
-nvm use
-npm ci
-cp .env.example .env
-```
+These commands manage a Linux systemd user service:
+
+| Command                     | Purpose                                                      |
+| --------------------------- | ------------------------------------------------------------ |
+| `tellrun start`             | Start the background service                                 |
+| `tellrun start --enable`    | Start the service and enable it at boot                      |
+| `tellrun status`            | Show service status and data paths                           |
+| `tellrun logs`              | Show the latest 100 log entries                              |
+| `tellrun logs -f`           | Follow logs                                                  |
+| `tellrun restart`           | Restart with the current configuration or installed version  |
+| `tellrun stop`              | Stop the background service                                  |
+| `tellrun service uninstall` | Stop and remove the service, keeping configuration and state |
 
-编辑 `.env`，填写 `TELEGRAM_BOT_TOKEN` 和本人 `TELEGRAM_OWNER_ID`；用户 ID 必须是十进制正整数。`.env` 已加入 Git 忽略规则。
+On startup, Tellrun checks and enables user lingering so the service can continue after you disconnect from SSH. If permissions are insufficient, the CLI prints the command to run on your server. Use `tellrun --help` for full CLI help.
 
-当前只有以上两项必填配置，也可运行 `node dist/cli.js setup` 写入用户配置。配置与状态分别放在 `~/.tellrun/config.json`、`~/.tellrun/state.json`，开发运行与全局安装使用同一目录和单实例锁。Codex 优先使用 `CODEX_PATH`，其次使用配置文件路径，均未设置时通过 PATH 查找。日志级别固定为 `info`。无需项目清单；会话默认使用服务启动目录，可在 Telegram 中用 `/cwd` 切换，不设置目录白名单。
+### Upgrade
 
-`telegram.proxyUrl` 为可选配置，由用户按需填写。Telegram 代理优先使用非空 `TELEGRAM_PROXY_URL`，其次使用配置文件中的 `telegram.proxyUrl`；配置文件中空字符串表示明确直连。两处均未指定时，读取运行环境的 `HTTPS_PROXY` / `https_proxy`；使用代理时遵循 `NO_PROXY` / `no_proxy`（小写优先）。代理 URL 不写入服务定义或命令行参数。
+Wait for the current task to finish, then run:
 
 ```sh
-npm run dev
+tellrun stop
+npm install -g tellrun@latest
+tellrun restart
 ```
 
-启动时会取得单实例锁、加载并校验状态文件、检查 Codex CLI，再核实 Telegram 身份并启动轮询。仅响应配置的本人私聊；发给其他机器人的命令会被忽略，不支持的媒体会收到提示。若已有 Webhook 或出现轮询冲突，服务退出并给出诊断，不自动接管其他部署。
+Configuration and state live in `~/.tellrun/` and are preserved when upgrading the global package. After upgrading Node.js or Tellrun, `restart` updates the Node and CLI paths used by the service.
 
-在 Telegram 中直接发送消息即可：
+## Configuration and data
 
-```text
-hi
-```
+Run `tellrun setup` to create or update your configuration. Leave the Bot Token blank to keep the existing value.
 
-未指定工作目录的会话会记住服务启动目录；systemd 服务默认使用当前用户的主目录。需要切换时发送 `/cwd /你的项目绝对路径`，目录变化会开始新会话。后续文本沿用当前 Codex 会话。`/new` 新建会话并保留目录，`/status` 查看状态，`/last` 查看最近结果；`/stop` 停止当前任务并暂停接收，确认结果后用 `/resume` 恢复。当前全局只接受一个未结束任务，忙碌时新消息会明确提示未提交。
+| Path                         | Contents                                                                              |
+| ---------------------------- | ------------------------------------------------------------------------------------- |
+| `~/.tellrun/config.json`     | Bot Token, authorized user ID, Codex path, and optional proxy                         |
+| `~/.tellrun/state.json`      | Current conversation, working directory, task inputs and results, and pending replies |
+| `~/.tellrun/tellrun.service` | Linux background service definition                                                   |
 
-Codex 沿用本机登录、模型配置和终端代理；默认使用工作区写入与按需审批。尚未支持的审批或结构化提问会中断任务并说明原因。CLI 版本检查不代表模型可用，实际调用失败会保存状态并回复。
+Codex uses the same operating system user's authentication and model configuration, and manages its own full conversation history. Tellrun does not maintain a project directory allowlist. Access depends on operating system permissions and the Codex sandbox; Tellrun defaults to workspace write access and approvals on request.
 
-入站标识、任务和回执作为同一份快照保存，重复 Update 不会再次执行。重启会保留尚未派发的任务；执行中断且结果不确定的任务不会自动重跑，需检查后 `/resume`。关停等待 Agent 结束后释放状态锁。
+### Environment variables
 
-普通 Telegram 请求连同重试最多等待 15 秒，长轮询最多 40 秒。可恢复的发送失败会保留 outbox 并退避重试，429 遵守服务端等待时间；永久拒绝会记录日志并将回复移出队列，任务结果仍可用 `/last` 查看。发送成功但响应丢失时可能重复通知，但不会重跑任务。轮询或存储故障会停止服务，待人工或进程管理器重启。
+When running in the foreground or managing the process yourself, you can override configuration with environment variables:
 
-开发服务本身时使用 `npm run dev`。让 Agent 修改代码时可用 `npm run build && npm start`，避免源码监听重启打断正在执行的任务。
+| Variable             | Purpose                                                                       |
+| -------------------- | ----------------------------------------------------------------------------- |
+| `TELEGRAM_BOT_TOKEN` | Bot token                                                                     |
+| `TELEGRAM_OWNER_ID`  | Numeric ID of the user allowed to interact with the bot                       |
+| `CODEX_PATH`         | Codex command name or executable path                                         |
+| `TELEGRAM_PROXY_URL` | HTTP/HTTPS proxy for Telegram; overrides the configuration file when nonempty |
 
-## 本地开发
+The built-in background service does not automatically load your current terminal's environment variables or a project's `.env` file. Save the required configuration with `tellrun setup`.
 
-在项目目录执行：
+### Telegram proxy
 
-```sh
-npm ci                     # 首次安装依赖
-npm run build              # 生成 CLI 入口并设置执行权限
-npm link
-tellrun --help
-tellrun setup
-tellrun run
-```
+To use a proxy, add `"proxyUrl": "http://127.0.0.1:7890"` to the existing `telegram` object in `~/.tellrun/config.json`, then restart the service. Adjust the address and port to match your proxy. Set it to `""` to explicitly connect directly.
 
-Linux 下本地调试时，在 `setup` 中选择仅保存配置，再通过 `tellrun run` 前台运行。
+Proxy precedence is: nonempty `TELEGRAM_PROXY_URL` → `telegram.proxyUrl` in the configuration file → the running process's `https_proxy` / `HTTPS_PROXY`. Proxy connections honor `no_proxy` / `NO_PROXY`; lowercase variables take precedence. This setting only affects Telegram. Codex uses its own process's proxy environment.
 
-修改 TypeScript 后，重新执行 `npm run build`，再运行命令即可，不用重复 `npm link`。完成首次构建后，也可以单独开一个终端自动编译：
+## FAQ
 
-```sh
-npx tsc -p tsconfig.build.json --watch
+### Can I use Codex for coding from my phone?
+
+Yes. Install Codex CLI and Tellrun on your server, then chat with your bot through Telegram on your phone or desktop. Code inspection, file edits, and commands run on the server. Telegram is the interface for sending tasks, reading replies, and continuing the conversation.
+
+### How do I find my Telegram user ID?
+
+Before starting Tellrun, send a private message to your new bot. Use Telegram's [getUpdates](https://core.telegram.org/bots/api#getupdates) endpoint and find `message.from.id` for that message:
+
+```text
+https://api.telegram.org/bot<BOT_TOKEN>/getUpdates
 ```
 
-自动编译不会重启正在运行的进程，修改后需要手动重启 `tellrun run`。如果只调试业务逻辑，可以直接使用现有的 `npm run dev`，它会监听源码并自动重启。
+Replace `<BOT_TOKEN>` with your token. If Tellrun is already running, stop it first to avoid polling conflicts.
+
+### Why is the bot not replying?
+
+Check that you are using a private chat and that your configured user ID is correct. Inspect `tellrun logs`, or the terminal output if running in the foreground. The same bot cannot be used by multiple polling instances at once, and Tellrun cannot start while the bot has an active webhook.
+
+### What happens when a task needs approval?
+
+Telegram interfaces for approvals and structured questions are not available yet. Tellrun interrupts the task and explains why. Handle the request locally first, check the task state, then send `/resume` and a new message with the work you want to continue.
 
-发布前，使用实际安装包验证文件是否齐全：
+### Will tasks run again after a restart?
+
+Tasks that have not been dispatched are retained. Tasks with uncertain execution status are not automatically rerun. Check `/status` and `/last`, then use `/resume` to accept new tasks and send a new message.
+
+## Local development
 
 ```sh
-npm pack                         # 已配置自动构建
-npm install -g ./tellrun-1.0.1.tgz
-tellrun --help
+git clone https://github.com/chaoyue1998/tellrun.git
+cd tellrun
+npm ci
+npm run build
+node dist/cli.js setup
+npm run dev
 ```
 
-压缩包文件名随版本号变化，以 `npm pack` 输出为准。安装压缩包后，全局命令会改用安装包中的代码；继续通过源码调试时，在项目目录重新执行 `npm link`。
-
-## 开发命令
+Choose to save configuration without starting a background service in the setup wizard, then start the development process. Development and global installations share `~/.tellrun/`, so stop any existing instance first. You can also create a `.env` file using the repository's [.env.example](https://github.com/chaoyue1998/tellrun/blob/main/.env.example) for development configuration.
 
-| 命令             | 用途                     |
-| ---------------- | ------------------------ |
-| `npm run dev`    | 监听源码并重启           |
-| `npm run check`  | 格式、静态检查与类型检查 |
-| `npm run format` | 格式化并应用安全修复     |
-| `npm run build`  | 编译到 `dist/`           |
-| `npm start`      | 运行编译产物             |
+| Command         | Purpose                                          |
+| --------------- | ------------------------------------------------ |
+| `npm run dev`   | Watch source files and restart automatically     |
+| `npm run check` | Run formatting, static analysis, and type checks |
+| `npm run build` | Compile to `dist/`                               |
+| `npm start`     | Run the compiled application                     |
 
+When asking Codex to modify Tellrun itself, run `npm run build` followed by `npm start` so source changes do not trigger a restart during the task.
 
-上述源码开发命令从项目根目录运行，用户配置和运行状态始终保存在用户目录。
+## Documentation and feedback
 
-已在本机 Node.js 24.22.1、Codex CLI 0.165.0 验证真实回复、跨进程续聊与中断。文件存储验证覆盖去重、单实例锁、重启恢复、损坏文件与写入失败；打包检查确认包含所需编译产物。后台命令仅在隔离命令环境中检查了调用顺序和特殊路径；目标 Linux 的真实 systemd 启停、退出 SSH、开机自启及完整 M0 验证仍待完成。[Codex app-server 官方文档](https://learn.chatgpt.com/docs/app-server)
+- [Architecture and technical design](https://github.com/chaoyue1998/tellrun/blob/main/docs/architecture.md) (Chinese): implementation, storage, and deployment details.
+- [Product requirements and roadmap](https://github.com/chaoyue1998/tellrun/blob/main/docs/prd.md) (Chinese): includes planned features; this README describes what is currently available.
+- [GitHub Issues](https://github.com/chaoyue1998/tellrun/issues): report bugs or suggest improvements. Include versions, reproduction steps, and logs with credentials removed.
 
-## 文档位置
+## License
 
-设计文档保存在项目的 `docs/` 目录。原始 [产品 Pages 草案](https://chatgpt.com/space/page_8cd777a7402c8191aa928ab888cb8df8) 和 [架构 Pages 草案](https://chatgpt.com/space/page_c0f7aa829c508191b8712e93ee49b06c) 保留，后续本地修改不会自动同步到 Pages。
+[MIT](https://github.com/chaoyue1998/tellrun/blob/main/LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,207 @@
+# Tellrun — 通过 Telegram 远程使用 OpenAI Codex
+
+**Tellrun 是可自行部署的 Telegram 机器人，基于 OpenAI Codex CLI 提供远程 AI 编程、持久化会话和流式回复。**
+
+在服务器上运行 Tellrun，即可通过手机或电脑上的 Telegram 提交编码任务、继续对话和查看执行结果，无需一直保持 SSH 终端连接。
+
+[English](https://github.com/chaoyue1998/tellrun/blob/main/README.md) | **简体中文**
+
+[npm](https://www.npmjs.com/package/tellrun) · [GitHub](https://github.com/chaoyue1998/tellrun) · [问题反馈](https://github.com/chaoyue1998/tellrun/issues)
+
+[快速开始](#安装并通过-telegram-使用-codex) · [Telegram 命令](#telegram-命令) · [配置](#配置与数据) · [常见问题](#常见问题)
+
+## 功能
+
+- **远程编码**：在 Telegram 私聊中发送任务，由服务器上的 Codex 执行。
+- **连续对话**：保留当前会话上下文，通过 `/cwd` 指定项目目录，通过 `/new` 开始新会话。
+- **即时反馈**：显示输入状态与流式回复，执行期间可以继续发送文字补充要求。
+- **任务控制**：查看状态和最近结果，停止任务并暂停接收；重启后保留会话与任务记录。
+- **个人部署**：仅响应指定用户的私聊，使用长轮询接收消息，无需配置 Webhook 或开放入站端口。
+
+当前支持 **Telegram + Codex**，面向单用户，每次处理一个任务。多会话列表、独立任务排队、审批与结构化提问交互、图片和文件输入暂未支持。
+
+
+## 安装并通过 Telegram 使用 Codex
+
+### 1. 准备环境
+
+- **Node.js ≥ 24.5.0**。
+- **[Codex CLI](https://github.com/openai/codex)**：在运行 Tellrun 的同一系统用户下安装并完成登录，确认可以在终端正常使用。
+- **Telegram Bot Token**：向 [@BotFather](https://t.me/BotFather) 发送 `/newbot`，按提示创建机器人并获取 Token。参见 [Telegram 官方教程](https://core.telegram.org/bots/tutorial#obtain-your-bot-token)。
+- **本人 Telegram 数字用户 ID**：不是 `@用户名`，参见[获取方法](#如何获取-telegram-用户-id)。
+
+后台管理需要支持 **systemd 用户服务的 Linux**。本地调试或使用其他进程管理器时，可通过 `tellrun run` 前台运行。
+
+### 2. 安装并配置
+
+```sh
+npm install -g tellrun
+tellrun setup
+```
+
+按向导填写 Bot Token、本人数字用户 ID 和 Codex 命令或可执行文件路径。Linux 下可以在配置完成后直接启动后台服务，并选择开机自启。
+
+如果选择了仅保存配置，之后运行：
+
+```sh
+tellrun start --enable
+```
+
+前台运行时使用：
+
+```sh
+tellrun run
+```
+
+### 3. 在 Telegram 中开始对话
+
+打开与机器人的私聊，依次发送以下消息，将示例目录替换为服务器上实际存在的项目绝对路径：
+
+```text
+/start
+/cwd /home/you/projects/my-app
+帮我了解这个项目，说明主要模块和启动方式。
+```
+
+之后直接发送文字即可继续当前会话；任务执行中发送的新消息会补充到当前任务。例如：
+
+```text
+重点看一下登录流程，先分析问题并给出修改建议。
+```
+
+未设置 `/cwd` 时，工作目录默认为服务启动目录；systemd 服务默认使用当前用户的主目录。切换目录会开始新会话。
+
+## Telegram 命令
+
+| 命令                  | 作用                                       |
+| --------------------- | ------------------------------------------ |
+| `/start`、`/help`     | 查看使用说明                               |
+| `/cwd`                | 查看当前工作目录                           |
+| `/cwd /absolute/path` | 切换工作目录并开始新会话                   |
+| `/new`                | 开始新会话，保留工作目录                   |
+| `/status`             | 查看连接、会话、目录和任务状态             |
+| `/last`               | 查看最近任务的状态与结果                   |
+| `/stop`               | 请求停止当前任务，并暂停接收新任务         |
+| `/resume`             | 恢复接收新任务，不会重新执行此前中断的任务 |
+
+切换目录或新建会话前，需要等待当前任务结束。使用 `/stop` 后，先检查最终状态，再发送 `/resume` 和新的任务内容。
+
+## 后台服务
+
+以下命令用于 Linux systemd 用户服务：
+
+| 命令                        | 作用                           |
+| --------------------------- | ------------------------------ |
+| `tellrun start`             | 启动后台服务                   |
+| `tellrun start --enable`    | 启动服务并启用开机自启         |
+| `tellrun status`            | 查看服务状态与数据路径         |
+| `tellrun logs`              | 查看最近 100 条日志            |
+| `tellrun logs -f`           | 持续跟随日志                   |
+| `tellrun restart`           | 重启服务，加载新配置或新版本   |
+| `tellrun stop`              | 停止后台服务                   |
+| `tellrun service uninstall` | 停止并移除服务，保留配置和状态 |
+
+启动时会检查并启用用户 linger，使服务在退出 SSH 后继续运行。若权限不足，CLI 会显示需要在服务器执行的命令。完整命令帮助见 `tellrun --help`。
+
+### 升级
+
+等待当前任务结束后执行：
+
+```sh
+tellrun stop
+npm install -g tellrun@latest
+tellrun restart
+```
+
+配置与状态保存在 `~/.tellrun/`，全局包升级会保留这些数据。升级 Node.js 或 Tellrun 后，`restart` 会更新服务使用的 Node 和 CLI 入口路径。
+
+## 配置与数据
+
+运行 `tellrun setup` 创建或更新配置，已有 Bot Token 可留空保留原值。
+
+| 路径                         | 内容                                           |
+| ---------------------------- | ---------------------------------------------- |
+| `~/.tellrun/config.json`     | Bot Token、授权用户 ID、Codex 路径和可选代理   |
+| `~/.tellrun/state.json`      | 当前会话、工作目录、任务输入与结果、待发送回复 |
+| `~/.tellrun/tellrun.service` | Linux 后台服务定义                             |
+
+Codex 使用同一系统用户的登录和模型配置，完整会话历史由 Codex 管理。Tellrun 不设置项目目录白名单；可访问范围由运行用户权限和 Codex 沙箱共同决定，默认采用工作区写入与按需审批策略。
+
+### 环境变量
+
+前台运行或自行托管进程时，可以使用环境变量覆盖配置：
+
+| 变量                 | 用途                                            |
+| -------------------- | ----------------------------------------------- |
+| `TELEGRAM_BOT_TOKEN` | 机器人 Token                                    |
+| `TELEGRAM_OWNER_ID`  | 允许操作机器人的数字用户 ID                     |
+| `CODEX_PATH`         | Codex 命令名或可执行文件路径                    |
+| `TELEGRAM_PROXY_URL` | Telegram 的 HTTP/HTTPS 代理，非空时覆盖配置文件 |
+
+内置后台服务不会自动读取当前终端的环境变量或项目 `.env`，请使用 `tellrun setup` 保存必要配置。
+
+### Telegram 代理
+
+需要代理时，在已有 `~/.tellrun/config.json` 的 `telegram` 对象中添加 `"proxyUrl": "http://127.0.0.1:7890"`，再重启服务。端口和地址按实际代理调整；设置为 `""` 表示明确直连。
+
+代理优先级为：非空 `TELEGRAM_PROXY_URL` → 配置文件中的 `telegram.proxyUrl` → 运行进程的 `https_proxy` / `HTTPS_PROXY`。使用代理时遵循 `no_proxy` / `NO_PROXY`，同名变量以小写优先。此配置仅影响 Telegram；Codex 使用其进程自身的代理环境。
+
+## 常见问题
+
+### 可以在手机上使用 Codex 编程吗？
+
+可以。先在服务器上安装 Codex CLI 和 Tellrun，再通过手机或电脑上的 Telegram 与机器人私聊。代码读取、修改和命令执行都在服务器上完成，Telegram 用于发送任务、查看回复和继续对话。
+
+### 如何获取 Telegram 用户 ID？
+
+在启动 Tellrun 前，先向新建的机器人发送一条私聊消息，再通过 Telegram 的 [getUpdates](https://core.telegram.org/bots/api#getupdates) 接口查看该消息的 `message.from.id`：
+
+```text
+https://api.telegram.org/bot<BOT_TOKEN>/getUpdates
+```
+
+将 `<BOT_TOKEN>` 替换为自己的 Token。若 Tellrun 已在运行，先停止服务，避免同时轮询。
+
+### 机器人没有回复怎么办？
+
+确认是在私聊中使用、配置的用户 ID 正确，并查看 `tellrun logs`；前台运行时查看终端输出。同一个 Bot 不能同时由多个轮询实例使用，也不能在已有 Webhook 的情况下启动 Tellrun。
+
+### 任务需要审批时会怎样？
+
+当前还没有 Telegram 审批和结构化提问界面。遇到这类请求时，Tellrun 会中断任务并提示原因。请先在本机处理，确认状态后发送 `/resume`，再提交需要继续的内容。
+
+### 服务重启后会重新执行任务吗？
+
+尚未派发的任务会保留；执行状态不确定的任务不会自动重跑。通过 `/status` 和 `/last` 检查结果后，发送 `/resume` 恢复接收，再发送新消息。
+
+## 本地开发
+
+```sh
+git clone https://github.com/chaoyue1998/tellrun.git
+cd tellrun
+npm ci
+npm run build
+node dist/cli.js setup
+npm run dev
+```
+
+在配置向导中选择仅保存配置，再启动开发进程。开发环境与全局安装共用 `~/.tellrun/`，请先停止已有实例。也可参考仓库中的 [.env.example](https://github.com/chaoyue1998/tellrun/blob/main/.env.example)，创建 `.env` 提供开发配置。
+
+| 命令            | 用途                     |
+| --------------- | ------------------------ |
+| `npm run dev`   | 监听源码并自动重启       |
+| `npm run check` | 格式、静态检查与类型检查 |
+| `npm run build` | 编译到 `dist/`           |
+| `npm start`     | 运行编译产物             |
+
+如果让 Codex 修改 Tellrun 自身，使用 `npm run build` 后执行 `npm start`，避免源码监听重启打断任务。
+
+## 文档与反馈
+
+- [架构与技术选型](https://github.com/chaoyue1998/tellrun/blob/main/docs/architecture.md)：实现、存储和部署细节。
+- [产品需求与规划](https://github.com/chaoyue1998/tellrun/blob/main/docs/prd.md)：包含尚未实现的功能，当前能力以本 README 为准。
+- [GitHub Issues](https://github.com/chaoyue1998/tellrun/issues)：提交问题或建议，请附上版本、复现步骤和去除凭据后的日志。
+
+## 许可证
+
+[MIT](https://github.com/chaoyue1998/tellrun/blob/main/LICENSE)