📅 难度：⭐☆☆☆☆ 进阶｜阅读约 10 分钟｜适用：Spring Boot 2.7.x / 3.x ｜ Java 17+

前言

在大模型技术飞速发展的今天，越来越多的 Java 后端开发者开始尝试将 AI 能力引入自己的项目。OpenClAW（Open Claude API Wrapper）是一个专为 Java/Spring 生态设计的轻量级封装库，它屏蔽了底层 HTTP 请求的复杂度，让开发者可以用极少的代码快速接入 Claude 大模型 API。

本文是《OpenClAW + Spring Boot 系列》的第 1 篇，目标是帮助你：

理解 OpenClAW 的定位与核心概念
完成 Spring Boot 项目的环境搭建
配置 API Key 等必要参数
调通第一个 AI 对话接口（Hello World 级别）
理解请求与响应的基本数据结构

本系列共 6 篇，由浅入深覆盖：基础集成 → 服务封装 → 流式输出 → 多轮对话 → Function Calling → 生产级部署。建议按顺序阅读。

一、核心概念：OpenClAW 是什么？

在开始写代码之前，先用 3 分钟搞清楚几个概念，后续开发会省去很多困惑。

1.1 Claude API 与 OpenClAW 的关系

Claude API 是 Anthropic 官方提供的 RESTful 接口，通过 HTTP POST 请求发送消息、获取模型回复。开发者可以直接用 HttpClient 或 RestTemplate 调用，但需要自己处理：

请求头的组装（API Key、版本号等）
JSON 序列化与反序列化
流式响应（SSE）的解析
异常分类与重试逻辑

OpenClAW 将上述繁琐工作封装成简洁的 Java API，让你只需关注业务逻辑。二者关系如下：

|-------------------|-----------------|----------------|
| 层次 | 角色 | 你需要关心的 |
| Claude API | Anthropic 官方服务层 | 几乎不需要直接接触 |
| OpenClAW | Java 封装层（本系列主角） | 配置 + 调用方法 |
| 你的 Spring Boot 服务 | 业务层 | 业务逻辑 + 接口设计 |

1.2 关键术语速查

|---------------|-------------------------------------------|
| 术语 | 解释 |
| model | 使用的模型名称，如 claude-sonnet-4-20250514 |
| message | 一条对话消息，包含 role（user/assistant）和 content |
| max_tokens | 本次回复最多生成的 token 数（约 0.75 个英文单词 = 1 token） |
| stream | 是否启用流式输出（Server-Sent Events） |
| system prompt | 系统级指令，控制模型的角色和行为方式 |

二、环境准备

2.1 前置要求

在开始之前，请确认以下条件已满足：

|-------------------|------------------------|--------------------------|
| 环境 | 版本要求 | 说明 |
| JDK | 17 或以上 | 推荐 JDK 21 LTS |
| Spring Boot | 2.7.x 或 3.x | 两个版本均支持 |
| Maven / Gradle | Maven 3.6+ / Gradle 7+ | 任选其一 |
| Anthropic API Key | 已注册并获取 | 前往 console.anthropic.com |
| IDE | IntelliJ IDEA 推荐 | VS Code 也可 |

API Key 申请地址：https://console.anthropic.com/settings/keys。新账号有免费额度，足够完成本系列所有示例（用其他大模型也可）。

2.2 创建 Spring Boot 项目

推荐使用 Spring Initializr（https://start.spring.io）快速生成骨架，配置如下：

|--------------|--------------------|
| 选项 | 推荐值 |
| Project | Maven |
| Language | Java |
| Spring Boot | 3.2.x（或最新稳定版） |
| Group | com.example |
| Artifact | openclaw-demo |
| Packaging | Jar |
| Java | 17 |
| Dependencies | Spring Web, Lombok |

下载解压后，用 IDEA 打开项目。

三、集成 OpenClAW

3.1 添加 Maven 依赖

打开 pom.xml，在 <dependencies> 中添加以下内容：

XML 复制代码

<!-- pom.xml -->
<dependencies>

    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>


    <!-- OpenClAW：Spring Boot 自动配置版 -->
    <dependency>
        <groupId>io.github.openclaw</groupId>
        <artifactId>openclaw-spring-boot-starter</artifactId>
        <version>1.0.2</version>
    </dependency>


    <!-- Lombok（可选，减少样板代码） --
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>

    <!-- 测试 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>

</dependencies>

⚠️ 请在 Maven Central 确认 openclaw-spring-boot-starter 的最新版本，示例中的版本号仅供参考，实际以官方发布为准。

如果你使用 Gradle，在 build.gradle 中添加：

java 复制代码

dependencies {

    implementation 'org.springframework.boot:spring-boot-starter-web'

    implementation 'io.github.openclaw:openclaw-spring-boot-starter:1.0.2'

    compileOnly 'org.projectlombok:lombok'

    annotationProcessor 'org.projectlombok:lombok'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'

}

3.2 配置 API Key

打开 src/main/resources/application.yml，添加以下配置：

java 复制代码

spring:
  application:
    name: openclaw-demo

openclaw:
  api-key: ${ANTHROPIC_API_KEY}          # 从环境变量读取（推荐）
  default-model: claude-sonnet-4-20250514 # 默认使用的模型
  max-tokens: 1024                        # 默认最大输出 token 数
  timeout: 60                             # 请求超时时间（秒）

server:
  port: 8080

强烈建议通过环境变量传入 API Key，而非硬编码在配置文件中。可在 IDEA 的 Run/Debug Configuration → Environment variables 中设置 ANTHROPIC_API_KEY=sk-ant-xxx。

如果你希望在开发环境直接写入（不推荐上传 git），可以使用：

openclaw:

api-key: sk-ant-api03-xxxxxxxxxxxxxxxx # 直接填写（仅本地开发，切勿提交 git）

四、自动配置原理（简要了解）

添加 openclaw-spring-boot-starter 依赖后，框架会自动完成以下工作，你无需手动配置：

读取 application.yml 中 openclaw.* 的配置项，封装为 OpenClawProperties 对象
自动创建 ClaudeClient Bean（核心 HTTP 客户端），注入到 Spring 容器
自动创建 ClaudeService Bean（高级封装），提供常用的同步/异步调用方法
注册全局异常处理器，将 API 错误转换为标准 Spring 异常

这是典型的 Spring Boot 自动装配（Auto-Configuration）机制。如果你对底层实现感兴趣，可以查看 jar 包中的 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件。

五、Hello World：调通第一个 AI 对话

5.1 编写 Controller

在 src/main/java/com/example/openclaw_demo 目录下创建 controller 包，新建 ChatController.java：

java 复制代码

package com.example.openclaw_demo.controller;

 
import io.openclaw.client.ClaudeService;
import io.openclaw.model.request.ChatRequest;
import io.openclaw.model.response.ChatResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;

 
/**
 * 第一个 AI 对话接口
 * GET /api/chat/hello - 快速测试
 * POST /api/chat      - 标准对话接口
 */
@RestController
@RequestMapping("/api/chat")
@RequiredArgsConstructor
public class ChatController {


    // Spring 自动注入，无需手动创建
    private final ClaudeService claudeService;

 
    /**
     * GET 接口：快速验证配置是否正确
     * 访问 http://localhost:8080/api/chat/hello
     */
    @GetMapping("/hello")
    public String hello() {
        return claudeService.chat("请用一句话介绍你自己。");
    }


    /**
     * POST 接口：标准对话（接收用户输入）
     * Body: { "message": "你好" }
     */
    @PostMapping
    public ChatResponse chat(@RequestBody ChatRequest request) {
        return claudeService.chat(request);
    }


}

5.2 请求与响应数据结构

ClaudeService 中使用的核心数据类如下：

ChatRequest --- 请求体

java 复制代码

public class ChatRequest {

    private String model;          // 模型名，不填则使用配置中的默认值
    private Integer maxTokens;     // 最大输出 token 数
    private String systemPrompt;   // 系统提示词（可选）


    // 消息列表（支持多轮对话，详见第 4 篇）
    private List<Message> messages;

    // 便捷静态工厂方法：单轮对话
    public static ChatRequest of(String userMessage) { ... }

    // 链式构建器
    public static Builder builder() { ... }

}

ChatResponse --- 响应体

java 复制代码

public class ChatResponse {

    private String id;             // 本次请求唯一 ID
    private String model;          // 实际使用的模型
    private String stopReason;     // 停止原因（end_turn / max_tokens 等）

    private List<Content> content; // 模型输出内容列表

    private Usage usage;           // Token 用量统计

    // 便捷方法：直接获取文本回复
    public String getText() {
        return content.stream()
            .filter(c -> "text".equals(c.getType()))
            .map(Content::getText)
            .findFirst()
            .orElse("");

    }

}

java 复制代码

public class Usage {

    private int inputTokens;       // 输入 token 数
    private int outputTokens;      // 输出 token 数

}

5.3 运行并测试

启动 Spring Boot 应用：

Maven

mvn spring-boot:run

或直接运行 main 方法

com.example.openclaw_demo.OpenClawDemoApplication

看到如下日志说明启动成功：

. ____ _ __ _ _

/\\ / _' __ _ () __ __ _ \ \ \ \

( ( )\___ | '_ | '| | ' \/ _` | \ \ \ \

\\/ _)| |)| | | | | || (| | ) ) ) )

' || .__|| ||| |\__, | / / / /

=========||==============|/=///_/

:: Spring Boot :: (v3.2.x)

... Started OpenClawDemoApplication in 2.345 seconds (process running for 2.8)

用 curl 或 Postman 测试：

方式一：GET 快速测试

curl http://localhost:8080/api/chat/hello

预期响应（示例）：

"我是 Claude，Anthropic 开发的 AI 助手，很高兴认识你！"

方式二：POST 标准对话

curl -X POST http://localhost:8080/api/chat \

-H "Content-Type: application/json" \

-d '{"message": "Java 和 Python 哪个更适合做后端？"}'

POST 响应示例（精简后）：

java 复制代码

{

  "id": "msg_01XqRt9K...",
  "model": "claude-sonnet-4-20250514",
  "stopReason": "end_turn",
  "content": [
    {
      "type": "text",
      "text": "Java 和 Python 各有优劣。Java 适合高并发、强类型的企业级...(省略)"
    }
  ],
  "usage": {
    "inputTokens": 28,
    "outputTokens": 156
  }
}

看到正常的 JSON 响应，恭喜你！第一个 AI 接口已经跑通了。接下来我们继续完善代码

六、进阶：使用系统提示词与构建器

实际项目中，你通常需要给模型设定角色或约束行为，这时就要用到 systemPrompt（系统提示词）。

java 复制代码

@GetMapping("/assistant")
public String getAssistantResponse() {

    ChatRequest request = ChatRequest.builder()
        .systemPrompt("你是一名专业的 Java 后端工程师助手，"
            + "回答简洁专业，遇到代码问题请给出可运行的示例。")
        .message("Spring Boot 如何配置连接池？")
        .maxTokens(512)
        .build();

    ChatResponse response = claudeService.chat(request);
 
    // 直接获取文本内容
    return response.getText();
}

七、常见问题排查

|-----------------------|--------------------------|----------------------------------|
| 错误现象 | 可能原因 | 解决方法 |
| 401 Unauthorized | API Key 错误或未配置 | 检查环境变量 ANTHROPIC_API_KEY 是否正确 |
| Connection timeout | 网络无法访问 api.anthropic.com | 检查网络/代理设置，或配置 HTTP 代理 |
| 429 Too Many Requests | 请求频率超限 | 降低调用频率，或升级 API 套餐 |
| Bean 注入失败 | 依赖版本冲突 | 检查 Spring Boot 版本与 starter 版本兼容性 |
| max_tokens 超限 | 回复被截断 | 增大 max-tokens 配置值 |

八、完整项目结构

完成本篇后，你的项目结构应如下：

openclaw-demo/

├── src/

│ ├── main/

│ │ ├── java/

│ │ │ └── com/example/openclaw_demo/

│ │ │ ├── OpenClawDemoApplication.java # 启动类

│ │ │ └── controller/

│ │ │ └── ChatController.java # 本篇新建

│ │ └── resources/

│ │ └── application.yml # 配置文件

│ └── test/

│ └── java/

│ └── com/example/openclaw_demo/

│ └── ChatControllerTest.java # 可选：单元测试

└── pom.xml

九、附加：编写简单的单元测试

好的习惯从第一行代码开始。为 Controller 补充一个基础集成测试：

java 复制代码

package com.example.openclaw_demo;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import io.openclaw.client.ClaudeService;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest
class ClaudeServiceIntegrationTest {

    @Autowired
    private ClaudeService claudeService;


    @Test
    void testSimpleChat() {

        String response = claudeService.chat("请用一句话解释什么是 Spring Boot。");

        System.out.println("AI 回复：" + response);

        // 断言：回复非空且不是错误信息
        assertThat(response).isNotBlank();
        assertThat(response.length()).isGreaterThan(10);
    }

}

⚠️ 集成测试会真实调用 API，会消耗 token 额度。建议在 CI 中通过 Mock 替代，或使用 @Tag 标注为手动运行。

十、本篇总结

恭喜完成第 1 篇！让我们回顾一下本文涵盖的核心内容：

了解了 Claude API、OpenClAW、Spring Boot 三层关系
通过 Spring Initializr 创建了项目骨架
在 pom.xml 添加了 openclaw-spring-boot-starter 依赖
在 application.yml 完成了 API Key 与基础参数配置
编写了 ChatController，实现了 GET 与 POST 两个对话接口
理解了 ChatRequest / ChatResponse 的核心字段含义
用 curl 成功验证了接口调用

现在你已经拥有了一个能跑的 AI 接口骨架。但直接在 Controller 里调用 ClaudeService 还不够优雅，下一篇我们将进行工程化改造------封装 Service 层、统一配置管理、处理异常与重试，打造生产级别的服务架构。

如果本文对你有帮助，欢迎点赞、收藏、关注，你的支持是我持续创作的动力！

Spring Boot 项目集成 OpenClAW【OpenClAW + Spring Boot 系列 第1篇】

前言

一、核心概念：OpenClAW 是什么？

1.1 Claude API 与 OpenClAW 的关系

1.2 关键术语速查

二、环境准备

2.1 前置要求

2.2 创建 Spring Boot 项目

三、集成 OpenClAW

3.1 添加 Maven 依赖

3.2 配置 API Key

四、自动配置原理（简要了解）

五、Hello World：调通第一个 AI 对话

5.1 编写 Controller

5.2 请求与响应数据结构

ChatRequest --- 请求体

ChatResponse --- 响应体

5.3 运行并测试

Maven

或直接运行 main 方法

com.example.openclaw_demo.OpenClawDemoApplication

方式一：GET 快速测试

预期响应（示例）：

方式二：POST 标准对话

六、进阶：使用系统提示词与构建器

七、常见问题排查

八、完整项目结构

九、附加：编写简单的单元测试

十、本篇总结

Spring Boot 项目集成 OpenClAW【OpenClAW + Spring Boot 系列第1篇】