자격 증명

Credential Center는 OpenAI API 키, Slack Webhook, Stripe Secret, 내부 API 인증 헤더 등 모든 외부 시스템 키의 통합 저장소입니다. 모두 여기에 배치됩니다. 플랫폼은 AES-256-GCM을 사용하여 데이터베이스를 암호화하며 YAML 내보내기, 로그 및 감사 이벤트에 처음부터 끝까지 표시되지 않습니다.

Credential Center에 가야 하는 이유는 무엇입니까?

YAML에서 직접 키를 편리하게 작성하려는 경우 세 가지 유형의 문제가 있습니다.

1. 누출 — YAML 내보내기, Git 제출 및 AI 보조 비교 미리보기는 모두 일반 텍스트 키를 가져옵니다.
2. 회전할 수 없습니다. — 키가 취소되면 각 YAML을 수동으로 수정해야 하는데 이는 놓치기 매우 쉽습니다.
3. 감사할 수 없음 — 문제가 발생하면 어떤 Key를 어떤 실행에 사용했는지 알 수 없습니다.

Credential Center는 YAML에 "참조"만 남기고 실제 값은 런타임 시 해당 단계에 주입됩니다.

자격 증명 만들기

1. 왼쪽의 "Credential Management" → 오른쪽 상단의 "New Credential" 입니다.
2. 작성:
   • 이름 — YAML에서 인용에 사용되는 모두 소문자 + 밑줄 짧은 식별자입니다. 예: openai_main、slack_webhook_url。
   • 유형 — api_key / oauth_token / bot_token / webhook_secret / generic。类型决定平台在 UI 上怎么展示它，对解析逻辑影响不大。
   • 가치 — 한번 쓴 내용은 다시 읽을 수 없습니다.
   • 네임스페이스 — 개인/팀(Pro+ 패키지에서 팀에 속한 경우)
   • 설명(선택사항) — 자신이나 팀 구성원을 위해 작성됩니다(예: "OpenAI 프로젝트 X의 Prod 키").
3. 저장합니다. 플랫폼은 즉시 데이터베이스를 암호화하고 목록에 다음과 같이 표시합니다. ****abc3 마지막 몇 자리 숫자의 형태입니다.

YAML에서 자격 증명 인용

에이전트용: 공급자 필드

agents:
  writer:
    preset: writer
    overrides:
      model: gpt-4.1-mini
      provider: openai_main          # 凭据中心里的凭据名

provider: openai_main 에이전트에게 "LLM을 디버깅할 때 자격 증명 센터에서 openai_main이라는 키를 사용하세요."라고 말합니다. 플랫폼은 네임스페이스 순서로 구문 분석하고 첫 번째 적중이 적용됩니다.

코드 단계에서는 자격 증명 목록을 사용합니다.

- id: charge_customer
  type: code
  language: node
  credentials:
    - stripe_secret                  # 声明需要这两个凭据
    - internal_api_token
  code: |
    const stripe = require('stripe')(process.env.STRIPE_SECRET);
    const internal = await fetch('https://api.mycompany.com/invoice', {
      headers: { Authorization: 'Bearer ' + process.env.INTERNAL_API_TOKEN }
    });
    // ...

설명:

• 자격 증명: 목록에 명시적으로 선언된 항목만 읽을 수 있으며 다른 단계로 유출되지 않습니다.
• 구문 분석 후 자격 증명 이름 openai_main → env var OPENAI_MAIN (SCREAMING_SNAKE_CASE) 환경 변수로 주입됩니다.
• 선언된 항목만 process.env에서 볼 수 있습니다. 자격 증명 센터의 다른 자격 증명은 이 코드에 표시되지 않습니다.

변수 표현식에서 참조됨

일부 필드(예: sub_workflow의 입력)는 직접 입력될 수 있습니다. {{credentials.xxx}} 인용문:

- id: notify
  type: sub_workflow
  module: dingyue-module-slack-deliver
  inputs:
    slack_webhook_url: "{{credentials.slack_webhook_url}}"
    message_text: "..."

또한 네임스페이스 순서로 구문 분석됩니다. 자격 증명 값은 현재 단계가 실행 중일 때만 적용되며 실행 스냅샷에 기록되지 않습니다.

네임스페이스 및 구문 분석 순서

동일한 이름이 다른 네임스페이스에 존재할 수 있습니다. 실행 시, 첫 번째 히트, 첫 번째 사용 순으로 검색하세요.

1. 개인 네임스페이스 — 직접 구축한 경우에는 본인만 참조할 수 있습니다.
2. 팀 네임스페이스 — 팀에서 공유하며 모든 구성원이 참조할 수 있습니다. Team Admin만 생성/삭제할 수 있습니다.

공급자: 여러 키를 다양한 비즈니스에 바인딩

동일한 LLM 공급자(예: OpenAI)에 여러 키(테스트/프로덕션/팀/프로젝트 X/프로젝트 Y)가 있는 경우 다음을 수행할 수 있습니다.

1. 자격 증명 센터의 각 키에 대해 하나의 키를 생성합니다(이름 구분: openai_test / openai_prod_a / openai_prod_b).
2. Agent의 overrides.provider 필드는 사용할 항목을 지정합니다.
3. 다양한 워크플로는 다양한 공급자를 사용할 수 있지만 에이전트 정의를 복사하지 않고도 동일한 사전 설정을 사용할 수 있습니다.

agents:
  expensive:
    preset: universal
    overrides:
      model: claude-opus-4-7
      provider: anthropic_team_budget     # 团队有预算的那把

  cheap:
    preset: universal
    overrides:
      model: deepseek-v3-5
      provider: deepseek_personal         # 个人账户的

Claude Code / Codex 구독 자격 증명

AI 도우미 또는 워크플로 에이전트가 구독 할당량 모델을 사용하는 경우 "내 자격 증명"에서 해당 공급자를 생성하십시오.

• claude_code_oauth — Claude Code로 로그인하여 얻은 OAuth Token입니다.
• codex_subscription — Codex CLI 로그인으로 생성된 auth.json의 전체 텍스트입니다.

이러한 값은 에이전트/AI 보조 구성에 저장되지 않으며 런타임 시 해당 CLI에 일시적으로만 삽입됩니다.

순환 및 해지

일반 회전

1. 자격 증명 센터 → 자격 증명을 클릭하고 → "값 업데이트"를 클릭합니다.
2. 저장할 새 값을 입력하세요.
3. 이후에 시작된 새로운 실행은 새 값을 사용합니다. 지속적인 실행은 시작 시 캐시된 이전 값을 계속 사용합니다.

긴급해지

내 자격 증명이 유출된 것으로 의심되어 즉시 비활성화하고 싶습니다.

1. 자격 증명 센터 → "삭제"에서 자격 증명을 클릭합니다.
2. 이를 참조하는 모든 단계는 다음에 실행될 때 credential_not_found로 인해 즉시 실패합니다.
3. 그런 다음 업스트림 공급자(OpenAI/Anthropic...)로 이동하여 실제 키를 취소합니다.

감사

참조된 자격 증명 확인의 각 생성/업데이트/삭제/실패에 대해 감사 로그가 기록됩니다. 관리자는 "감사 로그" 페이지로 이동하여 credential_*을 event_type별로 필터링하여 볼 수 있습니다.

로그 폭발을 방지하기 위해 참조 구문 분석이 성공하면 로그가 기록되지 않습니다. 그러나 "이 실행으로 구문 분석된 자격 증명"에 대한 메타데이터는 각 실행의 세부 정보에 표시됩니다.

FAQ

대신 환경 변수를 사용할 수 있나요?

기술적으로는 가능하지만(팀의 자체 배포 환경 변수를 통해) 권장되지는 않습니다.

• 환경 변수는 프로세스 수준 전역 변수이며 모든 코드 단계에서 process.env로 읽을 수 있습니다. Credential Center는 귀하가 선언한 몇 가지 항목만 주입합니다.
• 환경 변수 교체는 서비스를 다시 시작해야 하며 자격 증명 센터의 변경 사항은 즉시 적용됩니다.
• 환경 변수는 감사되지 않습니다.

동료가 내 개인 네임스페이스 자격 증명을 볼 수 있나요?

아니요. 팀 관리자도 자격 증명의 존재(목록)만 볼 수 있지만 값을 보거나 자체 워크플로에서 참조할 수 없습니다. 런타임 구문 분석에서는 누락됩니다.

OAuth 새로고침으로 무엇을 해야 하나요?

주류 OAuth 공급자(Google / GitHub / Slack / Notion)의 경우: Refresh_token이 자격 증명 센터에 배치되고 access_token 플랫폼이 자동으로 새로 고쳐집니다. 다른 공급자의 경우 자격 증명에 장기간 유효한 토큰을 넣거나 새로 고침 코드 단계를 직접 작성해야 합니다.

다음 단계

• BYOK · 자체 LLM Key 사용 — 가장 일반적인 자격 증명 시나리오: 자체 LLM 공급자 키 구성
• 변수 및 표현식 — {{credentials.xxx}} 표현식의 추가 세부사항
• 권한 및 역할 — 팀 네임스페이스에 관리자 권한이 어떻게 할당되나요?