claude-web-serve

将 Claude Code Agent SDK 封装为 HTTP API 服务，让你可以在任何语言、任何平台上调用 Claude Code。

为什么需要它

Claude Code 有强大的 CLI，但没有 HTTP API。claude-web-serve 填补了这个空白 —— 将 Claude Code 暴露为 REST 服务，提供以下能力：

• Project 隔离的 Session 管理：不同项目的对话互不干扰
• SSE 流式输出：实时推送 Claude 的输出，无需等待完整响应
• 文件系统接口：读取项目文件树和文件内容，支持构建 @文件 引用等富交互
• 多轮对话：自动维护上下文，无需手动管理对话历史

Session 按 Project 自动隔离：

• git 仓库：以根 commit hash（git rev-list --max-parents=0 HEAD）作为 Project ID
• 非 git 目录：以目录路径的 SHA-256 hash 作为 Project ID

快速开始

安装

npm install -g @claude-web-serve/api

注册项目

在每个需要使用的项目目录执行一次：

cd /your/project-a
claude-web init

cd /your/project-b
claude-web init

启动服务

在任意位置启动一次即可，服务会加载所有已注册的项目：

claude-web start

# 指定端口
claude-web start --port 8080

命令说明

claude-web init [options]
  -c, --cwd <path>         要注册的目录（默认：当前目录）

claude-web start [options]
  -p, --port <number>      监听端口（默认：8003）
  -H, --hostname <string>  绑定地址（默认：127.0.0.1）

API 文档

Base URL：http://127.0.0.1:8003

健康检查

GET /health
→ { healthy: true, version: "x.x.x" }

Project

GET /project                          列出所有已注册的 Project
GET /project/:id/session              获取指定 Project 的 Session 列表
GET /project/:id/tree?path=/          获取文件目录树
GET /project/:id/file?path=/src/a.ts  读取文件内容

Project 对象：

{
  "id": "a1b2c3d4e5f6a1b2",
  "cwd": "/your/project",
  "sessionCount": 3,
  "updatedAt": 1700000001000
}

文件树节点：

[
  {
    "name": "src",
    "path": "/src",
    "type": "dir",
    "children": [
      { "name": "index.ts", "path": "/src/index.ts", "type": "file" }
    ]
  }
]

文件树默认忽略 .git、node_modules、dist、.next、.cache 等目录，最大深度 8 层，单文件读取上限 1MB。

文件内容：

{ "path": "/src/index.ts", "content": "...", "size": 1024 }

Session 管理

GET    /session                   获取当前服务器的 Session 列表
POST   /session                   创建新 Session    body: { cwd: string }
GET    /session/:id               获取 Session 详情
DELETE /session/:id               删除 Session

Session 对象：

{
  "id": "ses_abc123",
  "title": "第一条消息的预览...",
  "cwd": "/your/project",
  "status": "idle",
  "time": { "created": 1700000000000, "updated": 1700000001000 }
}

消息

GET  /session/:id/message              获取消息历史    query: limit, offset
POST /session/:id/message              发送消息（阻塞）  body: { prompt: string }
POST /session/:id/message?stream=1     发送消息（SSE）   body: { prompt: string }

阻塞模式

等待 Claude 完成后一次性返回完整的 Assistant 消息：

SESSION=$(curl -s -X POST http://127.0.0.1:8003/session \
  -H "Content-Type: application/json" \
  -d '{"cwd":"/your/project"}' | jq -r '.id')

curl -s -X POST http://127.0.0.1:8003/session/$SESSION/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "列出当前目录的文件"}'

{
  "id": "msg_xyz",
  "sessionID": "ses_abc123",
  "role": "assistant",
  "parts": [
    { "type": "text", "text": "以下是结果..." },
    { "type": "tool_call", "tool": "Bash", "input": { "command": "ls" } },
    { "type": "tool_result", "content": "file1.ts\nfile2.ts" }
  ],
  "cost": 0.00123,
  "tokens": { "input": 1200, "output": 340, "cache": { "read": 0, "write": 0 } },
  "time": { "created": 1700000000000, "completed": 1700000005000 }
}

SSE 流式模式

加 ?stream=1 切换为 Server-Sent Events，边生成边推送：

curl -s -X POST "http://127.0.0.1:8003/session/$SESSION/message?stream=1" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"prompt": "列出当前目录的文件"}'

响应为 SSE 流，包含三种事件：

event: part
data: {"id":"prt_...","type":"text","text":"以下是结果..."}

event: part
data: {"id":"prt_...","type":"tool_call","tool":"Bash","input":{"command":"ls"}}

event: part
data: {"id":"prt_...","type":"tool_result","content":"file1.ts\nfile2.ts"}

event: done
data: {"id":"msg_xyz","role":"assistant","parts":[...],"cost":0.00123,...}

| 事件 | 说明 | |---|---| | part | 每产生一个 part（text / tool_call / tool_result）推送一次 | | done | Agent 完成，携带完整的 Message 对象（含 cost、tokens） | | error | 出现错误，携带 { message: string } |

数据存储

Session 和消息持久化到 ~/.claude-web-serve/，按 Project 分目录存储：

~/.claude-web-serve/
└── {projectID}/              # git 根 commit hash 或路径 hash（16位）
    ├── project.json          # Project 元数据（cwd 等）
    └── {sessionID}/
        ├── session.json      # Session 元数据
        └── messages.jsonl    # 消息历史（每行一条 JSON）

本地开发

环境要求

• Node.js >= 20
• pnpm >= 9
• Claude Code CLI 已安装并完成认证（claude 在 PATH 中）

启动

git clone https://github.com/dwqdaiwenqi/claude-web-serve
cd claude-web-serve
pnpm install
pnpm dev        # 同时启动 API 服务和示例前端

目录结构

claude-web-serve/
├── packages/
│   ├── api/                  # HTTP 服务
│   │   └── src/
│   │       ├── cli.ts        # CLI 入口（commander）
│   │       ├── server.ts     # Fastify 路由 + Agent 执行
│   │       ├── store.ts      # Session 和消息持久化
│   │       └── logger.ts     # Pino 日志
│   └── example/              # React + Ant Design 示例前端
│       └── src/
│           ├── App.tsx
│           ├── api.ts
│           └── main.tsx
└── package.json

环境变量

| 变量 | 默认值 | 说明 | |---|---|---| | LOG_LEVEL | debug | 日志级别（trace / debug / info / warn / error） | | NODE_ENV | — | 设为 production 时输出 JSON 格式日志 |

License

MIT