claude-agent-sdk 异常退出的几种原因及解决方法

1 以编程方式调用 Claude Code 的 API 的方法

@anthropic-ai/claude-agent-sdk 是 Claude Code 的一个 Node.js SDK，支持以编程方式调用 Claude Code 的 API。其基本用法如下：

import { query } from "@anthropic-ai/claude-agent-sdk";

// Simple one-shot query
for await (const message of query({
  prompt: "Explain the authentication flow",
  cwd: "/path/to/project",
  options: {
    maxTurns: 1,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

// Continue conversation with session management
for await (const message of query({
  prompt: "Now explain the authorization process",
  options: {
    continue: true,
    maxTurns: 1
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

2 Claude Code 异常退出原因及解决方法

在实践使用过程中，在 MacOS、alpine Docker 镜像等不同环境下多次遇到如下错误：

• Failed to spawn Claude Code process: spawn node ENOENT
• Claude Code process exited with code 1

通过搜索与分析排查最终得以解决。以下是我们遇到会导致这些异常退出的几种场景及解决办法。

技巧提示：通过设置 DEBUG=* 环境变量，可以查看 Claude Code 的运行日志，从而更清晰地了解异常退出的原因。

2.1 cwd 参数指定的路径不存在

当指定的 cwd 参数指定的路径不存在时，Claude Code 会抛出异常退出。

2.2 Docker 镜像下缺少 bash 环境

alpine 镜像中默认 bash 环境。但我在 allowedTools 中指定了 bash 相关工具，从而导致异常退出。示例：

query({
    maxTurns: 1,
    maxThinkingTokens: 0,
    model: this.model,
    //   permissionMode: 'default', // 'bypassPermissions',
    allowedTools: [
    'Bash',
    'BashOutput',
    'KillBash'
    ],
})

这可以在设置了 DEBUG=* 环境变量后，通过查看日志，找到异常退出的原因。报错信息参考：

IDEBUG] >>>>> getPluginSkillS CALLED <<<<<

Error: No suitable shell found. claude Cll requires a Posix shell environment. Please ensure you have a valid shell installed and the SHElL environment variable set.

解决办法可以是移除这些工具，或者安装 bash 环境：在 Dockerfile 中添加上一行 RUN apk add bash 即可。

2.3 设置了 bypassPermissions 权限

在 Docker 环境下，当设置了 permissionMode: 'bypassPermissions' 时会要求 sudo 权限，从而导致异常退出。

简单的解决办法是改为 permissionMode: 'default'。

3 扩展参考

• https://docs.claude.com/en/api/agent-sdk/streaming-vs-single-mode
• https://github.com/anthropics/claude-code/issues/4383