codeclaw 0.2.1 → 0.2.2

package/README.md

@@ -8,7 +8,6 @@ IM 交互体验最好的远程编程工具。没有之一。
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js 18+](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org)
-[![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen.svg)]()
 [![npm](https://img.shields.io/npm/v/codeclaw)](https://www.npmjs.com/package/codeclaw)
 
 [English](#english) | [中文](#中文)
@@ -25,10 +24,9 @@ Most "AI + IM" bridges just forward messages. codeclaw is built from scratch for
 
 - **Real-time streaming** — token-by-token output via Telegram message edits; you see the AI thinking live, not a wall of text after 2 minutes
 - **System-level keep-alive** — triggers OS-level power assertions to prevent your laptop from sleeping, so long-running tasks finish even when you walk away
-- **Dual engine hot-switch** — Claude Code + Codex CLI, switch with a single command
-- **Battle mode** — run both engines in parallel on the same prompt, compare side-by-side
+- **Multi-agent hot-switch** — Claude Code + Codex CLI, switch with a single `/agents` command
 - **True multi-session** — named sessions with persistent thread IDs; restart codeclaw, resume exactly where you left off
-- **Zero dependencies, one command** — pure Node.js stdlib, `npx codeclaw` and you're running
+- **One command** — `npx codeclaw` and you're running
 
 ```
 Telegram (your phone / desktop)
@@ -42,62 +40,21 @@ your codebase
 
 No server. No Docker. No config files. Just one process bridging Telegram to your local AI agent.
 
-## Comparison with Alternatives
-
-### vs. Claude Code + Telegram Projects
-
-| Feature | codeclaw | claude-code-telegram | claudecode-telegram | claude-telegram-bot-bridge | ccbot | claudegram |
-|---------|----------|---------------------|--------------------|-----------------------------|-------|------------|
-| Streaming output (live edits) | **Yes** | Yes | Partial | Partial | No | No |
-| Dual engine (Claude + Codex) | **Yes** | No | No | No | No | No |
-| Battle mode (parallel compare) | **Yes** | No | No | No | No | No |
-| Multi-session management | **Yes** | Yes | No | No | Partial (tmux) | No |
-| Session persistence (resume after restart) | **Yes** | Yes | No | No | Partial | No |
-| Keep-alive (prevent system sleep) | **Yes** | No | No | No | No | No |
-| Zero dependencies | **Yes** | No | No | No | No (tmux) | No |
-| npx one-command start | **Yes** | No | No | No | No | No |
-| Image/photo input support | **Yes** | Partial | No | No | No | No |
-| Paginated long output | **Yes** | No | No | No | N/A | No |
-| Access control (user/chat whitelist) | **Yes** | Partial | No | No | No | No |
-
-### vs. Multi-IM / Multi-Engine Platforms
-
-| Feature | codeclaw | cc-connect | OpenClaw | Claude-to-IM-skill | heyagent |
-|---------|----------|------------|----------|---------------------|----------|
-| IM platforms | Telegram | Telegram, Slack, Discord, 飞书, 钉钉, LINE, 企业微信 | 20+ (Telegram, WhatsApp, Slack, Discord, Signal, iMessage...) | Telegram, Discord, 飞书 | Telegram |
-| AI engines | Claude Code, Codex | Claude Code, Codex, Gemini, Cursor | Claude, Codex, local LLM | Claude Code, Codex | Claude Code, Codex |
-| Streaming (live token output) | **Yes** | Partial | Partial | No | No |
-| Battle mode | **Yes** | No | No | No | No |
-| Keep-alive (prevent sleep) | **Yes** | No | No | No | No |
-| Zero dependencies | **Yes** | No | No | No | No |
-| Setup time | **~10 seconds** | Minutes | Minutes | Minutes | Minutes |
-| Config files needed | **0** | YAML | YAML + plugins | Config | Config |
-
-> **Our philosophy:** codeclaw intentionally focuses on **one IM channel done right** rather than many done poorly. If you need 20 IM platforms, use OpenClaw or cc-connect. If you want **the best Telegram remote coding experience** — the fastest streaming, the smoothest interaction, and zero setup friction — use codeclaw.
-
-### Keep-Alive: Your Laptop Stays Awake
-
-When codeclaw is running, it triggers **OS-level power assertions** to prevent your machine from sleeping. This means:
-
-- Long-running AI tasks (refactoring, large codegen, test suites) **complete reliably** even if you walk away from the keyboard
-- No more coming back to find your screen locked, SSH session dropped, or AI agent frozen mid-task due to idle sleep
-- Works on **macOS** (caffeinate) and **Linux** (systemd-inhibit)
-
-This is a critical feature for remote coding — you send a task from your phone, the laptop stays awake and keeps working. (Note: closing the lid on most laptops will still trigger hardware-level sleep — keep the lid open for best results.)
-
 ## Features
 
-- **Dual engine** — Claude Code + Codex CLI, hot-switch with `/engine`
+- **Multi-agent** — Claude Code + Codex CLI, hot-switch via `/agents` inline keyboard
 - **Streaming** — real-time token-by-token output via Telegram message edits
-- **Battle mode** — `/battle <prompt>` runs both engines in parallel, compare side-by-side
-- **Multi-session** — per-chat session management with named sessions and thread resume
-- **Keep-alive** — OS-level sleep prevention ensures long tasks complete uninterrupted
-- **Full access / safe mode** — let the agent run freely, or lock it down
-- **Zero dependencies** — pure Node.js stdlib, no npm install needed
+- **Multi-session** — per-chat session management with named sessions, pagination, and resume
+- **Keep-alive** — OS-level sleep prevention (macOS `caffeinate`, Linux `systemd-inhibit`)
+- **Directory browser** — switch working directory interactively via `/switch` with inline navigation
 - **Image input** — send photos to the bot for visual context (screenshots, diagrams)
-- **Paginated output** — long responses are split into navigable pages with inline buttons
-- **Auto-start notice** — sends online status to all known chats on startup
+- **Quick replies** — auto-detects yes/no questions and numbered options, shows inline buttons
+- **Long output** — responses exceeding Telegram limits are split with a full `.md` file attachment
+- **Thinking display** — shows agent thinking/reasoning process in collapsible blocks
+- **Token tracking** — per-turn and cumulative input/output/cached token counts
 - **Access control** — restrict by chat/user ID whitelist
+- **Startup notice** — sends online status to all known chats on startup
+- **Full access / safe mode** — let the agent run freely, or require confirmation before destructive actions
 
 ## Quick Start
 
@@ -116,7 +73,7 @@ cd your-project/
 codeclaw -t YOUR_BOT_TOKEN
 ```
 
-> **Prerequisites:** Node.js 18+, `claude` CLI and/or `codex` CLI in PATH, a Telegram Bot Token from [@BotFather](https://t.me/BotFather).
+> **Prerequisites:** Node.js 18+, `claude` CLI and/or `codex` CLI installed, a Telegram Bot Token from [@BotFather](https://t.me/BotFather).
 
 ## CLI Options
 
@@ -128,31 +85,39 @@ codeclaw [options]
 
 | Flag | Env | Default | Description |
 |------|-----|---------|-------------|
-| `-c, --channel` | `CODECLAW_CHANNEL` | `telegram` | IM channel |
-| `-t, --token` | `CODECLAW_TOKEN` | — | Bot token |
-| `-e, --engine` | `DEFAULT_ENGINE` | `claude` | AI engine: `claude` or `codex` |
-| `-w, --workdir` | `CODECLAW_WORKDIR` | `.` | Working directory |
-| `-m, --model` | `CLAUDE_MODEL` / `CODEX_MODEL` | — | Model override |
+| `-c, --channel` | `CODECLAW_CHANNEL` | `telegram` | IM channel: `telegram` (feishu, whatsapp planned) |
+| `-t, --token` | `CODECLAW_TOKEN` | — | Bot token (or channel-specific env below) |
+| `-a, --agent` | `DEFAULT_AGENT` | `claude` | AI agent: `claude` or `codex` |
+| `-m, --model` | — | `claude-opus-4-6` / `gpt-5.4` | Model override (maps to agent-specific env) |
+| `-w, --workdir` | `CODECLAW_WORKDIR` | `.` | Working directory for the agent |
 
 ### Access Control
 
 | Flag | Env | Default | Description |
 |------|-----|---------|-------------|
 | `--full-access` | `CODECLAW_FULL_ACCESS` | `true` | Agent can read/write/execute without confirmation |
-| `--safe-mode` | `CODECLAW_SAFE_MODE` | `false` | Agent asks before destructive operations |
-| `--allowed-ids` | `CODECLAW_ALLOWED_IDS` | — | Comma-separated user/chat IDs whitelist |
-| `--timeout` | `CODECLAW_TIMEOUT` | `300` | Max seconds per request |
+| `--safe-mode` | — | `false` | Require confirmation before destructive operations |
+| `--allowed-ids` | `TELEGRAM_ALLOWED_CHAT_IDS` | — | Comma-separated chat/user ID whitelist |
+| `--timeout` | `CODECLAW_TIMEOUT` | `300` | Max seconds per agent request |
 
-### Engine-specific
+### Channel-specific Environment Variables
 
 | Env | Description |
 |-----|-------------|
-| `CLAUDE_MODEL` | Claude model (e.g. `sonnet`, `opus`) |
-| `CLAUDE_PERMISSION_MODE` | `bypassPermissions` (default) or `default` |
-| `CLAUDE_EXTRA_ARGS` | Extra CLI args passed to `claude` |
-| `CODEX_MODEL` | Codex model (e.g. `o3`, `o4-mini`) |
-| `CODEX_REASONING_EFFORT` | `none` / `minimal` / `low` / `medium` / `high` / `xhigh` |
-| `CODEX_EXTRA_ARGS` | Extra CLI args passed to `codex` |
+| `TELEGRAM_BOT_TOKEN` | Telegram bot token (from @BotFather) |
+| `TELEGRAM_ALLOWED_CHAT_IDS` | Comma-separated allowed Telegram chat IDs |
+
+### Agent-specific Environment Variables
+
+| Env | Default | Description |
+|-----|---------|-------------|
+| `CLAUDE_MODEL` | `claude-opus-4-6` | Claude model name |
+| `CLAUDE_PERMISSION_MODE` | `bypassPermissions` | `bypassPermissions` or `default` |
+| `CLAUDE_EXTRA_ARGS` | — | Extra CLI args passed to `claude` |
+| `CODEX_MODEL` | `gpt-5.4` | Codex model name |
+| `CODEX_REASONING_EFFORT` | `xhigh` | `none` / `minimal` / `low` / `medium` / `high` / `xhigh` |
+| `CODEX_FULL_ACCESS` | `true` | Bypass sandbox and approval prompts |
+| `CODEX_EXTRA_ARGS` | — | Extra CLI args passed to `codex` |
 
 ### Examples
 
@@ -160,31 +125,63 @@ codeclaw [options]
 # Basic: Telegram + Claude Code, full access
 npx codeclaw -t $BOT_TOKEN
 
-# Codex engine, safe mode, restricted users
-npx codeclaw -t $BOT_TOKEN -e codex --safe-mode --allowed-ids 123456,789012
+# Codex agent, safe mode, restricted users
+npx codeclaw -t $BOT_TOKEN -a codex --safe-mode --allowed-ids 123456,789012
 
 # Custom model, custom working directory
 npx codeclaw -t $BOT_TOKEN -m sonnet -w ~/projects/my-app
 
-# Validate setup without starting
-npx codeclaw -t $BOT_TOKEN --self-check
+# Using environment variables
+TELEGRAM_BOT_TOKEN=xxx CODEX_MODEL=o3 npx codeclaw -a codex
 ```
 
 ## Bot Commands
 
+Once running, these commands are available in Telegram:
+
 | Command | Description |
 |---------|-------------|
-| `/ask <prompt>` | Ask the AI agent |
-| `/engine [codex\|claude]` | Show or switch engine |
-| `/battle <prompt>` | Run both engines, compare results |
-| `/new [prompt]` | Reset session (optionally start new one) |
-| `/session list\|use\|new\|del` | Multi-session management |
-| `/status` | Show current session / engine / thread info |
-| `/stop` | Clear current session thread |
-| `/clear [N]` | Delete bot's recent messages (default 50) |
-| `/help` | Show all commands |
-
-> In private/DM chats, just send text directly — no command prefix needed.
+| `/sessions` | List, switch, or create sessions (paginated inline keyboard) |
+| `/agents` | List installed agents, switch between them |
+| `/switch` | Browse and change working directory (interactive file browser) |
+| `/status` | Bot status: uptime, memory, agent, session, token usage |
+| `/host` | Host machine info: CPU, memory, disk, top processes |
+| `/start` | Welcome message with command list |
+
+> In private chats, just send text directly — no command prefix needed. Any unrecognized `/command` is forwarded to the agent as a prompt.
+
+## Development
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Create .env file with your tokens
+echo "TELEGRAM_BOT_TOKEN=your_token_here" > .env
+
+# 3. Run locally
+set -a && source .env && npx tsx src/cli.ts
+
+# 4. Run tests
+npm test
+```
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the layered design:
+
+```
+cli.ts → bot-telegram.ts → bot.ts → code-agent.ts
+                ↓
+         channel-telegram.ts
+```
+
+- **bot.ts** — channel-agnostic business logic, state, streaming bridge
+- **bot-telegram.ts** — Telegram-specific rendering, keyboards, callbacks
+- **channel-telegram.ts** — pure Telegram API transport (polling, sending, file download)
+- **code-agent.ts** — AI agent abstraction (spawn CLI, parse JSONL stream)
+
+Adding a new IM channel means creating `channel-xxx.ts` + `bot-xxx.ts` without touching shared logic.
 
 ## License
 
@@ -208,10 +205,9 @@ npx codeclaw -t $BOT_TOKEN --self-check
 
 - **实时流式输出** — 通过 Telegram 消息编辑逐 token 推送；你能实时看到 AI 的思考过程，而不是等 2 分钟后收到一大段文字
 - **系统级保活** — 触发操作系统级电源断言，防止笔记本休眠，确保长时间任务在你离开后依然完整执行
-- **双引擎热切换** — Claude Code + Codex CLI，一条命令即可切换
-- **对战模式** — 同一个 prompt 同时跑两个引擎，结果并排对比
+- **多 Agent 热切换** — Claude Code + Codex CLI，一条 `/agents` 命令即可切换
 - **真正的多会话** — 命名会话 + 持久化线程 ID；重启 codeclaw 后可以无缝恢复之前的对话
-- **零依赖、一条命令** — 纯 Node.js 标准库，`npx codeclaw` 即可运行
+- **一条命令启动** — `npx codeclaw` 即可运行
 
 ```
 Telegram（手机 / 桌面端）
@@ -225,62 +221,21 @@ claude / codex CLI
 
 不需要服务器，不需要 Docker，不需要配置文件。一个进程把 Telegram 桥接到你本地的 AI 编程助手。
 
-## 竞品对比
-
-### vs. Claude Code + Telegram 专项工具
-
-| 特性 | codeclaw | claude-code-telegram | claudecode-telegram | claude-telegram-bot-bridge | ccbot | claudegram |
-|------|----------|---------------------|--------------------|-----------------------------|-------|------------|
-| 流式输出（实时编辑） | **支持** | 支持 | 部分 | 部分 | 不支持 | 不支持 |
-| 双引擎（Claude + Codex） | **支持** | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 |
-| 对战模式（并行对比） | **支持** | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 |
-| 多会话管理 | **支持** | 支持 | 不支持 | 不支持 | 部分（tmux） | 不支持 |
-| 会话持久化（重启恢复） | **支持** | 支持 | 不支持 | 不支持 | 部分 | 不支持 |
-| 保活（防止系统休眠） | **支持** | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 |
-| 零依赖 | **是** | 否（Node.js） | 否 | 否 | 否（tmux） | 否 |
-| npx 一键启动 | **是** | 否 | 否 | 否 | 否 | 否 |
-| 图片输入支持 | **支持** | 部分 | 不支持 | 不支持 | 不支持 | 不支持 |
-| 长文本分页 | **支持** | 不支持 | 不支持 | 不支持 | N/A | 不支持 |
-| 访问控制（白名单） | **支持** | 部分 | 不支持 | 不支持 | 不支持 | 不支持 |
-
-### vs. 多 IM / 多引擎平台
-
-| 特性 | codeclaw | cc-connect | OpenClaw | Claude-to-IM-skill | heyagent |
-|------|----------|------------|----------|---------------------|----------|
-| IM 平台 | Telegram | Telegram、Slack、Discord、飞书、钉钉、LINE、企业微信 | 20+（Telegram、WhatsApp、Slack、Discord、Signal、iMessage…） | Telegram、Discord、飞书 | Telegram |
-| AI 引擎 | Claude Code、Codex | Claude Code、Codex、Gemini、Cursor | Claude、Codex、本地 LLM | Claude Code、Codex | Claude Code、Codex |
-| 流式输出（实时 token） | **支持** | 部分 | 部分 | 不支持 | 不支持 |
-| 对战模式 | **支持** | 不支持 | 不支持 | 不支持 | 不支持 |
-| 保活（防休眠） | **支持** | 不支持 | 不支持 | 不支持 | 不支持 |
-| 零依赖 | **是** | 否 | 否 | 否 | 否 |
-| 部署时间 | **约 10 秒** | 数分钟 | 数分钟 | 数分钟 | 数分钟 |
-| 需要配置文件 | **0 个** | YAML | YAML + 插件 | 配置文件 | 配置文件 |
-
-> **我们的理念：** codeclaw 有意专注于 **把一个 IM 渠道做到极致**，而非什么都做但都做不好。如果你需要 20 个 IM 平台，用 OpenClaw 或 cc-connect。如果你想要 **最好的 Telegram 远程编程体验** —— 最快的流式输出、最流畅的交互、零配置摩擦 —— 用 codeclaw。
-
-### 保活：你的笔记本始终亮屏
-
-codeclaw 运行时会触发 **操作系统级电源断言**，防止你的机器进入休眠。这意味着：
-
-- 长时间 AI 任务（重构、大量代码生成、测试套件）即使你 **离开键盘** 也能可靠完成
-- 不再出现回来发现屏幕锁定、SSH 断开、AI 跑到一半因空闲休眠而卡住的情况
-- 支持 **macOS**（caffeinate）和 **Linux**（systemd-inhibit）
-
-这是远程编程的关键功能 —— 你从手机上发一个任务，笔记本保持唤醒状态持续工作。（注意：合上盖子在大多数笔记本上仍会触发硬件级休眠，建议保持开盖。）
-
 ## 功能特性
 
-- **双引擎** — Claude Code + Codex CLI，用 `/engine` 命令热切换
+- **多 Agent** — Claude Code + Codex CLI，通过 `/agents` 内联键盘热切换
 - **流式输出** — 通过 Telegram 消息编辑实时逐 token 输出
-- **对战模式** — `/battle <prompt>` 同时运行两个引擎，结果并排对比
-- **多会话** — 每个聊天支持命名会话管理和线程恢复
-- **系统保活** — 操作系统级防休眠，确保长任务不中断
-- **完全访问 / 安全模式** — 让 AI 自由运行，或限制危险操作需确认
-- **零依赖** — 纯 Node.js 标准库，无需 npm install
+- **多会话** — 每个聊天支持命名会话管理、分页浏览和线程恢复
+- **系统保活** — 操作系统级防休眠（macOS `caffeinate`、Linux `systemd-inhibit`）
+- **目录浏览器** — 通过 `/switch` 交互式切换工作目录，内联导航
 - **图片输入** — 向机器人发送图片提供视觉上下文（截图、设计图）
-- **长文本分页** — 长回复自动分页，内联按钮翻页浏览
-- **启动通知** — 启动时向所有已知聊天发送在线状态
+- **快捷回复** — 自动检测是/否问题和编号选项，显示内联按钮
+- **长文本处理** — 超出 Telegram 限制的回复自动拆分，并附带完整 `.md` 文件
+- **思考展示** — 在可折叠区块中显示 Agent 的思考/推理过程
+- **Token 统计** — 每轮和累计的输入/输出/缓存 token 计数
 - **访问控制** — 按聊天/用户 ID 白名单限制
+- **启动通知** — 启动时向所有已知聊天发送在线状态
+- **完全访问 / 安全模式** — 让 AI 自由运行，或限制危险操作需确认
 
 ## 快速开始
 
@@ -299,7 +254,7 @@ cd your-project/
 codeclaw -t YOUR_BOT_TOKEN
 ```
 
-> **前置条件：** Node.js 18+，`claude` CLI 和/或 `codex` CLI 在 PATH 中，从 [@BotFather](https://t.me/BotFather) 获取 Telegram Bot Token。
+> **前置条件：** Node.js 18+，`claude` CLI 和/或 `codex` CLI 已安装，从 [@BotFather](https://t.me/BotFather) 获取 Telegram Bot Token。
 
 ## 命令行选项
 
@@ -311,31 +266,39 @@ codeclaw [选项]
 
 | 参数 | 环境变量 | 默认值 | 说明 |
 |------|---------|--------|------|
-| `-c, --channel` | `CODECLAW_CHANNEL` | `telegram` | IM 渠道 |
-| `-t, --token` | `CODECLAW_TOKEN` | — | Bot token |
-| `-e, --engine` | `DEFAULT_ENGINE` | `claude` | AI 引擎：`claude` 或 `codex` |
+| `-c, --channel` | `CODECLAW_CHANNEL` | `telegram` | IM 渠道：`telegram`（feishu、whatsapp 规划中） |
+| `-t, --token` | `CODECLAW_TOKEN` | — | Bot token（或下方渠道专属环境变量） |
+| `-a, --agent` | `DEFAULT_AGENT` | `claude` | AI Agent：`claude` 或 `codex` |
+| `-m, --model` | — | `claude-opus-4-6` / `gpt-5.4` | 模型覆盖（映射到 Agent 专属环境变量） |
 | `-w, --workdir` | `CODECLAW_WORKDIR` | `.` | 工作目录 |
-| `-m, --model` | `CLAUDE_MODEL` / `CODEX_MODEL` | — | 模型覆盖 |
 
 ### 访问控制
 
 | 参数 | 环境变量 | 默认值 | 说明 |
 |------|---------|--------|------|
-| `--full-access` | `CODECLAW_FULL_ACCESS` | `true` | AI 可以无需确认地读写执行 |
-| `--safe-mode` | `CODECLAW_SAFE_MODE` | `false` | AI 在执行危险操作前需确认 |
-| `--allowed-ids` | `CODECLAW_ALLOWED_IDS` | — | 允许交互的用户/聊天 ID，逗号分隔 |
+| `--full-access` | `CODECLAW_FULL_ACCESS` | `true` | Agent 可以无需确认地读写执行 |
+| `--safe-mode` | — | `false` | 执行危险操作前需确认 |
+| `--allowed-ids` | `TELEGRAM_ALLOWED_CHAT_IDS` | — | 允许交互的聊天/用户 ID，逗号分隔 |
 | `--timeout` | `CODECLAW_TIMEOUT` | `300` | 每次请求最大秒数 |
 
-### 引擎专属配置
+### 渠道专属环境变量
 
 | 环境变量 | 说明 |
 |---------|------|
-| `CLAUDE_MODEL` | Claude 模型（如 `sonnet`、`opus`） |
-| `CLAUDE_PERMISSION_MODE` | `bypassPermissions`（默认）或 `default` |
-| `CLAUDE_EXTRA_ARGS` | 传递给 `claude` CLI 的额外参数 |
-| `CODEX_MODEL` | Codex 模型（如 `o3`、`o4-mini`） |
-| `CODEX_REASONING_EFFORT` | `none` / `minimal` / `low` / `medium` / `high` / `xhigh` |
-| `CODEX_EXTRA_ARGS` | 传递给 `codex` CLI 的额外参数 |
+| `TELEGRAM_BOT_TOKEN` | Telegram Bot Token（来自 @BotFather） |
+| `TELEGRAM_ALLOWED_CHAT_IDS` | 允许的 Telegram 聊天 ID，逗号分隔 |
+
+### Agent 专属环境变量
+
+| 环境变量 | 默认值 | 说明 |
+|---------|--------|------|
+| `CLAUDE_MODEL` | `claude-opus-4-6` | Claude 模型名 |
+| `CLAUDE_PERMISSION_MODE` | `bypassPermissions` | `bypassPermissions` 或 `default` |
+| `CLAUDE_EXTRA_ARGS` | — | 传递给 `claude` CLI 的额外参数 |
+| `CODEX_MODEL` | `gpt-5.4` | Codex 模型名 |
+| `CODEX_REASONING_EFFORT` | `xhigh` | `none` / `minimal` / `low` / `medium` / `high` / `xhigh` |
+| `CODEX_FULL_ACCESS` | `true` | 跳过沙箱和确认提示 |
+| `CODEX_EXTRA_ARGS` | — | 传递给 `codex` CLI 的额外参数 |
 
 ### 使用示例
 
@@ -343,31 +306,63 @@ codeclaw [选项]
 # 基本用法：Telegram + Claude Code，完全访问
 npx codeclaw -t $BOT_TOKEN
 
-# Codex 引擎，安全模式，限制用户
-npx codeclaw -t $BOT_TOKEN -e codex --safe-mode --allowed-ids 123456,789012
+# Codex Agent，安全模式，限制用户
+npx codeclaw -t $BOT_TOKEN -a codex --safe-mode --allowed-ids 123456,789012
 
 # 自定义模型和工作目录
 npx codeclaw -t $BOT_TOKEN -m sonnet -w ~/projects/my-app
 
-# 验证配置（不启动）
-npx codeclaw -t $BOT_TOKEN --self-check
+# 使用环境变量
+TELEGRAM_BOT_TOKEN=xxx CODEX_MODEL=o3 npx codeclaw -a codex
 ```
 
 ## 机器人命令
 
+运行后，以下命令可在 Telegram 中使用：
+
 | 命令 | 说明 |
 |------|------|
-| `/ask <prompt>` | 向 AI 提问 |
-| `/engine [codex\|claude]` | 查看或切换引擎 |
-| `/battle <prompt>` | 同时运行两个引擎，对比结果 |
-| `/new [prompt]` | 重置会话（可选带 prompt 开始新对话） |
-| `/session list\|use\|new\|del` | 多会话管理 |
-| `/status` | 查看当前会话/引擎/线程信息 |
-| `/stop` | 清除当前会话线程 |
-| `/clear [N]` | 删除机器人最近的消息（默认 50 条） |
-| `/help` | 显示所有命令 |
-
-> 在私聊中直接发送文字即可，无需命令前缀。
+| `/sessions` | 列出、切换或创建会话（分页内联键盘） |
+| `/agents` | 列出已安装的 Agent，切换使用 |
+| `/switch` | 浏览和切换工作目录（交互式文件浏览器） |
+| `/status` | 机器人状态：运行时间、内存、Agent、会话、Token 用量 |
+| `/host` | 宿主机信息：CPU、内存、磁盘、进程排行 |
+| `/start` | 欢迎消息和命令列表 |
+
+> 在私聊中直接发送文字即可，无需命令前缀。未识别的 `/命令` 会作为 prompt 转发给 Agent。
+
+## 本地开发
+
+```bash
+# 1. 安装依赖
+npm install
+
+# 2. 创建 .env 文件写入 token
+echo "TELEGRAM_BOT_TOKEN=your_token_here" > .env
+
+# 3. 本地运行
+set -a && source .env && npx tsx src/cli.ts
+
+# 4. 运行测试
+npm test
+```
+
+## 架构
+
+详见 [ARCHITECTURE.md](ARCHITECTURE.md)：
+
+```
+cli.ts → bot-telegram.ts → bot.ts → code-agent.ts
+                ↓
+         channel-telegram.ts
+```
+
+- **bot.ts** — 渠道无关的业务逻辑、状态管理、流式桥接
+- **bot-telegram.ts** — Telegram 专属渲染、键盘、回调处理
+- **channel-telegram.ts** — 纯 Telegram API 传输层（轮询、发送、文件下载）
+- **code-agent.ts** — AI Agent 抽象（启动 CLI 子进程、解析 JSONL 流）
+
+添加新 IM 渠道只需创建 `channel-xxx.ts` + `bot-xxx.ts`，无需修改共享逻辑。
 
 ## 许可证