n8n에 외부 API 연결하기: 내 API 키로 실행하는 워크플로

n8n AI Agent에서 OpenAI 호환 외부 API를 사용하려면 자신의 API 키와 제공업체의 Base URL로 OpenAI 자격 증명(credential)을 만든 뒤, OpenAI Chat Model 하위 노드에서 선택하면 됩니다. 단, 제공업체가 워크플로에서 실제로 사용하는 모델과 기능을 지원해야 합니다. 자격 증명 연결 테스트가 통과했다는 것만으로는 충분하지 않습니다.

이 글에서는 가상의 결제 문의를 분류하고, 읽기 전용 조회 도구를 호출한 다음, 결과를 검증하는 자격 증명 없는 워크플로 JSON을 제공합니다. 예시 API 제공업체인 Ofox가 이 글의 발행 주체이기도 합니다. 워크플로는 별도의 Agent Builder가 아닌 기존 AI Agent를 사용합니다. 환불을 실행하거나 메시지를 보내는 기능은 없습니다.

2026년 10월 20일, Ofox의 deepseek/deepseek-v4.1-flash-1017을 사용해 n8n 2.43.8 서버 CLI에서 실행했습니다. 수정 후 실행에서는 도구가 정상 응답했고 출력 검증도 통과했습니다. 그전에 도구가 실패했는데도 성공한 것처럼 보이는 실행을 발견했습니다. 다운로드 파일에 검증 노드를 넣은 이유입니다. 이는 작은 규모의 합성 데이터 통합 테스트이며, 모든 모델이나 n8n 버전에서의 운영 안정성을 입증하지는 않습니다.

가져오기 전에 준비할 것

편집 권한이 있는 n8n 인스턴스, 선택한 모델을 사용할 수 있고 잔액이 충분한 Ofox 계정, 테스트 입력을 해당 제공업체에 전송할 수 있는 권한이 필요합니다. 첫 워크플로는 운영 환경과 분리하세요. 이번 실행 환경은 로컬 자체 호스팅 설치본이었으며, n8n Cloud나 Agent Builder는 테스트하지 않았습니다.

모델 ID를 복사하기 전에 현재 Ofox 모델 카탈로그를 확인하세요. 카탈로그에 모델이 있다는 것은 제공 대상으로 안내된다는 뜻이지, 해당 계정에서 도구 호출이 성공한다는 증거는 아닙니다. 다른 모델을 선택하면 아래의 통과 조건을 다시 확인해야 합니다. OpenAI 호환이라는 설명이 모든 OpenAI 엔드포인트, 내장 도구, 응답 형식을 구현했다는 뜻은 아닙니다.

가져올 워크플로에는 노드 다섯 개가 있습니다.

Agent는 Chat Model 연결로 모델에, Tool 연결로 Code Tool에 연결됩니다. 일반 실행 경로는 Manual Trigger → Classify demo ticket → Validate result입니다. 연결 유형이 서로 다르므로 모든 선을 일반 main 연결로 만들면 같은 워크플로가 되지 않습니다.

템플릿을 가져오고 내 자격 증명 연결하기

1. 워크플로 JSON을 내려받아 가져오기 전에 내용을 확인하세요. 프롬프트와 JavaScript는 있지만 API 키, 자격 증명 참조, 핀으로 고정한 실행 결과(pinData), 실제 고객 데이터는 없습니다.
2. 빈 n8n 워크플로에서 워크플로 메뉴를 열고 Import from File을 선택한 뒤 다운로드한 JSON을 지정하세요. n8n은 URL에서 가져오기도 지원합니다. 가능한 방법은 내보내기·가져오기 문서에서 확인할 수 있습니다.
3. Ofox Chat Model을 여세요. 자격 증명 필드에서 OpenAI 자격 증명을 새로 만드세요. 이 유형은 호환 인터페이스를 가리키며, 반드시 OpenAI가 발급한 키를 써야 한다는 뜻은 아닙니다.
4. API Keys에서 Ofox 키를 만들거나 복사하세요. API Key에 붙여넣고 Base URL을 https://api.ofox.ai/v1로 설정하세요. 이 예시에서는 Organization ID를 비워 둡니다. 자격 증명을 저장한 뒤 모델 노드에서 선택하세요.
5. 계정에서 계속 사용할 수 있는 경우에만 모델 ID를 deepseek/deepseek-v4.1-flash-1017로 유지하세요. UI에 모델 선택 방식이 있다면 표시 이름 대신 정확한 ID를 사용하세요. 변경 후 저장된 값도 확인하세요.
6. 이 템플릿에서는 Use Responses API를 끈 상태로 두세요. 테스트한 경로는 Chat Completions입니다. 첫 확인에서는 Maximum Number of Tokens를 2048, Timeout을 60000밀리초, Max Retries를 0, Agent의 Max Iterations를 3으로 유지하세요.

Base URL 입력 위치를 보여 주기 위해 이전 n8n 자격 증명 안내에 사용한 영어 UI 스크린샷을 재사용했습니다. 10월 20일 실행 화면이나 이 워크플로의 통과 증거는 아닙니다. 항목 이름은 n8n 버전에 따라 다를 수 있으며, 이번 테스트의 근거는 아래에서 설명하는 서버 CLI 실행 데이터입니다.

API 루트를 입력하는 필드에 /chat/completions까지 포함한 전체 작업 URL을 넣거나 /v1을 두 번 붙이지 마세요. 자격 증명 테스트는 초록색인데 워크플로가 404를 반환한다면 별도의 n8n 엔드포인트 오류 해결 글을 참고하세요. 이 글은 같은 경로 진단을 반복하는 대신, 하나의 작업 전체와 출력 검증을 제공합니다.

OpenAI Chat Model 문서는 Chat Completions와 Responses를 구분합니다. 여기서 Responses를 끄는 것은 테스트한 경로를 선택하기 위한 설정이지, 스키마 오류나 403, 지원되지 않는 도구를 모두 해결하는 방법은 아닙니다. 이 템플릿의 일반 로컬 Code Tool도 OpenAI의 내장 웹 검색이나 파일 검색 도구와는 다릅니다.

문의를 실행하고 두 가지 결과 확인하기

제공하는 입력은 의도적으로 작게 구성했습니다.

Request ID: DEMO-1020
Message: I was charged USD 19.50 twice.
I have not supplied a payment ID.

에이전트는 먼저 request_id를 DEMO-1020으로 지정해 lookup_demo_ticket을 호출해야 합니다. 이 도구는 실제 계정을 조회하지 않습니다. JavaScript에서 다음과 같은 고정된 로컬 테스트 데이터를 반환합니다.

{"request_id":"DEMO-1020","payment_id_present":false}

이 도구를 넣은 이유는 모델이 도구를 선택하고, n8n이 실행하고, 모델이 그 결과를 받은 뒤 답하는 전체 왕복 과정을 테스트하기 위해서입니다. 운영용 워크플로에서는 이 고정 데이터를 적절한 권한을 갖춘 실제 조회로 바꿔야 합니다. 이 데모만으로 임의의 CRM이나 결제 커넥터가 작동한다고 판단할 수는 없습니다.

워크플로를 비활성 상태로 유지한 채 Execute workflow를 선택해 수동 실행하세요. 가져오기와 이번 실행은 서버 CLI에서 검증했습니다. 편집기 사용 설명은 n8n 공식 문서의 가져오기 방식과 저장된 노드 설정을 바탕으로 작성했으며, 별도로 Cloud UI에서 테스트한 결과가 아닙니다.

Classify demo ticket을 확인하세요. 출력은 정확히 다음 필드와 값을 가진 JSON이어야 합니다.

{
  "request_id": "DEMO-1020",
  "category": "billing",
  "amount": 19.5,
  "currency": "USD",
  "action": "request_payment_id"
}

중간 단계도 확인해야 합니다. 도구 이름이 일치하는 것만으로는 부족합니다. 도구 반환값인 observation에 테스트 데이터의 요청 ID와 payment_id_present: false가 포함되어야 하며 오류가 없어야 합니다. 다운로드 파일은 마지막 노드에서 이 근거를 확인할 수 있도록 Return Intermediate Steps를 켜 두었습니다.

마지막으로 Validate result를 여세요. 통과한 실행은 같은 업무 필드에 validated: true와 tool_verified: true를 추가해 반환합니다. 불필요한 추가 필드, 잘못된 action, 유효하지 않은 JSON, 누락된 도구 호출, 실패한 도구 반환값 중 하나라도 있으면 노드에서 오류를 발생시킵니다. 이후 단계에서 이메일을 보내거나 환불 요청을 실행하는 기능은 없습니다.

이 검증기는 지금 사용하는 테스트 데이터 한 건의 정답을 알고 있도록 만들었습니다. 문의 텍스트만 바꾸고 정확한 값을 대조하는 조건을 그대로 두면 실패합니다. 응용하기 전에 새 사례의 예상 규칙을 작성하고, 필드와 타입 검증을 유지하며, 알 수 없는 ID와 조회 데이터가 없는 경우를 명시적으로 테스트하세요. 워크플로를 초록색으로 만들기 위해 문법상 유효한 JSON이면 무엇이든 통과시키지 마세요.

첫 실행에서 드러나지 않았던 도구 실패

첫 로컬 실행에서 모델은 도구를 호출했지만, 도구 반환값에는 다음 오류가 기록되었습니다.

Received tool input did not match expected schema
Unrecognized key(s) in object: 'toolCallId'

그런데도 전체 워크플로는 성공으로 끝났고 예상한 분류 결과를 생성했습니다. 원래 검증기는 도구를 호출했는지만 확인하고, 사용 가능한 데이터가 반환되었는지는 확인하지 않았습니다. 따라서 이 실행은 통합 테스트 실패로 판정했습니다.

수정한 테스트용 Code Tool의 입력 스키마는 문자열 request_id를 필수로 요구하되 추가 속성을 허용합니다. 코드는 허용 목록에 있는 요청 ID만 사용해 고정 데이터를 반환하며, 입력을 다른 서비스에 전달하거나 쓰기 작업을 하지 않습니다. 이렇게 해서 이번 설치 환경에서 관찰된 추가 필드를 수용했습니다. 최종 출력 스키마는 여전히 정확히 일치해야 하고, 검증기는 이제 도구 반환값도 확인합니다. 이 오류를 감추려고 운영 작업의 엄격한 검증을 없애서는 안 됩니다. 데이터를 변경하는 도구라면 노드와 런타임의 동작을 조사하고 명확한 입력 규약을 정의한 뒤 진행하세요.

수정 후 실행에서는 모델을 두 번 호출했습니다. 첫 호출에서 도구 사용을 요청하고, 정상 조회가 끝난 뒤 두 번째 호출에서 분류 결과를 반환했습니다. n8n이 기록한 두 호출의 합계는 입력 토큰 1,019개와 출력 토큰 101개였습니다. 실패로 판정한 첫 실행에서는 세 번 호출했습니다. 이는 기록된 사용량이지 청구 내역이 아니며, 이후 실행에서도 같은 양을 사용한다는 보장도 아닙니다.

별도의 로컬 테스트로 검증기가 다섯 가지 실패 사례를 거부하는지 확인했습니다. 유효하지 않은 JSON, 추가 필드, 잘못된 action, 도구 호출 누락, 도구 오류입니다. 이 테스트에는 합성 검증 입력을 사용했으며, 실제 제공업체 장애나 요청 한도 초과, 결제 실패를 일으키지는 않았습니다. 또한 toolCallId 관찰 결과는 Agent Builder에서 별도로 보고된 get_environment 스키마 문제를 재현한 것이 아닙니다.

내 API 키를 쓰면 비용은 어디서 청구될까?

비용은 다음과 같이 나누어 확인해야 합니다.

Ofox 자격 증명을 사용한다면 해당 모델에 대한 Ofox 계정의 요청 기록과 청구 내역을 확인하세요. n8n Gateway 크레딧으로 표시된 잔액이 Ofox 키의 사용료를 지불한다고 생각하면 안 됩니다. 반대로 제공업체 잔액을 충전해도 n8n Gateway 크레딧이나 Assistant 크레딧이 충전되지는 않습니다. Gateway 크레딧 문서는 이러한 잔액과 사용자가 직접 관리하는 자격 증명 사용 방식을 구분합니다.

이 Code Tool은 로컬 테스트 코드이므로 외부 도구 서비스에 요청하지 않습니다. 실제 검색이나 스크래핑 도구를 붙이면 별도 비용이 생길 수 있습니다. 두 번의 테스트 실행에서 확인했듯, 워크플로 한 번을 실행하는 동안 에이전트가 모델을 여러 차례 호출할 수도 있습니다.

예산을 계산할 때는 과금 대상 사용량이 발생한 재시도와 실패 요청까지 포함해 모든 호출의 입력, 출력, 별도로 보고되는 캐시 항목을 합산하세요. 정확한 모델·제공업체·계정별 요율을 적용하고 외부 도구 비용을 더해야 합니다. 텍스트 모델의 출력 요율을 모든 토큰에 적용하거나 n8n 실행 한 번이 API 요청 한 번과 같다고 가정하지 마세요. 이 글은 Ofox 요금을 제시하거나 실측 비용 절감을 주장하지 않습니다.

합성 데이터와 작은 예산으로 시작하세요. 오류를 이해하기 전에는 재시도를 꺼 두고, 이후 오류 유형에 맞게 횟수가 제한된 정책을 적용하세요. 재시도와 에이전트 반복 횟수를 함께 늘리면 잘못된 키나 지원되지 않는 스키마는 고치지 못한 채 호출 수만 늘어날 수 있습니다.

가져온 워크플로가 실패할 때

DeepSeek 라우팅이나 서비스 문제라면 DeepSeek API 오류와 대체 모델 전환 안내로 이어서 확인하세요. 대체 경로에서도 필요한 프로토콜, 도구, 결과 규약이 유지되어야 합니다. 모델 이름만 바꿨다고 전환이 검증되는 것은 아닙니다.

실제 작업을 연결하기 전에 고정 테스트 데이터에만 맞춘 가정을 제거하고, 필요한 데이터에 대한 접근 권한을 확인하세요. 쓰기 작업에는 별도의 권한 확인과 중복 방지 검사를 유지해야 합니다. 첫 목표는 작지만 분명합니다. 자신의 자격 증명으로 모델과 도구의 왕복 호출을 마치고, 결과가 명시적인 검사를 통과하도록 만드는 것입니다. 이 단계가 작동하면 Ofox 인증 문서와 계정 요청 기록을 활용해 같은 확인 절차를 실제 워크플로에 적용하세요.