OpenClaw와 Amazon Bedrock 연동: 5분 만에 설정하기

클라우드 환경에서 AI 모델을 관리하다 보면 API 키를 일일이 발급받고 관리하는 일이 꽤 번거롭게 느껴질 때가 많아요. 특히 보안이 중요한 엔터프라이즈 환경에서는 더더욱 그렇죠. AWS를 이미 사용하고 있다면, 별도의 API 키 없이 기존의 IAM 권한만으로 Amazon Bedrock의 강력한 모델들을 OpenClaw에서 바로 사용할 수 있습니다.

OpenClaw는 pi‑ai의 Bedrock Converse 스트리밍 프로바이더를 통해 Amazon Bedrock 모델을 지원해요. Bedrock 인증은 API 키가 아니라 AWS SDK default credential chain을 사용하기 때문에 보안상으로도 아주 안전합니다.

pi-ai 지원 사항

Provider: amazon-bedrock
API: bedrock-converse-stream
Auth: AWS credentials (환경 변수, 공유 설정 파일, 또는 인스턴스 역할)
Region: AWS_REGION 또는 AWS_DEFAULT_REGION (기본값: us-east-1)

자동 모델 검색

AWS credentials가 감지되면, OpenClaw는 streaming과 text output을 지원하는 Bedrock 모델을 자동으로 찾아줍니다. 이 검색 기능은 bedrock:ListFoundationModels 권한을 사용하며, 결과는 기본적으로 1시간 동안 캐시돼요.

설정 옵션은 models.bedrockDiscovery 아래에서 관리할 수 있습니다.

{
  models: {
    bedrockDiscovery: {
      enabled: true,
      region: "us-east-1",
      providerFilter: ["anthropic", "amazon"],
      refreshInterval: 3600,
      defaultContextWindow: 32000,
      defaultMaxTokens: 4096,
    },
  },
}

참고할 점:

AWS credentials가 있으면 enabled는 기본적으로 true가 됩니다.
region은 AWS_REGION이나 AWS_DEFAULT_REGION을 먼저 확인하고, 없으면 us-east-1을 사용해요.
providerFilter를 통해 특정 Bedrock 프로바이더(예: anthropic)만 골라낼 수 있습니다.
refreshInterval은 초 단위이며, 0으로 설정하면 캐시를 사용하지 않아요.
defaultContextWindow(기본값: 32000)와 defaultMaxTokens(기본값: 4096)는 검색된 모델에 적용됩니다. 모델의 한계를 정확히 알고 있다면 이 값을 직접 수정해 보세요.

온보딩

먼저 gateway host에서 AWS credentials를 사용할 수 있는지 확인해 주세요.

export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"
# Optional:
export AWS_SESSION_TOKEN="..."
export AWS_PROFILE="your-profile"
# Optional (Bedrock API key/bearer token):
export AWS_BEARER_TOKEN_BEDROCK="..."

설정 파일에 Bedrock 프로바이더와 모델을 추가합니다. apiKey는 따로 필요 없어요.

{
  models: {
    providers: {
      "amazon-bedrock": {
        baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
        api: "bedrock-converse-stream",
        auth: "aws-sdk",
        models: [
          {
            id: "us.anthropic.claude-opus-4-6-v1:0",
            name: "Claude Opus 4.6 (Bedrock)",
            reasoning: true,
            input: ["text", "image"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0" },
    },
  },
}

EC2 인스턴스 역할

IAM 역할이 부여된 EC2 인스턴스에서 OpenClaw를 실행하면, AWS SDK가 인스턴스 메타데이터 서비스(IMDS)를 통해 자동으로 인증을 처리합니다. 다만, 현재 OpenClaw의 인증 감지 로직은 환경 변수만 체크하고 IMDS 자격 증명은 직접 확인하지 않아요.

해결 방법: AWS credentials를 사용할 수 있다는 신호를 주기 위해 AWS_PROFILE=default를 설정해 주세요. 실제 인증은 IMDS를 통해 인스턴스 역할로 처리됩니다.

# Add to ~/.bashrc or your shell profile
export AWS_PROFILE=default
export AWS_REGION=us-east-1

EC2 인스턴스 역할에 필요한 IAM 권한은 다음과 같습니다.

bedrock:InvokeModel
bedrock:InvokeModelWithResponseStream
bedrock:ListFoundationModels (자동 검색용)

또는 AmazonBedrockFullAccess 관리형 정책을 연결해도 됩니다.

빠른 설정 (AWS 경로)

# 1. Create IAM role and instance profile
aws iam create-role --role-name EC2-Bedrock-Access \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "ec2.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

aws iam attach-role-policy --role-name EC2-Bedrock-Access \
  --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess

aws iam create-instance-profile --instance-profile-name EC2-Bedrock-Access
aws iam add-role-to-instance-profile \
  --instance-profile-name EC2-Bedrock-Access \
  --role-name EC2-Bedrock-Access

# 2. Attach to your EC2 instance
aws ec2 associate-iam-instance-profile \
  --instance-id i-xxxxx \
  --iam-instance-profile Name=EC2-Bedrock-Access

# 3. On the EC2 instance, enable discovery
openclaw config set models.bedrockDiscovery.enabled true
openclaw config set models.bedrockDiscovery.region us-east-1

# 4. Set the workaround env vars
echo 'export AWS_PROFILE=default' >> ~/.bashrc
echo 'export AWS_REGION=us-east-1' >> ~/.bashrc
source ~/.bashrc

# 5. Verify models are discovered
openclaw models list

참고 사항

Bedrock을 사용하려면 해당 AWS 계정 및 리전에서 model access가 활성화되어 있어야 합니다.
자동 검색 기능을 쓰려면 bedrock:ListFoundationModels 권한이 꼭 필요해요.
프로파일을 사용한다면 gateway host에 AWS_PROFILE을 설정해 주세요.
OpenClaw는 AWS_BEARER_TOKEN_BEDROCK, AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY, AWS_PROFILE, 그리고 기본 AWS SDK 체인 순서로 자격 증명을 확인합니다.
Reasoning 지원 여부는 모델마다 다릅니다. 최신 기능은 Bedrock 모델 카드를 확인해 보세요.
관리형 키 흐름을 선호한다면, Bedrock 앞에 OpenAI 호환 프록시를 두고 OpenAI 프로바이더로 설정하는 방법도 있습니다.

가드레일 (Guardrails) 설정

amazon-bedrock 플러그인 설정에 guardrail 객체를 추가하면 모든 Bedrock 모델 호출에 Amazon Bedrock Guardrails를 적용할 수 있습니다. 가드레일을 통해 콘텐츠 필터링, 주제 거부, 단어 필터링, 민감 정보 필터링 등을 수행할 수 있어요.

{
  plugins: {
    entries: {
      "amazon-bedrock": {
        config: {
          guardrail: {
            guardrailIdentifier: "abc123", // guardrail ID or full ARN
            guardrailVersion: "1", // version number or "DRAFT"
            streamProcessingMode: "sync", // optional: "sync" or "async"
            trace: "enabled", // optional: "enabled", "disabled", or "enabled_full"
          },
        },
      },
    },
  },
}

guardrailIdentifier (필수): 가드레일 ID(예: abc123) 또는 전체 ARN(예: arn:aws:bedrock:us-east-1:123456789012:guardrail/abc123)을 입력합니다.
guardrailVersion (필수): 사용할 배포 버전을 지정하거나, 작업 중인 초안을 쓰려면 "DRAFT"를 입력하세요.
streamProcessingMode (선택 사항): 스트리밍 중에 가드레일 평가를 동기("sync")로 할지 비동기("async")로 할지 결정합니다. 생략하면 Bedrock의 기본 동작을 따릅니다.
trace (선택 사항): API 응답에 가드레일 추적 출력을 포함할지 설정합니다. 디버깅 시에는 "enabled"나 "enabled_full"을 쓰고, 운영 환경에서는 생략하거나 "disabled"로 두세요.

Gateway에서 사용하는 IAM 주체는 표준 호출 권한 외에 bedrock:ApplyGuardrail 권한도 가지고 있어야 합니다.

다음 단계

설정 중에 도움이 필요하신가요? AI Setup Assistant에게 물어보세요!

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.