claude-code/TUTORIAL.md

LHY Code 运行教程

本教程详细介绍如何在 Windows 环境下运行 LHY Code。

目录

1. 前置要求
2. 安装 Bun 运行时
3. 克隆与依赖安装
4. 环境配置
5. 运行方式
6. 高级配置
7. 常见问题

---

1. 前置要求

系统要求

项目	要求
操作系统	Windows 10/11 (推荐)
终端	PowerShell 5.1+ 或 Windows Terminal
Git	Git for Windows (用于 Shell 命令执行)
网络	能够访问你的 API 端点

必备软件

1. Git for Windows

   • 下载地址：https://git-scm.com/download/win
   • 安装时选择 "Use Git from Bash"

2. PowerShell 7+（可选但推荐）

   • 下载地址：https://github.com/PowerShell/PowerShell/releases
   • 项目已配置 PowerShell 7.5.4 地址：D:\PowerShell\PowerShell-7.5.4

---

2. 安装 Bun 运行时

方法一：官方脚本（推荐）

在 PowerShell 中执行：

powershell -c "irm bun.sh/install.ps1 | iex"

方法二：Scoop 安装

scoop install bun

验证安装

bun --version

应显示类似 Bun v1.x.x 的版本信息。

---

3. 克隆与依赖安装

克隆项目

git clone <仓库地址> lhy-code
cd lhy-code

安装依赖

bun install

---

4. 环境配置

4.1 复制环境变量模板

cp .env.example .env

4.2 编辑 .env 文件

使用文本编辑器打开 .env 文件，配置以下内容：

# ====================
# API 认证配置（必填）
# ====================

# 方式一：使用 API Key（通过 x-api-key 头发送）
ANTHROPIC_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

# 方式二：使用 Auth Token（通过 Authorization: Bearer 头发送）
# ANTHROPIC_AUTH_TOKEN=sk-xxxxxxxxxxxxxxxxxxxxxxxx

# ====================
# API 端点配置（必填）
# ====================

# Anthropic 官方端点
# ANTHROPIC_BASE_URL=https://api.anthropic.com

# MiniMax 端点（示例）
ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic

# OpenRouter 端点（示例）
# ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1

# ====================
# 模型配置
# ====================

# 默认模型
ANTHROPIC_MODEL=MiniMax-M2.7-highspeed

# 不同任务的模型映射
ANTHROPIC_DEFAULT_SONNET_MODEL=MiniMax-M2.7-highspeed
ANTHROPIC_DEFAULT_HAIKU_MODEL=MiniMax-M2.7-highspeed
ANTHROPIC_DEFAULT_OPUS_MODEL=MiniMax-M2.7-highspeed

# ====================
# 超时与网络
# ====================

# API 请求超时（毫秒），默认 10 分钟
API_TIMEOUT_MS=3000000

# 禁用遥测（推荐设为 1）
DISABLE_TELEMETRY=1

# 禁用非必要网络请求（推荐设为 1）
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

4.3 配置说明

API 端点兼容性

LHY Code 支持任何 Anthropic 兼容 API，以下是常用配置：

服务	BASE_URL	模型示例
Anthropic 官方	https://api.anthropic.com	claude-sonnet-4-5
MiniMax	https://api.minimaxi.com/anthropic	MiniMax-M2.7-highspeed
OpenRouter	https://openrouter.ai/api/v1	anthropic/claude-3.5-sonnet
Groq	https://api.groq.com/openai/v1	llama-3.1-70b-versatile
AWS Bedrock	（使用 AWS SDK）	Claude 3 系列

认证方式

方式	环境变量	说明
API Key	ANTHROPIC_API_KEY	标准方式，通过 x-api-key 头发送
Bearer Token	ANTHROPIC_AUTH_TOKEN	通过 Authorization: Bearer 头发送

---

5. 运行方式

5.1 方式一：PowerShell 直接运行（推荐）

交互模式（完整 TUI）

bun --env-file=.env ./src/entrypoints/cli.tsx

无头模式（单次问答）

bun --env-file=.env ./src/entrypoints/cli.tsx -p "解释这段代码的作用"

管道输入模式

echo "帮我写一个 Hello World" | bun --env-file=.env ./src/entrypoints/cli.tsx -p

查看帮助

bun --env-file=.env ./src/entrypoints/cli.tsx --help

5.2 方式二：使用启动脚本（需 Git Bash）

如果你使用 Git Bash 或 MSYS2 终端：

# 交互模式
./bin/lhy-code

# 无头模式
./bin/lhy-code -p "your prompt here"

⚠️ 注意：Windows 原生终端（cmd/PowerShell）无法直接运行 bash 脚本。

5.3 方式三：降级 Recovery CLI 模式

如果完整 TUI 出现问题，可以使用简化版：

bun --env-file=.env ./src/localRecoveryCli.ts

或设置环境变量：

$env:CLAUDE_CODE_FORCE_RECOVERY_CLI="1"
bun --env-file=.env ./src/entrypoints/cli.tsx

---

6. 高级配置

6.1 使用 Windows 原生路径

如果你希望在 Windows 路径下工作：

# 设置工作目录
cd D:\Projects\my-project

# 运行 LHY Code
bun --env-file=.env ./src/entrypoints/cli.tsx

6.2 多会话支持

LHY Code 支持多会话管理：

# 查看当前会话
./bin/lhy-code session list

# 切换会话
./bin/lhy-code session switch <session-id>

# 新建会话
./bin/lhy-code session new

6.3 MCP 服务器配置

LHY Code 支持 MCP (Model Context Protocol) 服务器：

# 查看 MCP 配置
./bin/lhy-code mcp list

# 添加 MCP 服务器
./bin/lhy-code mcp add <server-name> <command> [args...]

6.4 自定义快捷键

编辑 ~/.claude/settings.json（用户配置目录）：

{
  "keybindings": {
    "abort": "Ctrl+C",
    "scrollUp": "PageUp",
    "scrollDown": "PageDown"
  }
}

6.5 代理配置

如果需要通过代理访问 API：

# HTTP 代理
HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080

# 或者在 .env 中设置
ANTHROPIC_BASE_URL=http://your-proxy/anthropic/v1

6.6 日志与调试

# 启用调试日志
$env:CLAUDE_CODE_DEBUG="1"

# 查看详细错误
bun --env-file=.env ./src/entrypoints/cli.tsx 2>&1 | tee debug.log

---

7. 常见问题

Q1: 启动后界面卡住不动

解决方法：

1. 检查 API Key 是否正确配置
2. 检查网络连接是否正常
3. 尝试使用降级模式：

$env:CLAUDE_CODE_FORCE_RECOVERY_CLI="1"
bun --env-file=.env ./src/entrypoints/cli.tsx

Q2: Enter 键无响应

原因： modifiers-napi 原生模块缺失

解决方法：

# 确保使用较新版本的 Bun
bun upgrade

Q3: API 请求超时

解决方法： 增加超时时间

API_TIMEOUT_MS=600000  # 10 分钟

Q4: 中文显示乱码

解决方法： 确保终端编码为 UTF-8

# PowerShell 设置
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

# 或使用 Windows Terminal（推荐）

Q5: 权限被拒绝（Windows）

解决方法： 以管理员身份运行终端，或修改项目目录权限

icacls . /grant Everyone:F /t

Q6: 无法找到 Bun

解决方法： 确保 Bun 已正确安装并添加到 PATH

# 检查 Bun 路径
where bun

# 如果找不到，重新安装
powershell -c "irm bun.sh/install.ps1 | iex"

Q7: 工具执行被拒绝

LHY Code 默认会询问权限来执行危险操作（如删除文件、执行命令）。

解决方法：

• 在提示时输入 y 确认
• 或设置自动批准规则（谨慎使用）：

CLAUDE_CODE_ALLOW_DANGEROUS_OPERATIONS=1

---

快速参考

常用命令

命令	说明
bun --env-file=.env ./src/entrypoints/cli.tsx	交互模式
bun --env-file=.env ./src/entrypoints/cli.tsx -p "prompt"	无头模式
bun --env-file=.env ./src/entrypoints/cli.tsx --version	查看版本
bun --env-file=.env ./src/entrypoints/cli.tsx --help	查看帮助

环境变量速查

变量	必填	默认值	说明
ANTHROPIC_API_KEY	是*	-	API Key
ANTHROPIC_AUTH_TOKEN	是*	-	Auth Token（二选一）
ANTHROPIC_BASE_URL	是	api.anthropic.com	API 端点
ANTHROPIC_MODEL	否	claude-sonnet-4-20250514	默认模型
DISABLE_TELEMETRY	否	0	设为 1 禁用遥测

---

文档版本：1.0.0 最后更新：2026-04-02