1. Leo 项目概述：一个为 Claude Code 而生的进程管家

如果你和我一样，日常重度依赖 Claude Code 来辅助开发、调试甚至处理一些自动化任务，那你肯定遇到过这个痛点：一个运行中的 Claude Code 会话，因为网络波动、终端关闭或者只是你忘了保持活跃，突然就断开了。所有上下文、正在进行的对话和代码状态瞬间消失，那种感觉就像写到一半的文档没保存一样令人抓狂。更别提那些你想让它定时运行的任务，比如每天早晨自动生成一份项目简报，或者监控代码库的特定变更——手动操作不仅繁琐，而且难以持久化。

这就是我最初接触并决定深入使用 Leo 的原因。它不是一个全新的 AI 工具，而是一个专门为 Claude Code 设计的“进程管家”和任务调度器。简单来说，Leo 的核心使命就是让 Claude Code 会话变得像系统服务一样可靠，让定时任务变得像 cron job 一样简单，并且能让你通过多种方式（命令行、网页、甚至 Telegram 机器人）来管理和交互。它的名字来源于作者的黑猫 Leo，寓意着像猫一样优雅而独立地守护着你的 AI 工作流。

这个用 Go 语言编写、完全自托管的小工具，解决的是 AI 辅助编程工作流中“持久化”和“自动化”这两个核心难题。无论你是想 7x24 小时保持一个专用于代码审查的 Claude 会话在线，还是希望每天定点让 Claude 分析日志并发送报告，抑或是需要快速从模板克隆一个临时的、隔离的编码代理（Agent）来处理一个拉取请求（PR），Leo 都能提供一个清晰、统一的框架来管理这一切。接下来，我将结合自己数周的实战部署和调优经验，为你彻底拆解 Leo 的设计思路、核心功能、避坑指南以及那些官方文档可能没细说的实操技巧。

2. 核心架构与设计哲学解析

在深入命令行操作之前，理解 Leo 的底层设计哲学至关重要。这能帮助你在配置和遇到问题时，更快地定位原因，而不是盲目地试错。Leo 的架构可以概括为“三个核心原语，一个守护进程”。

2.1 三大核心原语：进程、模板与任务

Leo 将你对 Claude Code 的所有操作抽象为三种资源，这种清晰的划分是其易用性的基石。

2.1.1 进程：常驻的 AI 伙伴

这是 Leo 最基础的功能。一个“进程”对应一个 长期运行、受监管的 Claude Code 会话 。你可以把它想象成一个后台服务（daemon）。Leo 会为这个会话创建一个独立的 tmux 会话（运行在独立的 socket 上，不干扰你的个人终端），并持续监控其状态。如果会话意外退出，Leo 会按照指数退避策略自动重启它，确保服务的高可用性。

每个进程都拥有独立的配置空间：

• 工作区 ：进程运行的文件系统根目录，不同进程的工作区完全隔离，避免文件冲突。
• 模型 ：可以为不同进程指定不同的 Claude 模型（如 claude-3-5-sonnet ， claude-3-opus ），让代码助手和文档分析助手各司其职。
• 通道 ：定义该进程可以通过哪些“渠道”接收指令和发送输出，例如 Telegram 机器人、Slack 应用或 Webhook。
• 权限模式 ：控制该进程中的 Claude Code 能执行哪些系统命令（如读写文件、运行脚本）。

2.1.2 模板与代理：即用即抛的编码沙盒

这是 Leo 非常强大的一个特性。“模板”定义了创建一次性“代理”的蓝图。当你需要临时处理一个特定任务时（比如审查某个 GitHub 仓库的某个分支），你可以基于模板快速“孵化”出一个代理。

这个代理会：

1. 克隆你指定的代码仓库到一个临时工作区。
2. 在一个全新的、独立的 tmux 会话中启动一个 Claude Code 实例。
3. 任务完成后，你可以选择停止并清理这个代理，释放资源。

这完美解决了“我想让 Claude 深度介入这个临时项目，但又不想污染我的主工作环境”的需求。模板保证了孵化过程的一致性，而代理则提供了极致的隔离性和灵活性。

2.1.3 任务：AI 驱动的定时作业

如果你熟悉 Linux 的 cron ，理解这个就很容易了。Leo 的“任务”就是 基于时间表运行的、非交互式的 Claude Code 执行 。你定义一个任务，包括：

• 调度表达式 ：标准的 cron 语法，如 0 7 * * * 表示每天早晨 7 点。
• 提示词文件 ：一个 Markdown 文件，里面包含了要发给 Claude 的完整指令和上下文。
• 触发动作 ：任务成功或失败后，可以通过配置的“通道”发送通知。

例如，你可以设置一个每天凌晨运行的“代码质量报告”任务，让 Claude 分析最新提交，并总结潜在风险，然后将报告通过 Telegram 发送给你。

2.2 统一守护进程与通信层

所有上述功能都由一个统一的 leo 守护进程管理。这个守护进程不仅负责进程监管和任务调度，还内置了三个关键的对外接口：

1. Web 控制面板与 API ：默认在 127.0.0.1:8370 提供一个本地网页界面，可以直观地查看所有进程、任务、代理的状态，进行启停操作，甚至预览 cron 表达式。同时，一个基于令牌认证的 HTTP API 暴露了所有管理功能，为自动化集成提供了可能。
2. 内置 MCP 服务器 ：这是 Leo 的一个巧妙设计。MCP 是 Claude Code 的一种扩展协议。Leo 内置的 MCP 服务器意味着， 任何连接到 Leo 管理的 Claude Code 会话的通道插件（如 Telegram），都能自动获得一组统一的斜杠命令 ，例如 /clear （清屏）、 /tasks （列出任务）、 /agent spawn （孵化代理）等。这极大地统一了不同渠道的操作体验。
3. 远程 CLI 桥接 ： leo 命令行工具本身可以配置为远程模式。当你配置了远程主机信息后，本地的 leo agent list 等命令会通过 SSH 隧道在远程 Leo 主机上执行，结果返回本地。这让你可以像管理本地服务一样管理服务器上的 Leo，无需手动 SSH 过去再执行命令。

设计哲学体会 ：Leo 没有尝试重新发明轮子，而是优雅地整合了现有成熟工具。它用 tmux 解决会话持久化和隔离问题，用 cron 语法解决调度问题，用 Go 编写守护进程保证性能和可靠性，最后用 Claude Code 插件体系解决交互问题。这种“胶水”式的设计，使得它既轻量又强大，学习曲线相对平缓。

3. 从零开始：环境准备与首次部署

理论讲完了，我们动手把它跑起来。我会以 macOS（使用 Homebrew）和 Linux 系统为例，涵盖从安装到跑通第一个进程的全过程。

3.1 前置条件检查与安装

Leo 运行依赖两个核心组件： Claude Code CLI 和 tmux 。

3.1.1 安装并认证 Claude Code CLI

这是 Leo 能够驱动 Claude 的基础。如果你还没安装，需要先完成这一步。

# 安装 Claude Code CLI (假设使用 npm)
npm install -g @anthropic-ai/claude-code

# 运行认证，这会在浏览器中打开 Anthropic 的认证页面
claude auth login

认证成功后，你的访问令牌会存储在本地。Leo 在启动 Claude Code 进程时会自动使用这个已认证的上下文。

3.1.2 确保 tmux 版本达标

Leo 使用 tmux 的 display-popup 等现代特性来管理会话，因此需要 tmux 3.2 或更高版本 。

# 检查当前 tmux 版本
tmux -V

# 如果版本过低，需要升级
# macOS (Homebrew)
brew upgrade tmux

# Ubuntu/Debian
sudo apt update && sudo apt install tmux

# 或者从源码编译更新版本

3.1.3 安装 Leo 本体

最推荐的方式是使用 Homebrew，管理起来最方便。

# 添加 blackpaw-studio 的 tap 并安装 leo
brew tap blackpaw-studio/tap
brew install leo

# 验证安装
leo --version

如果不用 Homebrew，也可以用一键安装脚本或 Go 安装。

# 一键安装脚本
curl -fsSL leo.blackpaw.studio/install | sh

# Go 安装 (需要 Go 1.21+)
go install github.com/blackpaw-studio/leo/cmd/leo@latest

安装完成后，运行 leo 命令应该能看到帮助信息。

3.2 交互式初始化配置

Leo 提供了一个非常友好的 setup 向导，强烈建议第一次使用时通过它来初始化。

leo setup

这个交互式命令会引导你完成以下几步：

1. 选择配置目录 ：默认是 ~/.leo 。这里会存放所有的配置文件、工作区、状态和日志。
2. 创建第一个进程 ：它会问你第一个常驻进程叫什么名字（例如 assistant ），使用什么模型，工作区路径在哪里。你可以先使用默认值。
3. 生成基础配置 ：向导会根据你的回答，在 ~/.leo/config.yaml 生成一份初始配置文件。

这个过程完成后，你的 Leo 骨架就已经搭好了。你可以立刻查看生成的状态：

leo status

这个命令会显示守护进程状态（未运行）、已定义的进程、任务等概要信息。

3.3 启动守护进程与验证

配置好了，现在让我们把 Leo 服务跑起来。

3.3.1 前台启动（调试推荐）

首次启动，建议在前台运行，方便观察日志和排查问题。

leo service start

你会看到 Leo 守护进程启动，加载配置，然后为你创建的进程（例如 assistant ）启动一个 tmux 会话。如果一切正常，最后几行日志会显示 Web 面板的访问地址（通常是 http://127.0.0.1:8370 ）和 API 令牌信息。

3.3.2 访问 Web 控制面板

打开浏览器，访问 http://127.0.0.1:8370 。你应该能看到 Leo 的仪表盘。这里展示了所有进程的状态（应该是 running ）、任务列表等。这是验证服务是否正常运行的直观方式。

3.3.3 以系统服务方式后台运行

调试无误后，我们可以将其安装为系统服务，实现开机自启和后台稳定运行。

# 安装并启动系统服务 (macOS 的 launchd 或 Linux 的 systemd)
leo service start -d

# 查看服务状态
leo service status

# 查看服务日志
leo service logs

使用 -d 参数后，Leo 会检测你的系统（launchd 或 systemd），并生成相应的服务配置文件，然后启动它。之后你就可以通过 leo service 系列命令来管理这个后台服务了。

首次部署避坑指南 ：

• 权限问题 ：确保 ~/.leo 目录以及你的工作区目录对当前用户有读写权限。Leo 守护进程会以当前用户身份运行。
• Claude Code 认证失效 ：如果 leo service start 失败并提示 Claude 认证问题，请再次运行 claude auth login 确保令牌有效。有时令牌过期需要重新认证。
• tmux 版本兼容性 ：如果遇到与会话创建相关的奇怪错误，首要怀疑对象就是 tmux 版本。务必使用 tmux -V 确认版本 >= 3.2。
• 端口冲突 ：默认的 8370 端口被占用？可以在后续的配置中通过 web.port 修改。

4. 核心功能实战：配置、管理与进阶用法

现在 Leo 已经跑起来了，我们来深入它的核心功能，通过修改配置文件和使用 CLI 来实际创建和管理资源。

4.1 深入配置文件： config.yaml 详解

Leo 的所有行为都由 ~/.leo/config.yaml 控制。理解这个文件的结构是掌握 Leo 的关键。让我们拆解一个功能丰富的配置示例。

# ~/.leo/config.yaml
web:
  enabled: true
  port: 8370
  # 如果你想让同一网络的其他设备访问，需设置 bind 和 allowed_hosts
  # bind: 0.0.0.0
  # allowed_hosts: ["my-computer.local"]

processes:
  # 一个常驻的代码助手进程
  code-assistant:
    workspace: ~/projects/leo-workspace
    model: claude-3-5-sonnet
    # 权限模式：'auto' 会根据提示词自动请求权限，'restricted' 则严格限制
    permission_mode: auto
    # 启用远程控制，这样在通道里才能用 /stop, /clear 等命令
    remote_control: true
    # 关联的通道：需要先安装对应的 Claude Code 插件
    channels: ["plugin:telegram@claude-plugins-official"]
    enabled: true

  # 另一个专门用于文档分析的进程，使用更强的模型
  doc-analyzer:
    workspace: ~/docs-analysis
    model: claude-3-opus
    permission_mode: restricted # 文档分析，不需要运行命令
    enabled: true

templates:
  # 定义一个名为“code-review”的代理模板
  code-review:
    model: claude-3-5-sonnet
    permission_mode: auto
    # 所有由此模板孵化的代理，其工作区都将位于此目录下
    workspace: ~/agents/code-review
    remote_control: true
    # 可以设置环境变量传递给 Claude Code
    env:
      GIT_AUTHOR_NAME: "Leo Agent"
      GIT_AUTHOR_EMAIL: "agent@example.com"

tasks:
  # 一个定时任务：每天上午9点生成日报
  daily-standup:
    schedule: "0 9 * * *" # 分钟 小时 日 月 星期
    timezone: Asia/Shanghai
    # 提示词文件路径，相对于 Leo 的配置目录 (~/.leo)
    prompt_file: prompts/daily-standup.md
    model: claude-3-5-sonnet
    # 任务失败时，通过 Telegram 通知我
    notify_on_fail: true
    enabled: true

  # 每周一早晨清理临时工作区
  weekly-cleanup:
    schedule: "0 8 * * 1"
    prompt_file: prompts/cleanup.md
    model: claude-3-5-haiku # 简单任务，用快而省的模型
    enabled: true

配置文件管理技巧 ：

• 修改配置后，需要重启 Leo 服务才能生效： leo service restart 。
• 可以使用 leo config show 查看当前生效的完整配置（包括默认值）。
• 使用 leo config edit 会调用 $EDITOR 环境变量指定的编辑器（如 vim, code）直接打开配置文件，修改保存后 Leo 会自动重新加载（如果支持热重载）或提示你重启。

4.2 进程管理实战

进程是 Leo 的基石。除了通过配置文件定义，也可以用 CLI 动态管理。

4.2.1 查看与操作进程

# 列出所有进程及其状态
leo process list

# 启用或禁用一个进程（禁用后，守护进程不会启动它）
leo process disable code-assistant
leo process enable code-assistant

# 查看特定进程的详细日志
leo process logs code-assistant

# 动态添加一个临时进程（不会写入 config.yaml）
# 注意：这种添加是临时的，服务重启后会消失。适合测试。
leo process add temp-session --model haiku --workspace /tmp/test

4.2.2 直接与会话交互

虽然进程在后台通过 tmux 运行，但你可以直接“接入”这个会话来与 Claude 实时交互。

# 接入名为 ‘code-assistant’ 的进程会话
leo attach code-assistant

这个命令会把你当前的终端“附着”到该进程背后的 tmux 会话中，你就像直接在里面运行 claude 命令一样，可以进行多轮对话。按 Ctrl+b 然后按 d 可以脱离该会话，让它在后台继续运行。

进程管理心得 ：

• 工作区隔离 ：为不同用途的进程设置不同的 workspace 路径，避免文件交叉污染。例如，代码助手和文档分析助手的工作区应该分开。
• 模型选择策略 ：对响应速度要求高的常驻对话（如编码）使用 sonnet ，对复杂分析任务使用 opus ，对简单的、周期性的任务使用 haiku 以节约成本。
• 监控日志 ：当进程行为异常或 Claude 没有响应时，第一件事就是 leo process logs <name> 。日志里通常包含了 Claude Code 子进程的标准输出和错误，是排查问题的金矿。

4.3 代理模板：按需孵化编码沙盒

这是我认为 Leo 最酷的功能之一。假设你接到一个任务，要审查一个 GitHub 仓库的某个功能分支。

4.3.1 定义模板

首先，确保你的配置文件中有一个像前面示例那样的 code-review 模板。

4.3.2 孵化代理

现在，基于这个模板孵化一个代理来处理特定的仓库和分支。

# 孵化一个代理，克隆主分支，并命名为 ‘pr-123-review’
leo agent spawn code-review --repo github-username/repo-name --name pr-123-review

# 孵化一个代理，克隆特定的分支或标签，并基于该分支创建一个新的工作树
leo agent spawn code-review --repo github-username/repo-name --worktree feat/new-awesome-feature --name feature-review

执行后，Leo 会：

1. 在模板指定的 workspace 目录下，为这个代理创建一个独立的子目录（通常以名字或仓库名命名）。
2. 克隆指定的仓库（或切换到指定分支的工作树）。
3. 启动一个全新的 Claude Code 会话，其上下文完全隔离于此工作目录。

4.3.3 接入与停止代理

# 列出所有活跃的代理
leo agent list

# 接入名为 ‘pr-123-review’ 的代理进行交互
leo attach pr-123-review
# 或者使用代理子命令
leo agent attach pr-123-review

# 任务完成后，停止并清理该代理
leo agent stop pr-123-review --prune
# 如果使用了 --worktree，还可以删除对应的分支
leo agent stop feature-review --prune --delete-branch

--prune 参数会停止 tmux 会话并 删除代理的工作目录 ，真正做到“即用即抛”，不留垃圾。

4.4 定时任务：让 AI 自动工作

定时任务将 AI 能力变成了真正的自动化工具。

4.4.1 创建提示词文件

首先，在 ~/.leo/prompts/ 目录下创建你的任务提示词文件，例如 daily-standup.md 。

# 每日项目简报生成

你是一个资深项目分析师。请分析位于 `/path/to/project` 的 Git 仓库。

请执行以下操作：
1.  获取最近24小时内的所有提交。
2.  总结每个提交的主要变更。
3.  识别出可能引入风险的变更（如大型重构、关键依赖更新）。
4.  检查是否有失败的 CI/CD 流水线。
5.  将以上分析整理成一份简洁的 Markdown 报告。

报告需要包括：
- 概述
- 提交摘要
- 风险提示
- 后续建议

将最终报告输出到 `/path/to/project/daily-standup-$(date +%Y%m%d).md` 文件中。

4.4.2 定义并测试任务

在 config.yaml 的 tasks: 部分添加该任务的定义（如前文示例）。然后，不必等到预定时间，可以手动触发一次来测试。

# 手动运行一次 ‘daily-standup’ 任务
leo run daily-standup

# 查看该任务的执行历史记录
leo task history daily-standup

# 查看最近一次执行的详细日志
leo task logs daily-standup

手动运行可以帮助你验证提示词是否有效，Claude 是否有足够的权限执行 Git 命令和写文件等操作。

4.4.3 任务调度与通知

Leo 使用系统的 cron 守护进程来触发定时任务，因此时间调度非常精确。 notify_on_fail: true 配置非常有用，一旦任务因任何原因（网络错误、权限不足、提示词歧义导致 Claude 执行失败）执行失败，Leo 会尝试通过配置的 channels 发送通知，让你及时介入处理。

5. 高级集成与运维技巧

当基础功能稳定运行后，你可以探索更强大的集成和运维方案。

5.1 通道插件集成：通过聊天工具控制

Leo 本身不处理消息通信，而是与 Claude Code 的通道插件无缝集成。以 Telegram 为例：

1. 安装 Telegram 插件 ：

   claude plugin install telegram@claude-plugins-official
   # 按照插件指引，配置 Bot Token 和 Chat ID
   

2. 在 Leo 进程中引用插件 ：在进程的 channels 配置中加入 "plugin:telegram@claude-plugins-official" 。

3. 注册斜杠命令 （可选但推荐）：

   leo channels register-commands telegram
   

   这个命令会向 Telegram Bot 注册 Leo 内置的 MCP 命令（如 /clear , /tasks , /agent spawn 等），让你在 Telegram 聊天中直接使用这些命令来控制关联的 Leo 进程。

完成以上步骤后，你就可以在 Telegram 中和你的“代码助手”进程对话了，并且可以使用统一的斜杠命令来管理 Leo 本身。

5.2 远程管理：将 Leo 部署在服务器

你可以将 Leo 部署在一台始终在线的云服务器上，然后通过本地 CLI 进行远程管理。

1. 在服务器上安装并配置 Leo ：步骤同上，确保 web.bind 可能设置为 0.0.0.0 并配置好 allowed_hosts 和防火墙规则（ 注意安全 ，最好结合 VPN 或 SSH 隧道）。

2. 在本地 Leo 配置中添加远程主机 ：

   # ~/.leo/config.yaml (本地机器)
   client:
     default_host: my-server
     hosts:
       my-server:
         ssh: username@your-server-ip
   

3. 通过本地 CLI 管理远程 Leo ：

   # 以下命令都会通过 SSH 在远程服务器上执行
   leo -H my-server status
   leo -H my-server agent spawn coding --repo my-org/my-repo
   leo -H my-server attach
   

   这样，你就可以利用服务器更强的算力和永不停机的特性，运行一些耗时的 AI 任务或作为团队的共享 AI 助手。

5.3 安全配置与 API 使用

Leo 的 Web 和 API 接口设计考虑了基本的安全。

• 主机与来源锁定 ：默认只绑定 127.0.0.1 ，并严格检查 HTTP 请求的 Host 和 Origin 头，防止 DNS 重绑定等攻击。如果需要对外暴露， 务必 设置 web.allowed_hosts 。
• API 令牌认证 ：所有 /api/ 下的接口都需要 Bearer Token。令牌在首次启动时生成于 ~/.leo/state/api.token 。任何自动化脚本调用 API 时都需要携带此令牌。

  # 示例：使用 curl 调用 API 列出任务
  API_TOKEN=$(cat ~/.leo/state/api.token)
  curl -H "Authorization: Bearer $API_TOKEN" http://localhost:8370/api/task/list
  

• 令牌轮换 ：如果令牌泄露，直接删除 ~/.leo/state/api.token 文件并重启 Leo 服务，即可生成新令牌。

5.4 故障排查与日常维护

5.4.1 查看服务状态与日志

这是诊断问题的第一步。

# 查看守护进程和所有资源状态
leo status

# 查看 Leo 守护进程本身的日志
leo service logs

# 查看特定进程的详细日志
leo process logs <process-name>

# 查看特定任务的执行日志
leo task logs <task-name>

5.4.2 验证配置与环境

当出现无法启动或行为异常时，使用验证命令。

# 检查配置文件语法、依赖项和工作区健康状态
leo validate

这个命令会报告常见问题，如 Claude CLI 未认证、tmux 版本过低、工作目录不可写等。

5.4.3 手动检查 tmux 会话

由于 Leo 使用独立的 tmux socket ( -L leo )，你可以直接用 tmux 命令检查底层会话。

# 列出 Leo 管理的所有 tmux 会话
tmux -L leo ls

# 手动接入某个会话（在复杂调试时有用）
tmux -L leo attach -t <session-name>

5.4.4 更新 Leo

保持 Leo 更新可以获得新功能和错误修复。

# 如果通过 Homebrew 安装
brew update
brew upgrade blackpaw-studio/tap/leo
leo service restart

# 如果通过安装脚本安装，Leo 提供了自更新命令
leo update
# 更新后同样需要重启服务
leo service restart

经过一段时间的深度使用，我将 Leo 融入了自己的日常开发流。一个 code-assistant 进程常驻，作为我的第二大脑，随时回答技术问题；几个定时任务负责每日的代码库健康检查和报告生成；而 agent 模板功能，则在我需要深度介入一个开源项目的 Issue 或 PR 时，提供了完美的沙盒环境。它可能不是那种功能繁多的庞然大物，但它在“让 Claude Code 更可靠、更自动化”这件事上，做得极其专注和优雅。如果你也在寻找一种方式来固化你的 AI 编程助手工作流，Leo 绝对值得你花上一个下午的时间来部署和把玩。