DoneHub

阿里云百炼 Coding Plan 官方宣称”仅限编程工具使用”，但实际上其 endpoint 基于 OpenAI 兼容协议，Java/Python 应用完全可以调用。本文分享如何用 LangChain4j 和 OpenAI SDK 突破这一限制，直接消耗 Coding Plan 额度。

一、背景：一个被”误解”的服务

阿里云百炼的 Coding Plan 是一项面向 AI 编程助手的服务套餐，提供专门的模型调用额度。官方客服的说法是：

“Coding Plan 的专属 API Key（格式为 sk-sp-xxxxx）仅限在支持的编程工具（如 Claude Code、OpenClaw 等）中使用，不能用于 Java 应用直接调用大模型。若您的 Java 应用需要调用百炼大模型，请使用百炼通用 API Key（格式为 sk-xxxxx），该 Key 支持调用包括 Coding 模型在内的所有百炼模型，并按量计费。”

这意味着如果你想在 Java 应用中使用百炼大模型，需要：

1. 额外开通百炼通用 API Key（格式为 sk-xxxxx）
2. 按量付费，产生额外费用

但实际上，Coding Plan 的额度完全可以在 Java/Python 应用中使用！ 本文将分享这个”奇技淫巧”。

二、问题发现：为什么 Coding Plan Key 在 Java 中”失效”？

2.1 错误的调用方式

很多开发者（包括我）最初使用阿里云官方的 dashscope-sdk-java 调用百炼：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// pom.xml
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>dashscope-sdk-java</artifactId>
    <version>2.22.15</version>
</dependency>

// Java 代码
Generation gen = new Generation();
GenerationParam param = GenerationParam.builder()
    .apiKey("sk-sp-xxxxx")  // Coding Plan API Key
    .model("qwen-plus")
    .messages(messages)
    .build();
GenerationResult result = gen.call(param);

结果：API 返回 InvalidApiKey 错误，或者即使调通了，消耗的是通用额度而非 Coding Plan 额度！

2.2 根本原因分析

Coding Plan 的 API Key 使用的是 OpenAI 兼容协议，endpoint 地址不同于通用百炼服务：

官方的 dashscope-sdk-java 只支持通用百炼 endpoint，无法连接 Coding Plan 的 endpoint！

三、解决方案：使用 OpenAI 兼容模式

3.1 技术原理

Coding Plan 的 endpoint 基于 OpenAI API 兼容协议，任何支持 OpenAI API 的客户端都可以调用：

1. Python: 使用 openai SDK
2. Java: 使用 LangChain4j 的 langchain4j-open-ai 模块

只要将 base_url 指向 Coding Plan 的 endpoint，API Key 就能正常工作！

四、Java 实现：LangChain4j + Coding Plan

4.1 添加依赖

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<!-- pom.xml -->
<properties>
    <langchain4j.version>0.35.0</langchain4j.version>
</properties>

<dependencies>
    <!-- LangChain4j OpenAI 兼容模块 -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j</artifactId>
        <version>${langchain4j.version}</version>
    </dependency>
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-open-ai</artifactId>
        <version>${langchain4j.version}</version>
    </dependency>
</dependencies>

4.2 配置文件

1
2
3
4
5
6

# application.properties - Coding Plan 配置
langchain4j.open-ai.chat-model.base-url=https://coding.dashscope.aliyuncs.com/v1
langchain4j.open-ai.chat-model.api-key=sk-sp-xxxxx
langchain4j.open-ai.chat-model.model-name=kimi-k2.5
langchain4j.open-ai.chat-model.temperature=0.3
langchain4j.open-ai.chat-model.max-tokens=4096

关键点：base-url 必须是 coding.dashscope.aliyuncs.com/v1，不是通用的 dashscope.aliyuncs.com！

4.3 Java 代码实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

import dev.langchain4j.data.message.AiMessage;
import dev.langchain4j.data.message.ChatMessage;
import dev.langchain4j.data.message.SystemMessage;
import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.model.output.Response;

import java.time.Duration;
import java.util.Arrays;
import java.util.List;

public class CodingPlanExample {

    private final ChatLanguageModel chatModel;

    public CodingPlanExample(String baseUrl, String apiKey, String modelName) {
        // 使用 OpenAI 兼容模式构建 ChatModel
        this.chatModel = OpenAiChatModel.builder()
                .baseUrl(baseUrl)  // Coding Plan endpoint
                .apiKey(apiKey)    // Coding Plan API Key
                .modelName(modelName)
                .temperature(0.3)
                .maxTokens(4096)
                .timeout(Duration.ofSeconds(60))
                .build();
    }

    public String chat(String systemPrompt, String userMessage) {
        List<ChatMessage> messages = Arrays.asList(
                SystemMessage.from(systemPrompt),
                UserMessage.from(userMessage)
        );

        Response<AiMessage> response = chatModel.generate(messages);

        if (response == null || response.content() == null) {
            throw new RuntimeException("模型返回结果为空");
        }

        return response.content().text();
    }

    public static void main(String[] args) {
        CodingPlanExample example = new CodingPlanExample(
                "https://coding.dashscope.aliyuncs.com/v1",
                "sk-sp-xxxxx",
                "kimi-k2.5"
        );

        String result = example.chat(
                "你是一位专业的翻译助手",
                "将以下内容翻译为英文：你好世界"
        );

        System.out.println(result);
    }
}

4.4 Spring Boot 集成示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

@Configuration
public class LangChain4jConfig {

    @Value("${langchain4j.open-ai.chat-model.base-url}")
    private String baseUrl;

    @Value("${langchain4j.open-ai.chat-model.api-key}")
    private String apiKey;

    @Value("${langchain4j.open-ai.chat-model.model-name}")
    private String modelName;

    @Bean
    public ChatLanguageModel chatLanguageModel() {
        return OpenAiChatModel.builder()
                .baseUrl(baseUrl)
                .apiKey(apiKey)
                .modelName(modelName)
                .timeout(Duration.ofSeconds(60))
                .build();
    }
}

@Service
public class TranslationService {

    private final ChatLanguageModel chatModel;

    public TranslationService(ChatLanguageModel chatModel) {
        this.chatModel = chatModel;
    }

    public String translate(String content, String sourceLang, String targetLang) {
        String systemPrompt = String.format(
                "你是翻译专家，将内容从%s翻译为%s，直接输出结果",
                sourceLang, targetLang
        );

        List<ChatMessage> messages = Arrays.asList(
                SystemMessage.from(systemPrompt),
                UserMessage.from(content)
        );

        return chatModel.generate(messages).content().text();
    }
}

五、Python 实现：OpenAI SDK + Coding Plan

5.1 安装依赖

1

pip install openai

5.2 Python 代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

from openai import OpenAI

# 使用 Coding Plan endpoint
client = OpenAI(
    base_url="https://coding.dashscope.aliyuncs.com/v1",
    api_key="sk-sp-xxxxx"
)

response = client.chat.completions.create(
    model="kimi-k2.5",
    messages=[
        {"role": "system", "content": "你是一位专业的翻译助手"},
        {"role": "user", "content": "将以下内容翻译为英文：你好世界"}
    ],
    temperature=0.3,
    max_tokens=4096
)

print(response.choices[0].message.content)

5.3 异步调用示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

from openai import AsyncOpenAI
import asyncio

async_client = AsyncOpenAI(
    base_url="https://coding.dashscope.aliyuncs.com/v1",
    api_key="sk-sp-xxxxx"
)

async def translate_async(content: str) -> str:
    response = await async_client.chat.completions.create(
        model="kimi-k2.5",
        messages=[
            {"role": "system", "content": "你是翻译专家"},
            {"role": "user", "content": content}
        ]
    )
    return response.choices[0].message.content

# 批量翻译
async def batch_translate(contents: list[str]) -> list[str]:
    tasks = [translate_async(c) for c in contents]
    return await asyncio.gather(*tasks)

# 运行示例
async def main():
    results = await batch_translate(["你好世界", "人工智能"])
    print(results)

asyncio.run(main())

六、实际应用场景

6.1 职位内容翻译

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

@Service
public class JobTranslationService {

    private final ChatLanguageModel chatModel;

    public String translateJobDescription(String content, String sourceLang, String targetLang) {
        String systemPrompt = buildTranslationPrompt(sourceLang, targetLang);

        List<ChatMessage> messages = Arrays.asList(
                SystemMessage.from(systemPrompt),
                UserMessage.from(content)
        );

        return chatModel.generate(messages).content().text();
    }

    private String buildTranslationPrompt(String sourceLang, String targetLang) {
        return String.format("""
            你是一位专业的职位内容翻译专家。
            请将用户输入的职位描述从%s翻译为%s。

            翻译要求：
            1. 保持原文的段落结构和格式
            2. 专业术语使用行业标准翻译
            3. 直接输出翻译结果
            """, sourceLang, targetLang);
    }
}

6.2 文档内容生成

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

public String generateDocumentOutline(String topic) {
    String prompt = """
        根据以下主题，生成一份技术文档大纲：
        主题：%s

        要求：
        1. 结构清晰，层次分明
        2. 每个章节要有简要说明
        3. 使用 Markdown 格式输出
        """.formatted(topic);

    List<ChatMessage> messages = Arrays.asList(
        SystemMessage.from("你是技术文档撰写专家"),
        UserMessage.from(prompt)
    );

    return chatModel.generate(messages).content().text();
}

6.3 智能客服对话

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

@Service
public class CustomerServiceBot {

    private final ChatLanguageModel chatModel;

    public String handleUserMessage(String userMessage, List<String> history) {
        List<ChatMessage> messages = new ArrayList<>();

        // 系统提示词
        messages.add(SystemMessage.from("""
            你是专业的客服助手，帮助用户解答产品相关问题。
            回答要求：
            1. 语气友好专业
            2. 回答简洁明了
            3. 如果无法回答，引导用户联系人工客服
            """));

        // 添加历史对话
        for (String h : history) {
            messages.add(UserMessage.from(h));
        }

        // 当前消息
        messages.add(UserMessage.from(userMessage));

        return chatModel.generate(messages).content().text();
    }
}

七、关键注意事项

7.1 Endpoint 不要混用

混用会导致 InvalidApiKey 错误或消耗错误的额度！

7.2 模型名称差异

Coding Plan 支持的模型可能与通用百炼不同：

• Coding Plan: kimi-k2.5 等
• 通用百炼: qwen-plus, qwen-max, qwen-turbo

请根据实际账号支持的模型选择。

7.3 Token 消耗监控

虽然使用了 Coding Plan 额度，但仍需关注：

• 单次调用 Token 数量
• Coding Plan 额度剩余
• 设置合理的 max_tokens 防止超限

7.4 超时设置

Coding Plan 响应时间可能与通用服务不同，建议设置较长超时：

1

.timeout(Duration.ofSeconds(60))  // 或更长

八、总结

8.1 官方说法 vs 实际实践

8.2 核心原理

Coding Plan 的 endpoint 基于 OpenAI API 兼容协议，这是业界通用的 LLM API 标准。任何支持 OpenAI 协议的客户端都可以调用，不受编程工具限制。

8.3 适用场景

• ✅ Java 后端服务调用 LLM
• ✅ Python 应用调用 LLM
• ✅ Spring Boot / LangChain4j 集成
• ✅ 翻译、生成、对话等各类 NLP 任务
• ❌ 直接使用 dashscope-sdk-java（不支持 Coding Plan endpoint）

九、参考资料

• LangChain4j 官方文档
• OpenAI API 兼容协议
• 阿里百炼 Coding Plan

如果你最近关注 AI Agent 领域，可能会注意到一个新名字——Hermes Agent。它来自 Nous Research，在短短两个月内从一个小型内部项目成长为功能完备的 AI Agent 平台。这篇文章聊聊它到底有什么不一样，以及为什么值得你花时间了解。

一、Hermes Agent 是什么？

简单说，它是一个可以自我进化的 AI Agent 框架。

市面上大多数 Agent 工具，你用完一次，下次还要重新教它。你说”帮我整理今天的 Git 提交记录”，它执行了。第二天你再说同样的话，它又从头开始理解。对话结束后，一切归零。

Hermes Agent 不一样。它有个叫”技能系统”的东西。第一次你教它做某件事，完成后它会问自己：这件事我以后是不是经常要做？如果答案是肯定的，它会把整个过程打包成一个技能。下次你只需要说”整理提交”，它就能直接调用这个技能。

这不是预设好的模板，是 Agent 自己判断、自己创建、自己优化的。用久了，它会越来越懂你的工作习惯。

二、为什么突然火了？

翻一下 Hermes Agent 的版本历史，你会发现一个有意思的时间线：

从2月底到4月中旬，不到两个月，发布了10个大版本。平均每三四天一个版本。这不是营销驱动的节奏，是真实需求驱动的迭代速度。

看看 v0.2.0 的发布说明：”In just over two weeks, Hermes Agent went from a small internal project to a full-featured AI agent platform — thanks to an explosion of community contributions.”

这句话翻译过来：两个星期，从内部小项目变成完整平台，原因是社区贡献爆发。

为什么爆发？因为 Hermes Agent 解决了一个长期痛点——Agent 的记忆和学习能力。之前大家做 Agent，要么接受”每次对话归零”的现实，要么自己写一套复杂的持久化逻辑。Hermes Agent 把这套逻辑内置了，而且是真正意义上的”学习”，不只是”存储”。

三、核心特质

3.1 闭环学习，不是单次执行

这点前面说了，展开讲一下细节。

Hermes Agent 的学习机制包含几个层次：

技能自动创建：完成复杂任务后，Agent 会分析这个任务是否有重复价值。有，就创建技能。技能里包含了执行步骤、需要的工具、注意事项。

技能自我改进：你用某个技能的时候如果给了反馈，比如”这次格式不对”或”下次加上这个字段”，Agent 会把这些反馈写进技能描述里。下一次执行会自动应用。

定期提醒：Agent 有个机制叫”periodic nudges”，会周期性地提醒自己把重要信息持久化。不是被动等待你要求，是主动思考”这个信息值得记住吗”。

跨会话搜索：你问”上次我们讨论的那个方案是什么”，它会搜索历史对话，用 LLM 做摘要，然后告诉你。这不是简单的关键词搜索，是语义层面的召回。

3.2 Honcho 用户建模

Hermes Agent 内置了一个叫 Honcho 的用户建模系统。这个名字来自 plastic-labs 的 Honcho 项目，是一个专门做”AI 理解用户”的框架。

它的作用是：Agent 会持续观察你的偏好、习惯、工作方式，然后建立一个用户模型。你喜欢简洁回复，它记住；你讨厌某种操作方式，它记住；你对某个项目有特殊约定，它跨会话保持。

这不是简单的”记住你说过的话”，是”理解你是什么样的人”。

3.3 多平台统一接入

这点对实际使用很重要。

你可以在 Telegram、Discord、Slack、WhatsApp、Signal 这些平台跟 Hermes Agent 对话，也可以在终端用 CLI。同一个 Agent，不同入口，记忆和技能是共享的。

这意味着你早上在公司电脑用 CLI 让它整理日报，晚上回家用 Telegram 继续讨论，它记得你白天说了什么。

3.4 定时任务，原生支持

大多数 Agent 框架没有内置的定时任务系统。你想让 Agent 每天早上自动发日报，要么写外部脚本触发，要么依赖某个外部调度器。

Hermes Agent 内置了 cron 调度。你用自然语言描述：”每天早上9点，汇总昨天的 Git 提交并发到 Telegram”，它会自动解析、创建任务、按时执行。

这对于”Agent 作为助手”的场景很重要。真正的助手不只是你叫它才动，是会主动做事情。

3.5 云端部署，不是本地绑定

这点是 Hermes Agent 相比很多同类产品的优势。

它支持六种终端后端：本地、Docker、SSH、Daytona、Singularity、Modal。其中 Modal 和 Daytona 是”无服务器”模式——你的 Agent 环境在云端，空闲时几乎不花钱，有请求时自动唤醒。

这意味着你可以把 Hermes Agent 部署到云端，然后从 Telegram 发消息触发。不在电脑前的时候，Agent 依然在工作。这对于”随时随地操作”的需求很关键。

3.6 多模型，随时切换

Hermes Agent 支持大量 LLM 提供商：

• Nous Portal（官方订阅服务）
• OpenRouter（200+模型）
• Anthropic（Claude 系列）
• OpenAI（GPT 系列）
• Google AI Studio（Gemini）
• 阿里云百炼（DashScope）
• 智谱 AI（GLM）
• Moonshot（Kimi）
• MiniMax
• 小米 MiMo
• NVIDIA NIM
• DeepSeek
• xAI（Grok）
• Hugging Face
• AWS Bedrock
• 还有更多…

切换模型用一个命令：hermes model。不需要改代码，不需要重新部署，运行时切换。

这对于实际使用很重要。不同的任务适合不同的模型，你可能写代码用 Claude，快速问答用 GPT-mini，中文内容用 Qwen。Hermes Agent 让这种切换变得零成本。

四、对 OpenClaw 用户的意义

如果你正在用 OpenClaw，听到 Hermes Agent 可能会想：又一个类似的工具，有必要换吗？

这里有个事实你可能不知道：Hermes Agent 是 OpenClaw 的官方进化版本。

翻 Hermes Agent 的文档，你会发现专门的迁移章节：

1
2
3

## Migrating from OpenClaw

If you're coming from OpenClaw, Hermes can automatically import your settings, memories, skills, and API keys.

迁移命令很简单：

1
2

hermes claw migrate --dry-run    # 先预览会迁移什么
hermes claw migrate              # 执行迁移

迁移内容包括：

• SOUL.md（人格设定）
• 已有技能
• 命令白名单
• 消息平台配置
• API 密钥（Telegram、OpenRouter、OpenAI、Anthropic 等）
• 工作空间说明（AGENTS.md）

这说明 Hermes Agent 的开发团队明确知道 OpenClaw 用户群体，并且专门做了兼容路径。

那为什么要从 OpenClaw 换到 Hermes Agent？几个实际理由：

如果你需要定时任务、云端部署、Agent 学习能力，Hermes Agent 提供了这些 OpenClaw 没有的东西。

五、安装和使用指南

5.1 Mac 用户

Mac 上安装最简单，一行命令：

1

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后：

1
2

source ~/.zshrc   # 或者 source ~/.bashrc
hermes            # 启动

首次运行会引导你配置。按照提示选择 LLM 提供商、设置 API Key 就可以开始使用。

5.2 Windows 用户

Windows 原生不支持，需要通过 WSL2。

先安装 WSL2：

1

wsl --install

然后进入 WSL2 的 Linux 环境，运行和 Mac 一样的安装命令。

这步对不熟悉 Linux 的用户可能有点门槛，但设置好后使用体验和 Mac 一样。

5.3 常用命令

1
2
3
4
5
6
7

hermes              # 启动交互式 CLI
hermes model        # 选择模型提供商和具体模型
hermes tools        # 配置启用的工具
hermes gateway      # 启动消息平台网关（Telegram、Discord 等）
hermes setup        # 完整设置向导
hermes doctor       # 检查配置是否有问题
hermes update       # 更新到最新版本

在对话中使用的斜杠命令：

1
2
3
4
5
6
7

/new              # 开始新对话
/model            # 切换模型
/skills           # 浏览可用技能
/retry            # 重试上一轮
/undo             #撤销上一轮
/compress         # 压缩上下文
/usage            # 查看用量

5.4 配置阿里云百炼

如果你之前用 OpenClaw 配了阿里云百炼的 Coding Plan，在 Hermes Agent 里可以直接用：

1
2
3
4
5

# 设置环境变量
export DASHSCOPE_API_KEY=你的API密钥

# 如果用国内版，额外设置
export DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

或者在 ~/.hermes/.env 文件里写：

1

DASHSCOPE_API_KEY=sk-xxxxxxxx

然后用命令切换提供商：

1
2

hermes model alibaba
hermes model qwen3-coder-plus

六、OpenClaw 用户迁移指南

如果你已经有 OpenClaw 的配置，迁移步骤：

1. 安装 Hermes Agent

1
2

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.zshrc

2. 运行迁移命令

1

hermes setup

Setup 向导会自动检测 ~/.openclaw 目录，提示你是否迁移。

或者任何时候手动运行：

1
2

hermes claw migrate --dry-run    # 预览会迁移什么
hermes claw migrate              # 执行迁移

3. 检查迁移结果

1

hermes doctor    # 检查配置是否正确

4. 开始使用

1

hermes    # 启动 CLI

迁移后，你的 SOUL.md（人格设定）、已有技能、命令白名单、消息平台配置都会保留。API 密钥会自动迁移到 ~/.hermes/.env。

注意：OpenClaw 支持 Telegram、飞书等平台，这些配置会直接迁移。

七、适合什么人用？

如果你的需求是：

• 写代码为主 → 继续用 Claude Code，它在代码理解上更强
• 操作电脑、整理文件 → Hermes Agent 或 OpenClaw 都能胜任
• 重复性任务多 → Hermes Agent，技能系统会帮你省时间
• 需要定时自动化 → Hermes Agent，内置 cron
• 离开电脑时也想用 → Hermes Agent，云端部署 + Telegram
• 飞书/Telegram 是核心场景 → Hermes Agent 或 OpenClaw 都能胜任

如果你已经在用 OpenClaw，不需要立即换。两个工具核心功能重叠约 70%，Hermes Agent 新增的是学习能力、定时任务和云端部署。这些对你有没有价值，看你的实际需求。

但如果你想尝试 Hermes Agent，迁移成本很低。一条命令就能把 OpenClaw 的配置全部导过去，不存在”从头设置”的问题。

八、总结

Hermes Agent 的价值不在”功能更多”，在”设计思路不同”。

大多数 Agent 工具的设计假设是：用户发起对话 → Agent 执行 → 结束。下一次对话从零开始。

Hermes Agent 的设计假设是：Agent 和用户是长期关系，Agent 应该越来越懂用户，而不是每次都从陌生人开始。

这个假设的差异，导致了功能设计的差异：技能自动创建、技能自我改进、Honcho 用户建模、跨会话搜索、定期提醒持久化。

这些功能单独看都不复杂，组合起来形成一个闭环：Agent 做事 → Agent 学习 → Agent 下次做得更好。

这个闭环是 Hermes Agent 和其他 Agent 工具的本质区别。

如果你对”Agent 可以学习和进化”这个概念感兴趣，值得花半小时安装试试。不需要完全替换你现有的工具，先体验一下它的学习机制，看看是否符合你的预期。

九、相关资源

• Hermes Agent GitHub：https://github.com/NousResearch/hermes-agent
• 官方文档：https://hermes-agent.nousresearch.com/docs/
• Skills Hub：https://agentskills.io
• Nous Research Discord：https://discord.gg/NousResearch
• HermesClaw（微信桥接）：https://github.com/AaronWong1999/hermesclaw

LangChain 和 LangGraph 是当下最流行的 Agent 开发框架，但 Anthropic 的 Claude Code 却完全不用它们。这不是傲慢，而是基于技术本质、产品体验、API 特性和工程可控性的四重考量。本文从多个层面剖析 Claude Code 的自研架构选择，以及它用什么技术替代了 LangChain/LangGraph 的能力。

一、先说结论

Claude Code 不用 LangChain/LangGraph，原因有四个：

一句话概括：LangChain/LangGraph 是”通用框架”，Claude Code 是”专用系统”。通用框架追求易用，专用系统追求极致体验。

二、架构层面：为什么放弃 ReAct

2.1 ReAct 模式的根本缺陷

LangChain 和 LangGraph 的核心都是 ReAct 模式（Reasoning + Acting）：

1

思考(Thought) → 行动(Action) → 观察(Observation) → 思考 → ...

这个模式直观易懂，但存在三个根本缺陷：

缺陷一：串行瓶颈

1
2
3
4
5
6
7
8
9
10
11

┌─────────────────────────────────────────────────────────────┐
│                    ReAct 串行流程                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  用户输入 → 等待完整响应 → 解析工具调用 → 执行工具 → 等待 →  │
│            └───────────────────────────────────┘            │
│                        用户感知到的延迟                       │
│                                                             │
│  问题：用户要等模型生成完整响应后才能看到工具执行             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

在 CLI 交互场景中，这种延迟是致命的——用户盯着屏幕等待，不知道发生了什么。

缺陷二：无法利用流式传输

现代 LLM API 都支持流式输出（SSE），但 ReAct 模式下流式的价值被大大削弱：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# LangChain 的 Agent 执行
agent.run("帮我分析这个项目")

# 内部流程：
# 1. LLM 生成完整响应（即使流式，也要等 action 完整）
# 2. OutputParser 解析响应文本
# 3. 提取工具名称和参数
# 4. 执行工具
# 5. 工具结果返回给 LLM
# 6. 重复...

# 流式输出的价值：实时看到模型"在想什么"
# 但工具执行：必须等完整响应后才能开始
# 两者冲突，流式体验被割裂

缺陷三：状态恢复困难

ReAct 模式没有统一的状态表示，每一步都是独立的：

1
2
3
4
5
6
7
8

Step 1: Thought → Action → Observation  (无状态记忆)
Step 2: Thought → Action → Observation  (重新开始)
Step 3: ...

当 API 超时、Token 溢出时：
- LangChain：抛出异常，用户需手动处理
- LangGraph：需要显式定义 checkpoint，复杂度高
- Claude Code：State 对象统一承载，自动恢复

2.2 Claude Code 的替代方案：Async Generator 状态机

Claude Code 用一个 while(true) 循环 + State 赋值 替代 ReAct：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// src/query.ts 核心（简化版）
export async function* query(params: QueryParams): AsyncGenerator<QueryUpdate> {
  let state: State = {
    messages: [...],
    toolUseContext: {...},
    turnCount: 0,
    transition: undefined,
  }

  while (true) {
    // 阶段1: 消息压缩（自动处理 Token 溢出）
    // 阶段2: 流式 API 调用（工具即时执行）
    // 阶段3: 决策点（继续还是结束）
    // 阶段4: 工具编排（并行只读，串行写入）
    // 阶段5: 状态更新
    
    state = next  // 通过赋值驱动循环
    continue
  }
}

核心优势对比：

2.3 流式即时执行：StreamingToolExecutor

Claude Code 的关键创新是 工具在模型生成过程中就开始执行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

┌─────────────────────────────────────────────────────────────┐
│                 Claude Code 流式执行流程                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  模型流式输出：                                              │
│    "我来帮你分析这个项目..."                                 │
│    "首先读取 README..."                                     │
│    [生成 tool_use 块: Read { path: "README.md" }]           │
│                                                             │
│                    ↓ 立即执行                                │
│                                                             │
│  StreamingToolExecutor:                                     │
│    检测到 tool_use → 立即调用 Read 工具                     │
│    工具结果实时返回                                          │
│                                                             │
│  用户感知：                                                  │
│    实时看到模型思考                                          │
│    实时看到工具执行                                          │
│    无需等待完整响应                                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

对比 LangChain：

1
2
3
4
5
6
7

LangChain 流程：
  用户输入 → 等待(模型完整响应) → 解析 → 执行工具 → 等待 → ...
  总延迟 = 模型生成时间 + 解析时间 + 工具执行时间

Claude Code 流程：
  用户输入 → 流式生成(工具即时执行) → 流式输出 → ...
  总延迟 = max(模型生成时间, 工具执行时间)

三、API 层面：原生特性的充分利用

3.1 LangChain 的”框架税”

LangChain 作为通用框架，需要在多种模型 API 之间保持一致性。这意味着：

1
2
3

Anthropic API 特性          → LangChain 抽象层 → 用户代码
                                    ↓
                          被抹平或延迟支持

Anthropic 独有的 API 特性：

3.2 Claude Code 的原生集成

Claude Code 直接使用 Anthropic SDK，充分利用所有原生特性：

示例：Prompt Caching 的利用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// Claude Code 的提示词组装（src/constants/prompts.ts）

// 静态可缓存区域（scope: 'global'）
const systemPrompt = {
  type: 'text',
  text: `
    ## 角色定义
    Claude Code 是一个...
    
    ## 系统规则
    你必须遵守...
    
    ## 工具说明
    以下工具可用...
  `,
  cache_control: { type: 'ephemeral' }  // 缓存标记
}

// 动态不可缓存区域（scope: 'ephemeral'）
const dynamicPrompt = {
  type: 'text',
  text: `
    ## 当前环境
    工作目录: ${cwd}
    
    ## 用户记忆
    ${claudeMdContent}
  `,
  cache_control: { type: 'ephemeral' }  // 独立缓存
}

缓存效果：

• 第一次调用：完整 token 计费
• 后续调用：静态部分缓存命中，降本约 90%

LangChain 也支持 Prompt Caching，但需要用户手动配置，且无法像 Claude Code 这样精细划分缓存边界。

示例：原生 tool_use 块

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// Anthropic API 响应格式
{
  content: [
    { type: 'text', text: '我来帮你...' },
    {
      type: 'tool_use',
      id: 'toolu_01...',
      name: 'Read',
      input: { file_path: '/path/to/file' }
    }
  ]
}

// Claude Code 直接处理
for (const block of response.content) {
  if (block.type === 'tool_use') {
    // 立即执行，无需解析文本
    await executeTool(block.name, block.input)
  }
}

对比 LangChain：

1
2
3
4
5
6
7
8
9
10
11

# LangChain 的工具调用
response = llm.invoke(prompt)

# OutputParser 解析文本
parsed = output_parser.parse(response.content)
# 解析可能失败，格式不固定

if parsed['action']:
    tool_name = parsed['action']['tool']
    tool_input = parsed['action']['input']
    result = tools[tool_name].run(tool_input)

LangChain 需要 OutputParser 解析模型输出的文本，这是脆弱的——模型格式不固定时解析会失败。

四、性能层面：零抽象的流式优先

4.1 LangChain 的抽象层堆叠

LangChain 的抽象层结构：

1
2
3
4
5
6
7
8

用户代码
  → Chain
    → AgentExecutor
      → LLM
        → Memory
          → Tools
            → OutputParser
              → 实际 API 调用

每一层都增加处理开销。对于 Web 应用，这些开销可以忽略；但对于 CLI 交互工具，延迟是致命的。

4.2 Claude Code 的零抽象设计

Claude Code 的结构：

1
2
3
4

用户输入
  → query() AsyncGenerator
    → Anthropic SDK（直接调用）
      → 工具执行（流式即时）

没有中间抽象层，API 响应直接流式传递给用户。

4.3 工具编排的性能优化

Claude Code 的工具编排策略：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

工具调用列表
  │
  ├─ 分类：只读 vs 写入
  │
  ├─ 只读工具 ──→ 并行执行（最多 10 个并发）
  │   ├─ Read      ──→ 同时开始
  │   ├─ Grep      ──→ 同时开始
  │   ├─ Glob      ──→ 同时开始
  │   └─ WebFetch  ──→ 同时开始
  │
  └─ 写入工具 ──→ 串行执行（保证顺序）
      ├─ FileEdit  ──→ 等待上一个完成
      ├─ Write     ──→ 等待上一个完成
      └─ Bash      ──→ 等待上一个完成

LangChain 的工具执行：

1
2
3

# LangChain Agent 默认串行执行
for tool_call in parsed_tool_calls:
    result = tool.run(tool_call.input)  # 一个一个执行

LangChain 需要显式配置并行，且配置复杂；Claude Code 自动分析工具性质，智能编排。

五、可控层面：全栈自研的精准控制

5.1 框架黑盒问题

使用 LangChain/LangGraph 时，你无法精准控制：

5.2 Claude Code 的精准控制

Claude Code 自研每一层，可以精确控制：

控制一：工具执行权限

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// Claude Code 的权限系统（src/utils/permissions）

type PermissionResult = {
  behavior: 'allow' | 'deny' | 'ask'
  message?: string
  suggestions?: string[]
}

// 精细的权限检查
async function checkPermissions(tool, input, context) {
  // 1. deny 规则最高优先级
  if (matchesDenyRule(tool.name)) {
    return { behavior: 'deny', message: 'Blocked by deny rule' }
  }
  
  // 2. 工具自定义检查
  if (tool.checkPermissions) {
    const result = await tool.checkPermissions(input, context)
    if (result.behavior !== 'passthrough') {
      return result
    }
  }
  
  // 3. allow 规则
  if (matchesAllowRule(tool.name, input)) {
    return { behavior: 'allow' }
  }
  
  // 4. 默认询问用户
  return { behavior: 'ask', message: 'Do you want to allow?' }
}

控制二：自动压缩策略

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// Claude Code 的四级压缩（src/query）

// Level 1: Snip — 删除旧消息中的冗余 token
messages = snipMessages(messages)

// Level 2: Micro — 修改已缓存消息的内容
messages = microCompact(messages)

// Level 3: Collapse — 分阶段摘要历史消息
messages = collapseMessages(messages)

// Level 4: Auto Compact — 通过 Claude 生成完整摘要
messages = await autoCompact(messages)

// LangChain 的处理方式：
// messages = messages.slice(-max_tokens)  // 简单截断

控制三：钩子扩展系统

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "security-check.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "FileEdit",
        "hooks": [
          {
            "type": "command",
            "command": "run-tests.sh"
          }
        ]
      }
    ]
  }
}

用户可以在工具执行的任意阶段注入自定义逻辑，LangChain 需要继承类或修改源码才能实现类似功能。

六、能力映射：Claude Code 用什么替代 LangChain/LangGraph

6.1 LangChain 能力 → Claude Code 替代方案

6.2 LangGraph 能力 → Claude Code 替代方案

6.3 核心代码映射

LangChain Agent → Claude Code query()

1
2
3

# LangChain
agent = AgentExecutor.from_agent_and_tools(agent, tools)
result = agent.invoke({"input": "do something"})

1
2
3
4

// Claude Code
for await (const update of query({ messages, tools, systemPrompt })) {
  console.log(update)  // 实时输出
}

LangGraph StateGraph → Claude Code while 循环

1
2
3
4
5
6
7

# LangGraph
graph = StateGraph(AgentState)
graph.add_node("agent", agent_node)
graph.add_node("tool", tool_node)
graph.add_conditional_edges("agent", should_continue, 
    {"continue": "tool", "end": END})
app = graph.compile()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// Claude Code（src/query.ts）
while (true) {
  // 阶段 2: 流式 API 调用
  const response = await callModel(state)
  
  // 阶段 3: 决策点（条件分支）
  if (hasToolUse(response)) {
    // 阶段 4: 工具执行
    const results = await executeTools(response.tool_use_blocks)
    state = { ...state, messages: [...messages, results] }
    continue  // 继续循环
  } else {
    // 结束
    yield finalResult
    return
  }
}

七、什么时候该用 LangChain/LangGraph

Claude Code 的自研架构不是所有人的最优解。它们的选择基于：

1. 顶级工程团队：有能力自研高性能架构
2. 单一模型依赖：只需要支持 Anthropic API
3. 极致体验追求：CLI 交互需要零延迟感知
4. 深度定制需求：权限、压缩、钩子都需要精准控制

如果你不具备这些条件，LangChain/LangGraph 仍然是好选择：

八、总结

Claude Code 不用 LangChain/LangGraph，不是傲慢，而是基于产品定位的理性选择：

1
2
3
4
5
6
7
8
9
10
11

LangChain/LangGraph 定位：通用框架
  → 易用性优先
  → 支持多种模型
  → 抽象层统一
  → 适合快速原型和通用应用

Claude Code 定位：专用系统
  → 性能优先
  → 单一模型极致利用
  → 零抽象流式处理
  → 适合 CLI 交互和专业场景

Claude Code 用什么替代了 LangChain/LangGraph：

核心启示：框架不是必须的，适合自己的才是最好的。LangChain/LangGraph 解决了”怎么快速搭建 Agent”的问题；Claude Code 解决了”怎么搭建极致体验的 Agent”的问题。

参考资料

• Claude Code 源码揭秘：整体架构概览
• 打破 ReAct 迷思：Async Generator 状态机
• 工具系统设计：从定义到执行的七步管道
• Anthropic API 文档
• LangChain 官方文档
• LangGraph 官方文档

2026年3月31日，Anthropic 的 Claude Code 源码意外泄露。这个全球最流行的 AI 编程助手，其背后的架构设计远超外界想象——它不是简单的 Prompt 包装，而是一个精心设计的流式状态机系统。本文将从整体架构视角，为你揭开 Claude Code 的神秘面纱。

当大多数人谈论 AI Agent 架构时，ReAct（Reasoning + Acting）几乎是唯一的答案。但 Claude Code 选择了一条不同的路——Async Generator 状态机。这个设计决策背后有着深刻的思考，它解决了 ReAct 的根本性限制，为流式交互和优雅恢复奠定了基础。

你在手机上打开 Telegram，给 Claude Code 发一条消息，它就开始在你的电脑上工作——这就是 Channel 系统。它打破了 AI 编程助手只能在终端中交互的限制，实现了真正的远程控制。更精妙的是，它有六层访问控制和权限中继机制，确保安全性。

Computer Use 是 Claude Code 最具争议也最强大的能力——AI 可以直接操控你的桌面，点击按钮、输入文字、截图分析。这听起来像科幻电影，但 Claude Code 实现了一个九层安全关卡系统，确保每一步操作都在可控范围内。更关键的是，它通过 Python Bridge 实现跨语言通信，让 TypeScript 代理驱动 Python 执行器。

“对话没有上下文限制”——这是 Claude Code 的一个核心承诺。但它真的能做到吗？答案是：通过四级压缩系统，实现”伪无限对话”。这背后的设计非常精妙：不是简单截断，而是智能地压缩和保留关键信息。

让 Claude Code 跨会话记住你是谁、你偏好什么、项目正在发生什么——这是 Memory 系统的核心目标。它不是简单的聊天记录持久化，而是一个结构化的知识管理系统，通过四种记忆类型、自动提取机制、团队同步等功能，让 AI 真正”理解”你。

AI Agent 执行命令、修改文件、访问网络——这些都是高风险操作。Claude Code 的权限系统设计了一个分层的决策模型：规则 → 模式 → 钩子 → 分类器 → 用户确认。每一层都可以独立中断工具调用，确保安全性。