> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agencyhandy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AgencyHandy 워크스페이스에 커스텀 도메인 연결

> DNS 등록 기관에서 CNAME 레코드를 추가하여 자체 서브도메인 (예: portal.yourcompany.com)을 AgencyHandy에 연결하세요 — 코딩이 필요 없습니다.

기본적으로 AgencyHandy 워크스페이스는 `agencyhandy.com` 아래의 서브도메인으로 접근할 수 있습니다. 커스텀 도메인을 연결하면 기본 URL을 자체 브랜드 주소(예: `portal.youragency.com`)로 대체할 수 있어 클라이언트가 처음 방문하는 페이지부터 브랜드를 강화하는 원활하고 전문적인 경험을 제공합니다.

<Note>
  커스텀 도메인은 **슈퍼 관리자**와 **관리자**만 구성할 수 있습니다. 설정을 완료하려면 도메인을 소유하고 있어야 하며 등록 기관의 DNS 설정에 접근할 수 있어야 합니다.
</Note>

***

## 작동 방식

AgencyHandy에 커스텀 도메인을 추가하면 플랫폼이 **CNAME 레코드**를 제공합니다. 해당 레코드를 등록 기관(GoDaddy, Namecheap, Cloudflare 등)의 도메인 DNS 설정에 추가하면 DNS가 전파된 후 AgencyHandy가 연결을 확인합니다.

***

## 단계별 설정

<Steps>
  <Step title="커스텀 도메인 설정 열기">
    AgencyHandy 계정에 로그인하세요. 왼쪽 사이드바에서 **워크스페이스 구성**으로 이동한 다음 **커스텀 도메인**을 클릭하세요.
  </Step>

  <Step title="커스텀 도메인 추가">
    **+ 커스텀 도메인 추가** 버튼을 클릭하세요. 표시되는 입력란에 사용할 서브도메인을 입력하세요 — 예: `portal.youragency.com`.

    <Warning>
      서브도메인으로 `www`를 사용하지 **마세요** (예: `www.youragency.com` 사용 금지). `www` 접두사는 구성 충돌을 일으키고 성공적인 인증을 방해합니다. `portal`, `client`, `app`, `hub`와 같은 다른 서브도메인을 사용하세요.
    </Warning>
  </Step>

  <Step title="CNAME 레코드 정보 복사">
    도메인을 제출하면 AgencyHandy가 추가해야 할 DNS 레코드를 표시합니다:

    | 필드     | 값                    |
    | ------ | -------------------- |
    | **유형** | CNAME                |
    | **이름** | 서브도메인 (예: `portal`)  |
    | **값**  | AgencyHandy가 제공하는 대상 |

    이 값들을 신중하게 복사하세요 — 다음 단계에서 필요합니다.
  </Step>

  <Step title="DNS 등록 기관에서 CNAME 레코드 추가">
    도메인 등록 기관 대시보드(예: GoDaddy, Namecheap, Cloudflare)에 로그인하세요. 도메인의 DNS 관리 섹션으로 이동하여 AgencyHandy에서 복사한 유형, 이름, 값을 사용하여 CNAME 레코드를 추가하세요.

    Cloudflare에 대한 등록 기관별 안내는 아래를 참고하세요.
  </Step>

  <Step title="AgencyHandy에서 도메인 저장">
    AgencyHandy로 돌아가 **도메인 저장**을 클릭하세요. DNS가 전파되는 동안 상태가 처음에 **연결 안 됨**으로 표시될 수 있습니다 — 이는 정상적인 상황입니다.
  </Step>

  <Step title="DNS 전파 대기 및 확인">
    DNS 변경 사항은 등록 기관과 TTL 설정에 따라 몇 분에서 **최대 48시간**까지 전 세계적으로 전파되는 데 걸릴 수 있습니다. **새로 고침**을 주기적으로 클릭하여 연결 상태를 확인하세요.

    전파가 완료되면 상태가 **연결됨** ✅으로 변경됩니다.
  </Step>
</Steps>

<Warning>
  DNS 전파는 최대 **48시간**이 소요될 수 있습니다. 48시간 후에도 도메인이 **연결 안 됨**으로 표시되면 CNAME 레코드가 올바른지, 동일한 서브도메인에 충돌하는 DNS 레코드가 없는지 다시 확인하세요.
</Warning>

***

## Cloudflare 전용 안내

도메인이 Cloudflare를 통해 관리되는 경우 올바르게 구성해야 하는 중요한 설정이 있습니다:

<Steps>
  <Step title="Cloudflare에 로그인하고 도메인 선택">
    [Cloudflare 대시보드](https://dash.cloudflare.com)를 열고 AgencyHandy에 연결하려는 도메인을 클릭하세요.
  </Step>

  <Step title="DNS 설정으로 이동">
    도메인 설정 패널의 상단 내비게이션에서 **DNS** 탭을 클릭하세요.
  </Step>

  <Step title="CNAME 레코드 추가">
    **+ 레코드 추가**를 클릭하고 다음 필드를 입력하세요:

    * **유형:** CNAME
    * **이름:** 서브도메인 (예: `portal`)
    * **대상/콘텐츠:** AgencyHandy가 제공한 값
    * **TTL:** 초기 설정 시 **2분** (또는 가장 낮은 사용 가능한 옵션)으로 설정
  </Step>

  <Step title="Cloudflare 프록시 비활성화 (중요)">
    **프록시 상태** 열에서 토글이 **DNS만** (클라우드 아이콘이 주황색이 아닌 회색으로 표시)으로 설정되어 있는지 확인하세요.

    <Warning>
      Cloudflare 프록시가 **활성화**된 경우 (주황색 클라우드 아이콘), CNAME 레코드가 올바르게 확인되지 않아 AgencyHandy가 도메인을 인증할 수 없습니다. 연결이 작동하려면 **DNS만**으로 설정해야 합니다.
    </Warning>
  </Step>

  <Step title="레코드 저장">
    모든 값의 정확성을 검토하고 **저장**을 클릭하세요.
  </Step>
</Steps>

<Tip>
  [dnschecker.org](https://dnschecker.org)를 사용하여 전 세계 다양한 지역에서 CNAME 레코드의 전파를 모니터링하세요. AgencyHandy가 연결을 확인하기 전에 모든 지역에서 녹색 체크 표시를 확인하세요.
</Tip>

***

## 연결 상태 모니터링

저장 후 AgencyHandy의 **워크스페이스 구성 → 커스텀 도메인**으로 돌아가 상태를 확인하세요:

| 상태         | 의미                                             |
| ---------- | ---------------------------------------------- |
| **연결 안 됨** | DNS 레코드가 아직 전파되지 않았거나 오류가 포함되어 있음              |
| **연결됨**    | 도메인이 인증되어 활성화됨 — 클라이언트가 커스텀 URL로 워크스페이스에 접근 가능 |

***

## 커스텀 도메인 업데이트 또는 삭제

* **도메인 업데이트:** 기존 항목을 삭제하고 위의 동일한 설정 단계를 사용하여 새 도메인을 추가하세요.
* **도메인 삭제:** 커스텀 도메인 패널에서 도메인 옆의 **삭제** 버튼을 클릭하고 삭제를 확인하세요. 워크스페이스가 기본 AgencyHandy URL로 되돌아갑니다. 언제든지 도메인을 다시 추가할 수 있습니다.

***

## 중요 사항

* **루트 도메인이 아닌 서브도메인 사용:** AgencyHandy 커스텀 도메인에는 루트/에이펙스 도메인(예: `youragency.com`)이 아닌 서브도메인(예: `portal.youragency.com`)이 필요합니다.
* **`www` 피하기:** `www` 서브도메인은 인증 중에 문제를 일으킬 수 있습니다. 대신 커스텀 서브도메인 이름을 사용하세요.
* **정확한 레코드 필요:** AgencyHandy에 표시된 대로 정확히 CNAME 유형, 이름, 값을 입력하세요. 오타나 누락된 문자는 연결을 방해합니다.
* **Cloudflare 프록시는 반드시 끄기:** AgencyHandy 커스텀 도메인 인증을 위해 Cloudflare 레코드는 항상 **DNS만**으로 설정하세요.
* **관리자 전용 접근:** 커스텀 도메인 설정 추가, 수정, 삭제는 슈퍼 관리자와 관리자만 가능합니다.