1. 项目概述：一个终端AI编程工具的“统一指挥中心”

如果你和我一样，日常开发中会同时用到Claude Code、Cursor Agent、OpenAI Codex CLI这些基于终端的AI编程工具，那你一定也经历过这种混乱：为了同时处理几个不同的任务，桌面上开了三四个终端窗口，每个窗口里跑着一个不同的AI工具。你得像一个多线程CPU一样，在不同的窗口间来回切换，查看进度、输入指令。更麻烦的是，当你离开电脑，突然想起有个任务需要确认一个 y/n 的交互，或者想看看某个长任务的输出结果时，你只能干瞪眼——除非你一直开着SSH或者复杂的远程桌面。

这就是我最初开发CodeCLI的动机。它不是一个新AI工具，而是一个**“统一会话编排器”**。你可以把它想象成你所有终端AI工具的“指挥中心”或“总控台”。它把Claude Code、Cursor Agent、OpenAI Codex CLI、OpenCode乃至普通的Bash会话，都封装在一个统一的控制层之下。然后，你可以通过本地终端、Telegram、微信、HTTP API或者LangChain工具链，来统一管理和指挥所有这些会话。所有渠道共享同一套命令系统，你再也不用在多个工具和界面之间疲于奔命了。

核心价值 ：CodeCLI解决的不是“AI编码能力”的问题，而是“AI编码工具的管理和访问效率”问题。它让你能像管理Docker容器一样，去管理你的AI编码会话。

2. 核心设计思路：为什么是“编排器”而非“聚合器”

在深入代码之前，理解CodeCLI的设计哲学至关重要。市面上有些工具试图把不同AI的API聚合起来，提供一个统一的聊天界面。但CodeCLI走的是另一条路： 它不替换你现有的AI CLI工具，而是“编排”它们。

2.1 设计原则：无侵入与透明代理

CodeCLI坚持“无侵入”原则。它不要求你修改Claude Code或Cursor Agent的任何一行代码，也不提供自己的AI模型。它的工作方式是： 启动这些工具的原生可执行文件（如 claude 、 agent ），然后通过伪终端（PTY）技术，接管它们的标准输入和输出。

这意味着，你看到的输出、你进行的交互，和你直接在终端里运行这些工具几乎一模一样。CodeCLI只是中间那个“传令兵”和“翻译官”。这种设计的最大好处是 兼容性极强 。只要工具能在终端里跑，理论上CodeCLI就能管理它。未来如果出了新的AI CLI工具，为CodeCLI添加适配器通常也只需要几百行代码。

2.2 会话状态机：理解工具的生命周期

管理多个会话的核心是准确知道每个会话在干什么。CodeCLI为每个会话维护了一个精细的状态机，主要包括以下几种状态：

• idle (空闲) ：会话已启动，正在等待用户输入指令。这是最常见的状态。
• running (运行中) ：AI工具正在处理任务，输出流持续产生中。
• need_confirmation (需要确认) ：工具遇到了一个交互式提示（最常见的就是 [y/n] ），正在等待用户输入 y 、 n 或回车键。这是远程操作时最需要被“解救”的状态。
• completed (已完成) ：工具执行完一个命令后，自行结束了进程（例如， claude 回答完一个问题后退出）。此时会话仍在，但进程已终止。
• error (错误) ：工具进程因异常退出（例如，权限错误、依赖缺失）。
• stopped (已停止) ：用户通过 /stop 或 /kill 命令主动终止了会话。

这个状态机是CodeCLI所有智能功能的基础。例如，当状态检测到 need_confirmation 时，CodeCLI可以自动通知远程渠道（如你的Telegram）：“会话1需要确认，请回复 /y 或 /n ”。又比如，在 stream 输出模式下，只有状态是 running 时，才会持续推送增量输出。

2.3 多通道架构：一个大脑，多个出口

这是CodeCLI最巧妙的部分。它的核心——会话管理、命令处理、状态跟踪——是独立于通信渠道的。这个核心被称为 Chat （聊天处理器）。然后，不同的“通道”（Channel）负责与外界通信：

• cli 通道 ：本地终端，直接与 Chat 交互。
• telegram 通道 ：运行一个Telegram机器人，将收到的消息转发给 Chat ，并将 Chat 的回复发回Telegram。
• weixin 通道 ：通过微信的Web协议（itchat）登录你的微信，将指定聊天窗口的消息转发给 Chat 。
• http 通道 ：启动一个HTTP服务器，提供RESTful API，允许任何外部系统通过JSON与 Chat 交互。
• tool 通道 ：专为LangChain等AI Agent框架设计，提供结构化的函数调用接口。

所有这些通道都向一个中央的 ChannelRegistry （通道注册表）注册自己，声明自己能做什么（比如是否能发送文件、是否支持流式输出）。然后，它们都把收到的用户消息，丢给同一个 Chat._handle_message() 函数去处理。处理结果再通过原通道返回。

这种设计带来了巨大的灵活性：

1. 开发新通道极其简单 ：你只需要实现消息的“接收”和“发送”逻辑，并注册到中心，就能立刻获得管理所有AI会话的能力。
2. 状态共享 ：你在Telegram上启动了一个Claude会话，稍后可以在微信上查看它的输出，因为会话状态保存在中心的 SessionManager 里，而不是通道里。
3. 统一体验 ：无论从哪个渠道访问，你用的都是同一套命令（ /claude , /status , /y 等）。

3. 核心功能拆解与实操要点

理解了架构，我们来看看CodeCLI具体能做什么，以及在实际使用中需要注意哪些细节。

3.1 会话的启动与管理：不仅仅是 /claude

启动一个AI会话很简单，使用对应的命令即可，如 /claude /path/to/your/project 。但这里有几个关键点：

• 工作目录至关重要 ：几乎所有AI编码工具都需要一个上下文。 /claude /home/user/project 意味着Claude将以 /home/user/project 为当前目录启动，它能读取该目录下的文件来理解项目结构。如果你不指定路径，CodeCLI会使用它自己运行时的工作目录，这通常不是你想要的。
• 可执行文件路径 ：CodeCLI默认会从系统的 PATH 环境变量中寻找 claude 、 agent 等命令。如果你的工具安装在了非标准位置（比如用 pipx install --user 安装的），你需要在 config/codecli.json 的 cli_path 部分进行覆盖：

  "cli_path": {
      "claude": "/home/yourname/.local/bin/claude",
      "cursor": "/path/to/cursor/agent"
  }
  

• 并发会话 ：你可以同时启动多个同类型或不同类型的会话。例如， /claude ~/project_a 启动会话1， /cursor ~/project_b 启动会话2。它们完全独立运行，互不干扰。使用 /list 命令可以查看所有活跃会话。

3.2 命令系统详解：从基础到高级

CodeCLI的命令设计遵循“简洁但强大”的原则。所有命令都以 / 开头，避免与普通的聊天文本混淆。

基础操作命令：

• /status [id] : 查看指定会话（默认为当前活跃会话）的详细状态，包括PID、工作目录、运行时间、当前状态等。这是最常用的诊断命令。
• /output [id] : 获取该会话的最后一次完整输出。在 result 模式下，这就是AI返回的最终答案。
• /screen [id] : 获取会话的“当前屏幕”快照。这对于调试那些有复杂TUI（终端用户界面）的工具特别有用，它能告诉你工具现在“看起来”是什么样。
• /use <id> : 切换当前活跃会话。之后所有不指定 [id] 的命令（如直接输入文本）都将发送给这个会话。

交互式命令（远程操作的救星）： 当AI工具卡在 [y/n] 或等待回车时，这些命令就是你的遥控器。

• /y , /n : 模拟输入 y 或 n 。
• /enter , /esc , /tab : 模拟按下对应的键。
• /key <name> : 模拟按下其他组合键，例如 /key ctrl+c 发送中断信号， /key ctrl+l 清屏。

实操心得 ：很多AI CLI工具在完成一个任务后，会停留在“Press Enter to continue...”这样的提示符。如果你在远程（如Telegram）只看到输出停止了，但状态仍是 running ，很可能是遇到了这种交互。此时发一个 /enter 命令往往就能让会话回到 idle 状态，准备接收下一个任务。

会话生命周期管理：

• /stop [id] : 优雅地停止会话（发送终止信号）。对于行为良好的CLI工具，这会使其正常退出。
• /kill <id> : 强制杀死会话进程。当工具无响应时使用。
• /stopall : 停止所有会话。在结束一天工作或系统维护前使用。
• /restart <id> : 重启指定会话。这会在相同的工作目录下，重新启动同一个AI工具。适用于工具进程出现奇怪状态，但又不想丢失当前上下文的情况。

3.3 输出模式： result 与 stream 的智慧抉择

这是影响远程使用体验的核心配置。CodeCLI提供了两种输出交付策略：

1. result 模式（默认） ：CodeCLI会“耐心”等待AI工具完成当前任务，进程输出停止，状态变为 idle 或 completed 后，再将 完整的、清理过的 最终输出一次性发送给用户。这对于Telegram、微信等聊天工具非常友好，你不会被几十条中间状态消息刷屏。
2. stream 模式 ：CodeCLI会将AI工具的标准输出实时地、增量地转发给用户。你能看到进度的变化，就像在本地终端一样。这对于运行测试套件、编译等长时间任务非常有用，你可以实时知道进行到哪一步了。

如何切换？

• 使用 /mode [id] stream 或 /mode [id] result 命令手动切换某个会话的模式。
• 更智能的方式是配置 output_policy.rules 。你可以设置规则，例如：“如果用户输入中包含 test 或 run 关键字，则自动将该会话切换到 stream 模式”。这样，当你发送“请运行测试”时，CodeCLI会自动开始流式推送测试结果。

注意事项 ： stream 模式在Telegram/微信上可能会产生大量消息。有些聊天工具对消息频率有限制，可能导致发送失败或被暂时禁言。建议对于常规的代码生成、代码审查任务，坚持使用默认的 result 模式。只为明确的、长时间运行的任务开启 stream 。

3.4 路径与文件管理：让AI在正确的上下文中工作

AI编码工具的强大之处在于能理解整个项目的上下文。CodeCLI提供了一组命令来管理这个上下文。

• /cd <path> : 改变 当前活跃会话 的工作目录。注意，这改变的是AI工具进程内部的当前目录，而不是CodeCLI自身的目录。
• /pwd : 打印当前活跃会话的工作目录。
• /ls [path] : 列出当前会话工作目录（或指定路径）下的文件。这对于远程快速浏览项目结构非常方便。
• /paths : 这是CodeCLI的一个特色功能——“工作路径书签”。你可以将常用项目路径保存为别名（如 p1 , p2 ）。在配置文件中设置 worked_path 后，启动会话时可以直接用 /claude p1 ，这等价于 /claude /your/long/project/path 。
• /cat <file> : 将指定文件的内容读取并发送回来。这在远程调试时非常有用，你可以快速查看某个配置文件或日志文件的内容，而无需启动一个完整的编辑会话。

4. 多通道接入实战：从本地到远程，从人到AI

CodeCLI的强大在于其接入方式的多样性。我们逐一拆解每种方式的配置和典型使用场景。

4.1 本地CLI模式：快速上手与调试

这是最基础的模式，也是调试配置的最佳起点。

# 1. 克隆项目并安装依赖
git clone https://github.com/ax128/CodeCLI.git
cd CodeCLI
pip install -r requirements.lock  # 推荐，锁定版本保证一致性

# 2. 复制并配置核心文件
cp config/codecli.example.json config/codecli.json
# 此时，你可以先保持配置文件默认，仅用于本地CLI测试。

# 3. 启动本地CLI
python main.py cli

启动后，你会进入一个以 >>> 为提示符的交互式界面。在这里，你可以直接输入所有命令进行测试。例如，输入 /help 查看所有命令。这是验证你的Claude Code、Cursor等工具是否已正确安装并在 PATH 中的好方法。

4.2 Telegram机器人：最实用的远程控制方案

Telegram通道稳定、可靠，且支持文件传输（需额外配置），是我个人最推荐的远程控制方式。

配置步骤详解：

1. 创建Telegram Bot ：

   • 在Telegram中搜索 @BotFather 。
   • 发送 /newbot ，按提示输入机器人名字（如 My CodeCLI Bot ）和用户名（必须以 bot 结尾，如 my_codecli_bot ）。
   • 创建成功后， BotFather 会给你一个 HTTP API Token ，形如 1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ 。妥善保存。

2. 配置 codecli.json ：

   • 打开 config/codecli.json 。
   • 找到 channels.telegram 部分。里面可能已经有一个示例配置，比如叫 agent 。
   • 将 enabled 改为 true 。
   • 将 botToken 的值替换为你刚刚获得的Token。
   • chatId 可以先留空。

3. 获取你的Chat ID（关键步骤） ：

   • 运行命令： python main.py telegram 。CodeCLI会尝试以 agent 这个配置启动Telegram机器人。
   • 在Telegram中找到你的机器人（用户名就是刚才设置的 my_codecli_bot ），向它发送任意一条消息，比如“hello”。
   • CodeCLI运行窗口会在120秒内检测到这条消息，并自动获取到发送者的Chat ID，然后将其保存到配置文件中的 chatId 字段，并打印日志。
   • 之后，CodeCLI将只响应这个Chat ID发来的消息，确保安全。

4. 设置默认通道（可选但推荐） ：

   • 在 config/codecli.json 的根目录找到 default_channel 。
   • 将 chat 字段的值改为你在 telegram 下配置的名称，例如 "agent" 。
   • 这样，以后直接运行 python main.py （不带参数）就会默认启动Telegram通道。

配置完成后，你就可以在任何有网络的地方，通过Telegram向你的机器人发送命令，如 /claude ~/myproject ，来管理你的AI编码会话了。

4.3 微信通道：无额外客户端的便利之选

微信通道基于 itchat 库，通过模拟微信网页版登录来实现。它的好处是无需额外安装App（大家都有微信），但缺点是稳定性受微信官方网页端政策影响，且功能限于文本。

配置与登录：

# 首次运行，会要求扫码登录
python main.py weixin

首次运行时，终端会显示一个二维码（需要确保已安装 Pillow 和 qrcode 库）。用手机微信扫描登录即可。登录凭证会自动保存，后续运行会尝试直接复用，无需再次扫码。

重要提示 ：微信网页版登录存在被微信官方检测和封禁的风险，尤其是在频繁或异常使用的情况下。请勿将此通道用于生产或关键任务环境，仅作为个人便利工具。同时，该通道不支持图片、文件、语音消息。

4.4 HTTP桥接：赋予程序控制能力

HTTP通道将CodeCLI的能力暴露为RESTful API，这是实现自动化、与其它系统（如自建Dashboard、其他Bot框架）集成的关键。

配置与使用：

1. 启用并配置 ：在 config/codecli.json 中，找到 channels.http 部分，将一个配置（如 api ）的 enabled 设为 true ，并 务必 设置一个强壮的 authToken （不要用默认的 CHANGE_ME ）。

2. 启动HTTP服务 ：

   python main.py http:api
   # 或，如果你在default_channel中设置了http为api，可以直接运行
   python main.py http
   

   服务默认监听 127.0.0.1:8787 。

3. API调用示例 ：

   • 发送消息 ：

     curl -X POST "http://127.0.0.1:8787/message" \
       -H "Content-Type: application/json" \
       -H "X-CodeCLI-Token: YOUR_STRONG_AUTH_TOKEN" \
       -d '{"sender": "automation_script_1", "text": "/status"}'
     

     • sender 字段用于区分不同客户端，同一个 sender 的消息和事件是关联的。
     • 返回 {"ok": true, "accepted": true} 表示消息已进入处理队列。
   • 轮询事件（获取回复） ：

     curl "http://127.0.0.1:8787/events?sender=automation_script_1" \
       -H "X-CodeCLI-Token: YOUR_STRONG_AUTH_TOKEN"
     

     • 这是一个 阻塞或长轮询 接口（取决于配置）。它会返回该 sender 名下所有未读的回复事件（如命令执行结果、流式输出片段）。
     • 重要机制 ： /events 端点会“消耗”事件队列。一旦你通过该请求获取了事件，这些事件就会从该 sender 的队列中移除，防止重复接收。

这种请求-轮询模式非常适合由外部系统（如cron job、CI/CD流水线、另一个AI Agent）来驱动CodeCLI执行任务。

4.5 LangChain工具集成：让大模型学会使用你的工具

这是CodeCLI最“元”的用法：你让一个AI大模型（通过LangChain）来学习如何使用CodeCLI，进而操作你本地的各种AI编码工具。这构建了一个“AI指挥AI”的自动化链条。

集成步骤：

1. 安装LangChain ：CodeCLI的核心依赖不包含LangChain，需要单独安装。

   pip install langchain-core pydantic
   

2. 创建LangChain Tool ：

   from cli_orchestrator import create_langchain_tool
   
   # 创建一个工具实例
   codecli_tool = create_langchain_tool(
       response_format="content"  # 返回纯文本内容
   )
   
   # 现在，你可以把这个 tool 塞进 LangChain 的 Agent 或 LangGraph 的 ToolNode 里
   # 例如，在一个简单的链中调用：
   result = codecli_tool.invoke({
       "message": "/claude /home/user/my_python_project"
   })
   print(result["reply_text"])  # 获取CodeCLI返回的文本回复
   print(result["active_session"]) # 获取当前活跃的会话ID
   

3. 结构化响应 ：当 response_format 设置为 "content_and_artifact" 时，返回的将是一个高度结构化的字典，包含：

   • reply_text : 人类可读的回复。
   • status_hint : 会话状态提示（如 "need_confirmation" ）。
   • next_suggested_commands : AI根据当前状态建议的下一步命令（如 ["/y"] ）。
   • active_session : 当前会话ID。
   • available_sessions : 所有会话列表。
   • working_directory : 当前工作目录。

   这个结构化的输出，使得上层的AI Agent能够“理解”当前局面，并智能地决定下一步做什么，比如发现状态是 need_confirmation 时，自动发送 /y 命令。

应用场景想象 ：你可以构建一个LangGraph，让一个“总指挥”Claude调用CodeCLI工具，去启动一个“专家”Cursor Agent处理某个复杂模块的代码，然后获取结果，再交给另一个OpenCode会话进行代码风格检查。整个过程完全自动化。

5. 高级特性与运维技巧

5.1 会话所有权与移交 ( /handoff , /claim )

在多用户或复杂自动化场景下，会话的“所有权”很重要。默认情况下，启动会话的通道拥有该会话的所有权。只有所有者才能接收该会话的异步通知（如状态变更）和某些管理命令。

• /handoff <id> <channel_key> ：将会话的所有权移交给另一个通道。 channel_key 是通道的内部标识符。
• /claim <id> ：如果某个会话没有所有者（例如原通道断开），其他通道可以声明对其的所有权。

这个机制在以下场景有用：你通过HTTP API启动了一个长时间运行的任务（如完整测试），之后你想通过Telegram来监控其进度和结果。你可以先通过HTTP执行 /handoff <session_id> telegram ，将会话“推送”给Telegram通道，之后该会话的输出和状态更新就会自动发送到你的Telegram聊天中。

5.2 消息验证门禁

对于暴露在公网（或不可信内网）的HTTP通道，或者你担心Telegram Bot Token泄露，CodeCLI提供了一个可选的密码验证层。

在 config/codecli.json 的 security.verification 部分进行配置：

"verification": {
    "enabled": true,
    "password": "your_secret_passphrase_here",
    "ttl_seconds": 3600,
    "grace_period_seconds": 300
}

• 启用后，任何通过远程通道（Telegram, Weixin, HTTP）发送的消息，都必须以密码开头，格式为 /verify your_secret_passphrase_here 。
• 验证成功后，在 ttl_seconds （例如3600秒，1小时）内，该发送者（由 sender 标识）发送消息无需再次验证。
• grace_period_seconds （例如300秒，5分钟）允许在CodeCLI启动后的一小段时间内无需验证，方便你进行初始配置和测试。
• 注意 ： tool 通道（LangChain集成）和本地 cli 通道会绕过此验证门禁。

5.3 后台服务部署 ( start.sh )

对于需要7x24小时运行的场景（如托管在云服务器上的Telegram Bot），CodeCLI提供了 start.sh 脚本。

# 使用默认通道（在config中设置）作为后台服务启动
./start.sh

# 指定使用Telegram通道作为后台服务启动
./start.sh telegram

# 指定使用Weixin通道作为后台服务启动
./start.sh weixin

这个脚本做了几件事：

1. 检查并杀死同一目录下可能遗留的旧CodeCLI进程。
2. 使用 nohup 在后台启动新的CodeCLI进程，并将标准输出和错误重定向到 logs/codecli.out 文件。
3. 启动后，它会用 tail -f 显示最新的日志，方便你确认启动是否成功。按下 Ctrl+C 只会退出 tail 命令，CodeCLI主进程继续在后台运行。
4. 你可以随时通过 tail -f logs/codecli.out 来查看实时日志。

运维提示 ：在生产环境使用前，务必仔细阅读 start.sh 脚本内容。你可能需要根据你的系统环境（如使用 systemd 或 supervisor ）进行调整，以实现更完善的服务管理、日志轮转和故障自重启。

5.4 配置文件的组织与管理

config/codecli.json 是CodeCLI的心脏。遵循以下最佳实践可以避免很多麻烦：

• 永远不要提交 ：将 config/codecli.json 添加到你的 .gitignore 文件中。它包含令牌和密码。
• 使用模板 ：始终通过复制 config/codecli.example.json 来创建新的配置文件。
• 分层配置 ：配置文件支持为不同通道（telegram, weixin, http）创建多个命名配置（如 agent , api , personal ）。这允许你在一台机器上运行多个不同用途的CodeCLI实例（虽然不常见，但有可能）。
• 路径别名 ：充分利用 worked_path 。把你常用的项目绝对路径定义在这里，可以极大简化命令输入。

  "worked_path": {
      "p1": "/home/ax/workspace/company/backend",
      "p2": "/home/ax/workspace/personal/ai-experiments",
      "docs": "/home/ax/Documents"
  }
  

  之后就可以用 /claude p1 来代替长长的路径了。

6. 常见问题与故障排查实录

在实际使用和部署CodeCLI的过程中，我踩过不少坑。这里把最常见的问题和解决方法整理出来，希望能帮你节省时间。

6.1 会话启动失败：“Command not found”

问题描述 ：执行 /claude 或 /cursor 时，CodeCLI返回错误，提示找不到可执行文件。

原因与排查 ：

1. AI CLI工具未安装 ：这是最常见的原因。请确保你已在系统上正确安装了对应的工具（如 pip install claude-code ，或按照Cursor官方指南安装）。
2. 不在PATH中 ：虽然安装了，但安装路径没有添加到系统的 PATH 环境变量中。
   • 检查 ：在终端直接输入 claude 或 agent ，看是否能运行。
   • 解决 ：
     • 找到可执行文件的绝对路径（例如 which claude 或 find ~ -name "claude" ）。
     • 在 config/codecli.json 的 cli_path 部分，显式指定路径：

       "cli_path": {
           "claude": "/home/yourname/.local/bin/claude",
           "cursor": "/usr/local/bin/agent"
       }
       

3. 虚拟环境问题 ：如果你在虚拟环境（venv, conda）中运行CodeCLI，而AI工具安装在全局环境，或者另一个虚拟环境中，也会导致找不到命令。确保CodeCLI和它要调用的AI工具在同一个环境，或者AI工具在全局可访问的位置。

6.2 远程通道无响应或连接失败

问题描述 ：启动了Telegram或HTTP通道，但发送消息后收不到回复。

排查步骤 ：

1. 检查日志 ：首先查看CodeCLI的运行日志。对于后台运行的服务，查看 logs/codecli.out 。
2. 验证配置 ：
   • Telegram ：确认 botToken 完全正确，没有多余空格。确认 chatId 已正确获取并填写（如果留空，则需按前述步骤重新获取）。
   • HTTP ：确认 authToken 不是默认的 CHANGE_ME 。确认监听的 host 和 port 没有被防火墙阻挡。如果是云服务器，确保安全组/防火墙规则允许该端口入站。
3. 网络与代理 ：如果CodeCLI运行在需要代理才能访问外网的服务器上，Telegram Bot的API调用可能会失败。你需要为Python进程设置全局代理，或者在代码级别为 python-telegram-bot 库配置代理。
4. 查看进程状态 ：使用 ps aux | grep python 和 ps aux | grep main.py 确保CodeCLI进程确实在运行，并且没有因为异常而退出。

6.3 会话状态卡在“running”但无输出

问题描述 ：发送一个任务后， /status 显示会话状态为 running ，但 /output 始终是空的，或者很久都没有完成。

可能原因与解决 ：

1. 等待交互 ：这是最可能的情况。AI工具可能正在等待一个确认（如 [y/n] ），或者卡在某个需要按回车继续的提示符。使用 /screen <id> 命令查看会话的“屏幕”快照，通常能看到具体的提示信息。然后使用 /y , /n , /enter 等命令进行响应。
2. 长时间任务 ：任务本身确实需要很长时间（例如，让AI生成一个非常复杂的系统，或运行一个庞大的测试套件）。此时可以切换到 stream 模式（ /mode <id> stream ）来查看实时进度。
3. 进程僵死 ：极少数情况下，子进程可能僵死了。尝试使用 /kill <id> 强制结束该会话，然后重新启动。

6.4 微信通道扫码登录失败或掉线

问题描述 ：微信通道无法显示二维码，扫码后登录失败，或者使用一段时间后自动掉线。

原因与解决 ：

1. 依赖缺失 ：确保安装了 Pillow 和 qrcode 库（ pip install Pillow qrcode ），用于在终端显示二维码。
2. 微信风控 ：微信对网页版登录有严格的风控。频繁登录、异地登录、或在服务器上登录都可能触发验证甚至封禁。
   • 尝试 ：在个人电脑上首次登录并保存凭证，然后将整个 CodeCLI 目录（包含保存的登录状态文件）复制到服务器上运行。有时这样能绕过一些初始风控。
   • 降低预期 ：将微信通道视为一个“可能不稳定”的便利选项，不要用于关键任务。Telegram和HTTP通道是更可靠的选择。
3. 掉线重连 ： itchat 库有内置的重连机制，但并非100%可靠。如果发现长时间无响应，可能需要手动重启CodeCLI的微信通道。

6.5 性能与资源占用

问题描述 ：同时运行多个AI会话时，系统负载很高。

分析与建议 ：

• 资源消耗主体是AI工具 ：CodeCLI本身只是一个轻量的编排器和通信中转站，资源消耗极低。主要的CPU和内存占用来自于你启动的Claude Code、Cursor Agent等AI进程。这些工具本身通常就是资源大户。
• 管理并发数 ：根据你的机器性能（特别是CPU核心数和内存大小），合理控制并发会话的数量。不要一次性启动太多高负载的AI任务。
• 及时清理 ：对于已经完成（ completed 状态）或不再需要的会话，使用 /stop 或 /kill 命令及时结束它们，以释放系统资源。养成使用 /stopall 结束一天工作的习惯。

6.6 安全最佳实践

1. 令牌与密码是最高机密 ： config/codecli.json 中的 botToken (Telegram), authToken (HTTP) 以及可选的 verification.password ，等同于你系统的钥匙。 绝对不要 将其提交到版本控制系统或分享给他人。
2. 最小化网络暴露 ：
   • HTTP通道如果不需要从外网访问，请将 host 设置为 127.0.0.1 （仅本地访问），而不是 0.0.0.0 。
   • 如果必须对外暴露HTTP API，务必使用强密码（ authToken ），并考虑在前端配置Nginx/Apache反向代理，添加HTTPS和额外的身份验证层。
   • Telegram Bot本身是相对安全的，因为只有知道Bot用户名并能在Telegram上找到它的人才能发送消息。但仍建议启用消息验证门禁作为第二道防线。
3. 权限隔离 ：尽量不要以 root 用户身份运行CodeCLI。创建一个具有必要权限的普通用户来运行它，以降低潜在风险。
4. 定期更新 ：关注CodeCLI项目仓库的更新，及时获取安全修复和功能改进。

CodeCLI的设计初衷是提升效率，而不是增加复杂性。刚开始使用时，建议从本地CLI模式开始，熟悉基本命令和概念。然后逐步尝试一个远程通道（推荐Telegram），最后再探索HTTP API和LangChain集成等高级玩法。这个工具就像一把瑞士军刀，功能很多，但你可以根据当前的需要，只使用其中最趁手的那一两个。