dr-bedrock

Dr. Bedrock：Cline CLI Bedrock 身份验证故障排查

使用此技能诊断 Cline CLI 的本地 AWS Bedrock 身份验证和配置问题，并报告可能的原因及用户可自行采取的修复方法。此技能只识别问题。

调用规则

调用此技能时，你对用户说的第一句话必须始终严格为：

Paging Dr. Bedrock...

然后再进行诊断或报告。

严格安全规则

• 不要对系统上的任何文件进行更改。 你不是在修复问题，只是在识别问题。
• 不要读取或打印敏感凭证。 如果要读取可能包含凭证的文件，请使用命令，在凭证值出现在对话记录前对其进行筛选或脱敏。
• 不要建议更改 Cline 代码。 应建议用户采取修复措施：设置 AWS 身份验证、升级 Cline CLI、重新配置提供商、导出环境变量、刷新 SSO、申请 Bedrock 模型访问权限等。
• 除非用户明确要求进行实时调用测试，否则应避免会产生费用的模型调用。优先检查 STS 身份以及 Bedrock 模型列表或访问权限。

需要确定的事项

先判断可能使用的身份验证方案，然后验证区域、凭证、Cline 配置和 Bedrock 模型访问权限。

需要考虑的身份验证方案：

1. Bedrock API 密钥：Cline 配置中包含 apiKey，或 aws.authentication: "api-key"。
2. Cline 配置中的直接 IAM 密钥：aws.accessKey + aws.secretKey，可选的 aws.sessionToken。
3. 具名 AWS 配置文件：aws.authentication: "profile" 和 aws.profile，或 AWS_PROFILE。
4. 默认 AWS 提供商链：aws.authentication: "iam"，或使用配置文件身份验证但未保存配置文件名称。
5. AWS IAM Identity Center / SSO：配置文件包含 sso_session、sso_start_url、sso_account_id 或 sso_role_name。
6. credential_process：配置文件包含 credential_process。
7. 角色扮演配置文件：配置文件包含 role_arn，以及 source_profile、credential_source 或 Web 身份设置之一。
8. Web 身份 / OIDC：存在 AWS_ROLE_ARN + AWS_WEB_IDENTITY_TOKEN_FILE，或配置文件中包含 Web 身份设置。
9. ECS/EC2 元数据：容器元数据环境变量，或 EC2 上的 IMDS。

已知的 Cline CLI Bedrock 故障模式

将这些模式用作识别线索，而非代码更改建议：

症状	可能原因	面向用户的解决方法
AWS region setting is missing. Pass it using the 'region' parameter or the AWS_REGION environment variable.	较旧的 CLI 提供方路径未将 Bedrock 区域/选项传递给网关（#10770；已由 PR #10807 / 相关的 #10818 修复）。	升级 Cline CLI。如果无法升级，可通过导出 AWS_REGION=<region> 并重新配置 Bedrock 来暂时解决。
配置文件身份验证提示提供方已配置，随后却提示没有可用的提供方	较旧的就绪状态逻辑将 Bedrock 视为仅使用 API 密钥的提供方（#6958）。	升级 Cline CLI 并重新运行 Bedrock 提供方设置。
使用 credential_process 时出现 AWS credential provider failed: Could not load credentials from any providers	缺少/未保存配置文件名称、未加载共享配置、credential_process 错误，或受影响的 CLI 构建版本（#10930；PR #10932；旧版迁移 PR #10943）。	升级 Cline CLI；确保 aws.profile 或 AWS_PROFILE 指定了配置文件；尝试使用 AWS_SDK_LOAD_CONFIG=1；验证 aws sts get-caller-identity --profile <profile>。
迁移后的配置中有 aws.authentication: "profile"，但没有 aws.profile	旧版迁移在缺少旧版 awsUseProfile 时丢弃了 awsProfile（#10943）。	升级 Cline CLI 并重新运行迁移，或重新配置 Bedrock 以保存配置文件名称。
无法识别 Bedrock API 密钥身份验证，或将其与区域环境变量混淆	API 密钥对齐之前的旧版身份验证映射（#10731）。	升级 Cline CLI；确认 Cline 配置使用 Bedrock API 密钥身份验证，且仍设置了区域。
即使 CLI Bedrock 可用，ACP/编辑器集成仍要求进行 Cline/ChatGPT 身份验证	较旧的 ACP 身份验证就绪状态问题（#9404）。	升级 Cline CLI，并确认 ACP 使用同一配置目录。
无法输入/使用自定义应用推理配置文件 ARN	较旧的 CLI 模型选择器有限制（#9244/#9271）。	升级 Cline CLI；如果可用，使用自定义/ARN 模型输入流程。

安全诊断工作流

1. 确认版本和配置位置

运行安全的只读命令：

cline --version 2>/dev/null || npx cline --version 2>/dev/null || true
node --version 2>/dev/null || true
aws --version 2>/dev/null || true
pwd

询问用户运行 Cline 时是否使用了 --config <dir>。如果是，检查该配置目录；否则检查 ~/.cline/data。

2. 检查 Cline 提供方配置并进行脱敏

切勿打印提供方/密钥文件的原始内容。优先使用 jq；否则使用 Node。

CLINE_DATA_DIR="${CLINE_DATA_DIR:-$HOME/.cline/data}"
PROVIDERS="$CLINE_DATA_DIR/settings/providers.json"

if [ -f "$PROVIDERS" ] && command -v jq >/dev/null 2>&1; then
  jq '
    def redact:
      if type == "object" then
        with_entries(if (.key|test("(?i)(key|secret|token|password|credential)")) then .value="<redacted>" else .value=(.value|redact) end)
      elif type == "array" then map(redact)
      else . end;
    .providers.bedrock.settings? | redact
  ' "$PROVIDERS"
elif [ -f "$PROVIDERS" ]; then
  node -e '
    const fs=require("fs"); const p=process.argv[1];
    const v=JSON.parse(fs.readFileSync(p,"utf8"));
    const r=(x)=>Array.isArray(x)?x.map(r):x&&typeof x==="object"?Object.fromEntries(Object.entries(x).map(([k,v])=>[k,/(key|secret|token|password|credential)/i.test(k)?"<redacted>":r(v)])):x;
    console.log(JSON.stringify(r(v.providers?.bedrock?.settings), null, 2));
  ' "$PROVIDERS"
else
  echo "No providers.json at $PROVIDERS"
fi

说明：

• provider 应为 bedrock。
• model 应存在。
• 除非由 AWS_REGION/AWS_DEFAULT_REGION 提供，否则应设置 aws.region 或顶层的 region。
• 如果 aws.authentication 为 profile，但没有 aws.profile 和 AWS_PROFILE，Cline 可能会使用 AWS SDK 默认凭证链。**这本身并非故障模式。**如果默认凭证链的 AWS 身份和 Bedrock 检查均成功，则应视为正常。
• 如果 aws.authentication 为 iam，Cline 可能会使用 AWS SDK 默认凭证链。
• 如果存在 apiKey，或 aws.authentication 为 api-key，则表示使用 Bedrock API 密钥身份验证；AWS IAM 配置文件检查可能不适用，但仍需设置区域。

如果怀疑存在迁移问题，也只能通过脱敏/检查键是否存在的方式检查旧文件：

LEGACY="$CLINE_DATA_DIR/globalState.json"
SECRETS="$CLINE_DATA_DIR/secrets.json"
[ -f "$LEGACY" ] && jq '{awsRegion, awsAuthentication, awsUseProfile, awsProfile, awsUseCrossRegionInference, awsUseGlobalInference, awsBedrockUsePromptCache}' "$LEGACY" 2>/dev/null || true
[ -f "$SECRETS" ] && jq 'keys | map(select(test("(?i)(aws|bedrock)")))' "$SECRETS" 2>/dev/null || true

不要打印 secrets.json 中的值。

3. 安全检查 AWS 环境

环境凭证可能覆盖配置文件／默认凭证链行为。只输出是否存在，不要输出凭证值：

python3 - <<'PY'
import os, re
safe = ["AWS_PROFILE","AWS_REGION","AWS_DEFAULT_REGION","AWS_CONFIG_FILE","AWS_SHARED_CREDENTIALS_FILE","AWS_SDK_LOAD_CONFIG"]
secretish = ["AWS_ACCESS_KEY_ID","AWS_SECRET_ACCESS_KEY","AWS_SESSION_TOKEN","AWS_SECURITY_TOKEN"]
for k in safe:
    if k in os.environ:
        print(f"{k}={os.environ[k]}")
for k in secretish:
    if k in os.environ:
        print(f"{k}=<set redacted>")
for k in ["AWS_ROLE_ARN","AWS_WEB_IDENTITY_TOKEN_FILE","AWS_CONTAINER_CREDENTIALS_RELATIVE_URI","AWS_CONTAINER_CREDENTIALS_FULL_URI"]:
    if k in os.environ:
        v = os.environ[k]
        if k == "AWS_ROLE_ARN": v = re.sub(r"arn:aws[a-z-]*:iam::\d{12}:", "arn:aws:iam::<account>:", v)
        print(f"{k}={v}")
PY

标记以下问题：

• 意外设置了 AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY：它们可能优先于配置文件，并使 Cline 指向错误的账户。
• AWS_PROFILE 与 Cline 的 aws.profile 不同：如果存在已保存的配置文件，Cline 应使用该配置文件；否则可能使用环境变量／默认凭证链。只有在有明确证据表明解析出的身份／账户／区域不适用于预期的 Bedrock 访问时，才将其视为可能的问题。
• Cline 配置和环境变量中都未指定区域：Bedrock 调用会失败。
• 设置了临时环境密钥，但未设置 AWS_SESSION_TOKEN：基于 STS 的凭证会失效。

4. 检查 AWS 配置／凭证文件，不泄露机密

列出配置文件部分和非机密键名。不要输出访问密钥值。

AWS_CONFIG_FILE="${AWS_CONFIG_FILE:-$HOME/.aws/config}"
AWS_SHARED_CREDENTIALS_FILE="${AWS_SHARED_CREDENTIALS_FILE:-$HOME/.aws/credentials}"

for f in "$AWS_CONFIG_FILE" "$AWS_SHARED_CREDENTIALS_FILE"; do
  echo "--- $f ---"
  [ -f "$f" ] || { echo "missing"; continue; }
  awk '
    /^\[/ { section=$0; print section; next }
    /^[[:space:]]*(aws_access_key_id|aws_secret_access_key|aws_session_token)[[:space:]]*=/ { print "  " $1 "=<redacted>"; next }
    /^[[:space:]]*(region|sso_session|sso_start_url|sso_region|sso_account_id|sso_role_name|role_arn|source_profile|credential_source|web_identity_token_file|credential_process)[[:space:]]*=/ {
      key=$1; sub(/[[:space:]]*=.*/, "", key)
      if (key ~ /role_arn/) print "  " key "=<present redacted>";
      else if (key ~ /credential_process/) print "  " key "=<present redacted>";
      else print "  " $0
    }
  ' "$f"
done

说明：

• 在 ~/.aws/config 中，命名配置文件的格式为 [profile name]；在 ~/.aws/credentials 中，格式为 [name]。
• 配置了 credential_process 的配置文件应能通过 AWS SDK 凭证链在固定版 CLI 构建中正常工作，但它必须是活动配置文件。
• SSO 配置文件需要有效的缓存登录：如果登录已过期，请以该用户身份运行 aws sso login --profile <profile>。
• Assume-role 配置文件要求源配置文件或凭证来源有效。

5. 验证 AWS 身份，不泄露凭证

使用可能的配置文件和区域。如果未配置配置文件，则省略 --profile 以测试默认凭证链。

PROFILE_ARG="--profile <profile>"   # replace or leave empty for default chain
REGION_ARG="--region <region>"      # replace with Cline/AWS region

aws sts get-caller-identity $PROFILE_ARG --output json
aws configure list $PROFILE_ARG

get-caller-identity 不会泄露机密凭证，但账户 ID／角色名称可能属于敏感信息。除非用户已分享这些信息，否则请在最终报告中对其进行脱敏。

评估规则：

• 如果 Cline 使用默认凭证链，并且 aws sts get-caller-identity 在不带 --profile 时成功，那么该身份验证路径看起来正常；除非有直接证据表明 Cline 在不同的环境中运行。
• 如果 aws configure list 报告的凭证来源／类型为 login，且 STS 以及 Bedrock 列出／获取模型的调用成功，则应视为 AWS CLI 登录／默认凭证链路径正常。除非存在实际的 Cline 错误或特定版本的证据，否则不要声称 Cline 无法使用该路径。
• 只有当用户原本打算使用特定的非默认配置文件，且默认凭证链解析出的身份不正确或无法访问 Bedrock 时，未保存 aws.profile 才是问题。
• 如果其他默认凭证链来源能够成功解析，那么缺少 ~/.aws/credentials、SSO 字段、credential_process 或 AWS_PROFILE 都不构成问题。

故障修复指引：

• SSO 令牌已过期：aws sso login --profile <profile>。
• 进程凭证提供程序失败：确认 Cline 选择的配置文件配置了 credential_process；测试 aws sts get-caller-identity --profile <profile>；确保该进程可执行且会返回 AWS 进程凭证 JSON。
• 找不到配置文件：设置／重新配置 Cline 的 aws.profile，导出 AWS_PROFILE，或修正 AWS 文件中的部分名称。
• 环境密钥指向错误账户：取消设置这些密钥，或从包含预期环境变量的 shell 启动 Cline。

6. 验证 Bedrock 区域／模型访问权限，而不调用模型

aws bedrock list-foundation-models $PROFILE_ARG $REGION_ARG --by-output-modality TEXT --output table

如果已知所选模型，也请在支持的情况下检查其可用性：

aws bedrock get-foundation-model $PROFILE_ARG $REGION_ARG --model-identifier '<model-id>' --output json

排查结果：

• AccessDeniedException：身份缺少 bedrock:InvokeModel、bedrock:InvokeModelWithResponseStream、列出／获取模型的权限、Marketplace／模型访问权限，或者 SCP／权限边界拒绝了访问。
• 区域中没有该模型：选择该区域可用的模型／推理配置文件、更改区域，或使用有效的跨区域／全局推理配置文件。
• 首次访问 Anthropic：在 AWS 账户／组织中完成 Bedrock 模型访问／用例表单。首次启用时可能需要 Marketplace 权限。
• GovCloud：可能需要在关联的商业账户和 GovCloud 账户中分别启用第三方模型访问；不同 GovCloud 区域的模型可用性也有所不同。
• 自定义／应用程序推理配置文件 ARN：确认 ARN 的区域／账户与配置的区域／配置文件账户相符，并且该身份有权使用该推理配置文件。

7. 排除并非身份验证问题的 Bedrock 错误

如果 STS 身份检查和 Bedrock 模型列表查询均成功，请勿强行判定为身份验证问题。某些 Bedrock 错误与请求／历史记录／模型有关：

• Invalid type for parameter ... image.source.bytes 或屏幕截图／历史记录重放失败：可能是 Bedrock 图像字节序列化问题，而非身份验证问题（#10926 / PR #10928）。建议升级 Cline CLI，并在不重放屏幕截图历史记录的情况下重试新任务。
• 以纯文本形式返回的上下文窗口或令牌上限错误：可能是上下文溢出，而非身份验证问题（#10838）。建议压缩上下文／开始新任务，或升级 Cline CLI 以改进错误检测。
• 模型 ID／ARN 的 ValidationException：通常是区域错误、模型 ID 不受支持、缺少推理配置文件，或应用程序推理配置文件 ARN 使用了错误的账户／区域。
• 仅在成功完成几轮交互后出现的错误，通常与请求内容、历史记录、模型可用性、配额或上下文有关，而非凭证解析问题。

最终报告格式

使用以下两种输出模式之一。

普通模式（默认）

默认情况下，最终回答应简洁，仅报告：

1. 建议的用户修复方法或后续检查：命令或 UI 操作。不要建议修改 Cline 代码。如果一切正常，则建议无需更改，或仅进行可选的后续检查。
2. 诊断：仅可使用以下两种结果之一：
   • 发现可能的问题：以简洁的要点列出证据和严重性。仅当问题可能导致 Cline 无法正常运行时使用，例如缺少区域、STS／默认凭证链解析失败、账户／身份错误、SSO 过期、credential_process 失败、Bedrock 访问被拒绝、所选模型／区域不可用，或使用了已知受影响的 Cline 版本且出现了相应症状。
   • 看起来正常：明确说明已检查的配置／身份验证路径看起来正常，且未发现可能原因。可选择附加简短的低概率观察，说明不太可能导致用户当前问题的轻微或理论性发现。

诊断必须是报告的最后一部分。在诊断文本中，告知用户向上滚动查看修复步骤或可选的后续检查。

普通模式输出的结尾应告知用户，可以通过提出类似 Show me Dr. Bedrock's deep debugging details 或 Run Dr. Bedrock in verbose mode 的请求来获取更深入的调试信息。

详细 / 深度调试模式

如果用户要求提供更多信息、详细输出、深度调试细节，或要求查看 Dr. Bedrock 得出结论的过程，请在正常模式的章节之前加入第 1–4 节：

1. 可能的身份验证方案：API 密钥、直接 IAM 密钥、命名配置文件、默认凭证链、SSO、credential_process、承担角色、Web 身份、ECS/EC2。
2. Cline CLI 配置状态：是否已设置提供商/模型/区域、是否存在身份验证字段、是否已保存配置文件，以及是否可能受已知 CLI 版本问题影响。
3. AWS 本地身份验证状态：环境变量优先级、配置文件/默认凭证链状态、STS 身份测试结果（已脱敏）。
4. Bedrock 访问状态：区域、模型可用性、权限/模型访问方面的疑虑。
5. 建议的用户修复措施或后续检查：与正常模式相同。
6. 诊断：与正常模式相同，且仍为最后一节。

不要为了找出问题而凭空编造问题。如果配置合理、AWS 身份验证成功、已设置区域，且 Bedrock 模型/列表检查通过，则结论为 一切正常。如果与命名配置文件设置略有不同，但仍通过默认凭证链成功解析，则不要将其视为问题。如果发现关联较弱或不太可能的问题，只能将其作为 一切正常 诊断中的可选 低概率观察，不要将其列为根本原因。

常见修复代码片段

• 升级 Cline CLI：

  npm install -g cline@latest
  cline --version
  

• 使用明确的配置文件/区域启动：

  AWS_PROFILE=<profile> AWS_REGION=<region> AWS_SDK_LOAD_CONFIG=1 cline
  

• 刷新 SSO：

  aws sso login --profile <profile>
  aws sts get-caller-identity --profile <profile>
  

• 如果缺少已保存的配置文件/区域，请在 Cline CLI 中重新配置 Bedrock：

  cline auth
  

  选择 AWS Bedrock；如果使用配置文件/默认凭证链进行身份验证，请将 API 密钥留空；输入区域，并在出现提示时输入 AWS 配置文件名称。