Serendipity
ed91e47107
- 添加项目配置文件（tsconfig.json、bunfig.toml、.gitignore、.env.example） - 创建文档架构图（00runtime.png 至 08-state-data-flow.png） - 添加核心工具常量定义（FileEditTool、AgentTool、BashTool 等） - 实现基础命令框架（help、exit、config、model 等） - 添加 Ink TUI 组件库和布局引擎 - 包含内存管理、沙箱、shell 工具等基础工具类 - 设置预加载脚本和版本信息
410 lines
8.3 KiB
Markdown
410 lines
8.3 KiB
Markdown
# Claude Code Haha 运行教程
|
||
|
||
> 本教程详细介绍如何在 Windows 环境下运行 Claude Code Haha。
|
||
|
||
## 目录
|
||
|
||
1. [前置要求](#1-前置要求)
|
||
2. [安装 Bun 运行时](#2-安装-bun-运行时)
|
||
3. [克隆与依赖安装](#3-克隆与依赖安装)
|
||
4. [环境配置](#4-环境配置)
|
||
5. [运行方式](#5-运行方式)
|
||
6. [高级配置](#6-高级配置)
|
||
7. [常见问题](#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
|
||
powershell -c "irm bun.sh/install.ps1 | iex"
|
||
```
|
||
|
||
### 方法二：Scoop 安装
|
||
|
||
```powershell
|
||
scoop install bun
|
||
```
|
||
|
||
### 验证安装
|
||
|
||
```powershell
|
||
bun --version
|
||
```
|
||
|
||
应显示类似 `Bun v1.x.x` 的版本信息。
|
||
|
||
---
|
||
|
||
## 3. 克隆与依赖安装
|
||
|
||
### 克隆项目
|
||
|
||
```powershell
|
||
git clone <仓库地址> claude-code-haha
|
||
cd claude-code-haha
|
||
```
|
||
|
||
### 安装依赖
|
||
|
||
```powershell
|
||
bun install
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 环境配置
|
||
|
||
### 4.1 复制环境变量模板
|
||
|
||
```powershell
|
||
cp .env.example .env
|
||
```
|
||
|
||
### 4.2 编辑 .env 文件
|
||
|
||
使用文本编辑器打开 `.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 端点兼容性
|
||
|
||
Claude Code Haha 支持任何 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）
|
||
|
||
```powershell
|
||
bun --env-file=.env ./src/entrypoints/cli.tsx
|
||
```
|
||
|
||
#### 无头模式（单次问答）
|
||
|
||
```powershell
|
||
bun --env-file=.env ./src/entrypoints/cli.tsx -p "解释这段代码的作用"
|
||
```
|
||
|
||
#### 管道输入模式
|
||
|
||
```powershell
|
||
echo "帮我写一个 Hello World" | bun --env-file=.env ./src/entrypoints/cli.tsx -p
|
||
```
|
||
|
||
#### 查看帮助
|
||
|
||
```powershell
|
||
bun --env-file=.env ./src/entrypoints/cli.tsx --help
|
||
```
|
||
|
||
### 5.2 方式二：使用启动脚本（需 Git Bash）
|
||
|
||
如果你使用 Git Bash 或 MSYS2 终端：
|
||
|
||
```bash
|
||
# 交互模式
|
||
./bin/claude-haha
|
||
|
||
# 无头模式
|
||
./bin/claude-haha -p "your prompt here"
|
||
```
|
||
|
||
> ⚠️ 注意：Windows 原生终端（cmd/PowerShell）无法直接运行 bash 脚本。
|
||
|
||
### 5.3 方式三：降级 Recovery CLI 模式
|
||
|
||
如果完整 TUI 出现问题，可以使用简化版：
|
||
|
||
```powershell
|
||
bun --env-file=.env ./src/localRecoveryCli.ts
|
||
```
|
||
|
||
或设置环境变量：
|
||
|
||
```powershell
|
||
$env:CLAUDE_CODE_FORCE_RECOVERY_CLI="1"
|
||
bun --env-file=.env ./src/entrypoints/cli.tsx
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 高级配置
|
||
|
||
### 6.1 使用 Windows 原生路径
|
||
|
||
如果你希望在 Windows 路径下工作：
|
||
|
||
```powershell
|
||
# 设置工作目录
|
||
cd D:\Projects\my-project
|
||
|
||
# 运行 Claude Code
|
||
bun --env-file=.env ./src/entrypoints/cli.tsx
|
||
```
|
||
|
||
### 6.2 多会话支持
|
||
|
||
Claude Code 支持多会话管理：
|
||
|
||
```powershell
|
||
# 查看当前会话
|
||
./bin/claude-haha session list
|
||
|
||
# 切换会话
|
||
./bin/claude-haha session switch <session-id>
|
||
|
||
# 新建会话
|
||
./bin/claude-haha session new
|
||
```
|
||
|
||
### 6.3 MCP 服务器配置
|
||
|
||
Claude Code 支持 MCP (Model Context Protocol) 服务器：
|
||
|
||
```powershell
|
||
# 查看 MCP 配置
|
||
./bin/claude-haha mcp list
|
||
|
||
# 添加 MCP 服务器
|
||
./bin/claude-haha mcp add <server-name> <command> [args...]
|
||
```
|
||
|
||
### 6.4 自定义快捷键
|
||
|
||
编辑 `~/.claude/settings.json`（用户配置目录）：
|
||
|
||
```json
|
||
{
|
||
"keybindings": {
|
||
"abort": "Ctrl+C",
|
||
"scrollUp": "PageUp",
|
||
"scrollDown": "PageDown"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.5 代理配置
|
||
|
||
如果需要通过代理访问 API：
|
||
|
||
```env
|
||
# 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 日志与调试
|
||
|
||
```powershell
|
||
# 启用调试日志
|
||
$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. 尝试使用降级模式：
|
||
|
||
```powershell
|
||
$env:CLAUDE_CODE_FORCE_RECOVERY_CLI="1"
|
||
bun --env-file=.env ./src/entrypoints/cli.tsx
|
||
```
|
||
|
||
### Q2: Enter 键无响应
|
||
|
||
**原因：** `modifiers-napi` 原生模块缺失
|
||
|
||
**解决方法：**
|
||
```powershell
|
||
# 确保使用较新版本的 Bun
|
||
bun upgrade
|
||
```
|
||
|
||
### Q3: API 请求超时
|
||
|
||
**解决方法：** 增加超时时间
|
||
|
||
```env
|
||
API_TIMEOUT_MS=600000 # 10 分钟
|
||
```
|
||
|
||
### Q4: 中文显示乱码
|
||
|
||
**解决方法：** 确保终端编码为 UTF-8
|
||
|
||
```powershell
|
||
# PowerShell 设置
|
||
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
|
||
|
||
# 或使用 Windows Terminal（推荐）
|
||
```
|
||
|
||
### Q5: 权限被拒绝（Windows）
|
||
|
||
**解决方法：** 以管理员身份运行终端，或修改项目目录权限
|
||
|
||
```powershell
|
||
icacls . /grant Everyone:F /t
|
||
```
|
||
|
||
### Q6: 无法找到 Bun
|
||
|
||
**解决方法：** 确保 Bun 已正确安装并添加到 PATH
|
||
|
||
```powershell
|
||
# 检查 Bun 路径
|
||
where bun
|
||
|
||
# 如果找不到，重新安装
|
||
powershell -c "irm bun.sh/install.ps1 | iex"
|
||
```
|
||
|
||
### Q7: 工具执行被拒绝
|
||
|
||
Claude Code 默认会询问权限来执行危险操作（如删除文件、执行命令）。
|
||
|
||
**解决方法：**
|
||
- 在提示时输入 `y` 确认
|
||
- 或设置自动批准规则（谨慎使用）：
|
||
|
||
```env
|
||
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*
|