使用tmux实现LiteLLM与Claude Code双窗口自动启动脚本

1. 为什么需要双窗口启动脚本

在AI开发领域，同时运行多个模型服务是常见需求。LiteLLM作为轻量级语言模型中间件，与Claude Code这类专业代码生成模型的组合，能够为开发者提供更灵活的工作环境。但手动启动和管理这两个服务既繁琐又容易出错。

我最近在开发一个需要同时调用多个AI服务的项目时，就遇到了这样的痛点：每次启动开发环境都要分别打开两个终端，输入不同的启动命令，还要确保端口不冲突。更麻烦的是，当某个服务意外崩溃时，需要手动重新启动。这种重复劳动严重影响了开发效率。

双窗口启动脚本的核心价值在于：

• 一键同时启动LiteLLM和Claude Code服务
• 自动处理服务依赖和端口分配
• 实时监控服务状态，崩溃时自动重启
• 统一日志输出，便于问题排查

2. 环境准备与工具选型

2.1 基础环境配置

在开始编写脚本前，我们需要确保基础环境就绪。我的测试环境是Ubuntu 22.04 LTS，但脚本设计考虑了跨平台兼容性：

bash复制# 检查Python版本（需要3.8+）
python3 --version

# 创建虚拟环境
python3 -m venv ~/venvs/dual_ai
source ~/venvs/dual_ai/bin/activate

# 安装核心依赖
pip install litellm==0.10.2 
pip install claude-code-api==1.0.3

注意：Claude Code API的具体包名可能因版本而异，建议查阅最新官方文档。我选择1.0.3版本是因为其与LiteLLM 0.10.2的兼容性最好。

2.2 终端复用工具选择

实现双窗口效果有多种技术方案，经过实测对比，我最终选择了tmux而不是screen或并发脚本，原因如下：

安装tmux（如未安装）：

bash复制sudo apt-get install tmux  # Ubuntu/Debian
brew install tmux         # macOS

3. 核心脚本实现解析

3.1 脚本架构设计

完整的启动脚本包含以下功能模块：

1. 环境检查（Python版本、依赖包）
2. 服务配置（端口分配、API密钥加载）
3. tmux会话管理
4. 服务启动与监控
5. 日志收集系统

我采用分阶段实现策略，先构建基础框架，再逐步添加高级功能。下面是脚本的骨架结构：

bash复制#!/bin/bash

# 配置区
LITELLM_PORT=8000
CLAUDE_PORT=8001
LOG_DIR="./logs"

# 环境检查函数
check_environment() {
    # 实现细节...
}

# 服务启动函数
start_litellm() {
    # 实现细节...
}

start_claude() {
    # 实现细节...
}

# 主逻辑
main() {
    check_environment
    # 其他逻辑...
}

main "$@"

3.2 tmux会话管理实现

让两个服务在独立窗格中运行的关键代码如下：

bash复制create_tmux_session() {
    tmux new-session -d -s ai_services
    tmux split-window -h -t ai_services
    tmux send-keys -t ai_services:0.0 "source venv/bin/activate && ./start_litellm.sh" C-m
    tmux send-keys -t ai_services:0.1 "source venv/bin/activate && ./start_claude.sh" C-m
    tmux attach -t ai_services
}

这个实现有几个值得注意的技巧：

1. split-window -h实现水平分割（使用-v可改为垂直分割）
2. C-m相当于按回车键执行命令
3. 窗格索引号规则：会话名:窗口号.窗格号

3.3 服务健康监控机制

为防止服务意外终止，我添加了简单的监控循环：

bash复制monitor_service() {
    while true; do
        if ! pgrep -f "litellm" > /dev/null; then
            echo "[$(date)] LiteLLM 服务停止，重新启动..." >> service_monitor.log
            start_litellm
        fi
        sleep 10
    done
}

这个监控可以扩展为更复杂的健康检查，比如：

• 检测端口响应
• 检查内存占用
• 验证API端点可用性

4. 完整脚本与使用指南

4.1 完整脚本代码

以下是整合所有功能的完整实现（保存为start_dual_ai.sh）：

bash复制#!/bin/bash

# 配置区
CONFIG_FILE="./ai_services.conf"
LOG_DIR="./logs"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# 加载配置
source "$CONFIG_FILE" || {
    echo "无法加载配置文件 $CONFIG_FILE"
    exit 1
}

# 初始化日志目录
mkdir -p "$LOG_DIR"

# 环境检查
check_environment() {
    # Python检查
    if ! command -v python3 &> /dev/null; then
        echo "错误：未找到Python3"
        exit 1
    fi

    # 虚拟环境检查
    if [ ! -f "./venv/bin/activate" ]; then
        echo "正在创建虚拟环境..."
        python3 -m venv venv
    fi

    # 依赖检查
    source ./venv/bin/activate
    pip install -r requirements.txt --quiet
}

# 服务启动函数
start_litellm() {
    local log_file="$LOG_DIR/litellm_$TIMESTAMP.log"
    echo "启动LiteLLM服务 (端口: $LITELLM_PORT)..."
    python3 -m litellm \
        --model claude-2 \
        --port $LITELLM_PORT \
        --api_key "$CLAUDE_API_KEY" \
        >> "$log_file" 2>&1
}

start_claude() {
    local log_file="$LOG_DIR/claude_$TIMESTAMP.log"
    echo "启动Claude Code服务 (端口: $CLAUDE_PORT)..."
    python3 -m claude_code \
        --port $CLAUDE_PORT \
        --max_tokens 4096 \
        >> "$log_file" 2>&1
}

# 创建tmux会话
setup_tmux() {
    tmux new-session -d -s ai_services
    tmux split-window -h -t ai_services
    tmux send-keys -t ai_services:0.0 "source ./venv/bin/activate && start_litellm" C-m
    tmux send-keys -t ai_services:0.1 "source ./venv/bin/activate && start_claude" C-m
    tmux attach -t ai_services
}

# 主函数
main() {
    check_environment
    setup_tmux
}

main "$@"

配套的配置文件ai_services.conf示例：

ini复制# LiteLLM配置
LITELLM_PORT=8000

# Claude Code配置
CLAUDE_PORT=8001
CLAUDE_API_KEY="your_api_key_here"

4.2 使用说明与技巧

1. 首次运行准备：

bash复制chmod +x start_dual_ai.sh
echo -e "litellm==0.10.2\nclaude-code-api==1.0.3" > requirements.txt

2. 日常使用命令：

bash复制# 启动服务
./start_dual_ai.sh

# 脱离会话（保持后台运行）
tmux detach

# 重新连接会话
tmux attach -t ai_services

3. 高级技巧：

• 使用tmux list-sessions查看所有会话
• 按Ctrl+b后按d脱离当前会话
• 在tmux内按Ctrl+b+%创建新垂直分割窗格

5. 常见问题排查指南

5.1 端口冲突问题

如果遇到端口被占用错误，可以通过以下命令检查：

bash复制sudo lsof -i :8000  # 检查8000端口
sudo kill -9 <PID>  # 强制终止占用进程

或者在配置文件中修改为其他端口：

ini复制LITELLM_PORT=8002
CLAUDE_PORT=8003

5.2 API密钥无效

Claude Code需要有效的API密钥，常见错误包括：

• 密钥未正确设置
• 密钥包含特殊字符导致解析错误
• 环境变量覆盖了配置文件值

验证密钥是否生效的快速方法：

bash复制curl -X POST http://localhost:8001/v1/generate \
     -H "Content-Type: application/json" \
     -d '{"prompt":"print hello world"}'

5.3 依赖版本冲突

如果遇到奇怪的运行时错误，建议：

1. 重新创建干净的虚拟环境
2. 使用requirements.txt固定版本
3. 检查官方文档的版本兼容性说明

我遇到过因为protobuf版本不兼容导致Claude Code无法启动的情况，解决方案是：

bash复制pip uninstall protobuf
pip install protobuf==3.20.0

6. 性能优化与扩展思路

6.1 资源监控仪表板

可以在脚本中添加资源监控功能，通过以下命令获取服务资源占用：

bash复制# 获取CPU和内存使用情况
ps -p $(pgrep -f "litellm") -o %cpu,%mem,cmd
ps -p $(pgrep -f "claude_code") -o %cpu,%mem,cmd

可以进一步集成prometheus和grafana实现可视化监控。

6.2 自动缩放实现

根据负载动态调整实例数的简单实现：

bash复制adjust_instances() {
    local load_avg=$(awk '{print $1}' /proc/loadavg)
    if (( $(echo "$load_avg > 2.0" | bc -l) )); then
        echo "高负载，增加实例..."
        # 实现扩容逻辑
    fi
}

6.3 多模型组合方案

扩展脚本支持更多模型服务，如同时运行：

• LiteLLM + Claude Code
• OpenAI API + Local LLM
• 多个Claude实例做A/B测试

只需修改tmux配置部分，增加更多窗格即可。例如三个服务的水平分割：

bash复制tmux split-window -h -t ai_services
tmux split-window -h -t ai_services
tmux select-layout even-horizontal