빠른 시작

Ankole 배포 방식

프라이빗 Ankole deployment instance는 control plane 하나와 하나 이상의 Agent Computer Worker로 구성됩니다. control plane은 지속적인 도메인 상태와 감독을 소유하는 관리 플랫폼입니다. Worker는 Agent의 실행 환경을 제공하고 Agent의 작업 컴퓨터 역할을 합니다.

하나의 Worker는 여러 Agent를 서비스할 수 있습니다. 금융 등 엄격한 격리가 필요한 환경에서는 각 Agent에 전용 Worker를 주세요. 작업 컴퓨터는 여러 인턴이 공유하거나 한 명의 동료에게 할당할 수 있습니다.

각 instance에는 PostgreSQL과 영속 디스크 저장소도 필요합니다. 단일 호스트 배포는 로컬 또는 가상 디스크를 사용할 수 있습니다. Kubernetes 배포에는 ReadWriteMany를 지원하는 NFS 또는 다른 공유 볼륨이 필요합니다.

이 가이드에서 사용하는 용어

이 페이지는 Ankole 사용자 문서와 인터페이스에 쓰이는 용어를 정의합니다. 괄호 안의 이름은 타사 플랫폼, configuration 필드, API와 일치합니다. 이후 섹션은 짧은 형식을 사용합니다.

정식 용어	의미	짧은 형식
Private deployment instance	엔터프라이즈가 배포하고 관리하는 하나의 완전한 Ankole 시스템	Instance
Principal	Ankole에서 identity와 권한을 가질 수 있는 사람, Agent 또는 시스템 서비스	Principal
Identity Provider (IdP)	Console SSO를 제공하고 직원, 연락처, 조직 구조를 동기화하는 외부 identity 소스	IdP
Chat platform	Slack, Teams, Lark/Feishu, DingTalk, WeCom, Telegram, Discord, LINE, WhatsApp 또는 메일함 같은 외부 대화 플랫폼	Platform
Channel Provider	메시지를 받고 Agent 답변을 보내는 하나의 채팅 앱 또는 bot 설정	Channel Provider
Signal Routing Rule (Signal Binding)	시그널 소스에서 Agent로 메시지나 이벤트를 보내는 규칙	Routing rule
LLM Provider	모델 서비스 endpoint, 자격 증명, 사용 가능한 모델을 저장하는 설정	LLM Provider
Background Agent Jobs profile (internal key: `coding`)	Background Agent Jobs용 AIGateway provider와 모델을 선택합니다. 일반 대화는 코드 양으로 이것을 선택하지 않습니다	Background Agent Jobs

Agent가 setup을 완료하게 하기

Codex, Claude Code 또는 터미널을 조작할 수 있는 다른 Agent에 이 prompt를 보낼 수 있습니다:

https://ankole.agentbull.com/ko-KR/docs/quickstart/index.md 를 사용하여 프라이빗 Ankole 배포 인스턴스를 배포하고 구성하도록 도와주세요. 먼저 내 환경을 검사하고 Docker Compose, Kubernetes, 또는 소스로부터의 설치 중 하나를 추천해 주세요. 그런 다음 Identity Provider(IdP), LLM Provider, Agent, Channel Provider, Signal Routing Rule(Signal Binding) 설정을 도와주세요. 내가 IdP와 IM 플랫폼을 지정하지 않았다면 어떤 identity 소스와 채팅 플랫폼을 사용할지 물어봐 주세요. 저를 대신해 선택하지 마세요. chat이나 명령 출력에 secrets를 노출하지 마세요. 내가 선택한 IM에서 실제 Agent 답변을 받았을 때만 작업을 완료하세요.

1. Ankole 배포

단일 호스트에는 Docker Compose를, 엔터프라이즈 배포에는 Kubernetes를 사용하세요. 개발과 디버깅은 소스에서 설치합니다.

대부분의 팀에 가장 좋은 시작점입니다. Docker가 설치된 Linux, macOS, Windows 호스트 한 대로 PostgreSQL, control plane, Agent Computer Worker 한 개, Caddy HTTPS를 실행할 수 있습니다.

시작하기 전에

Linux amd64 또는 arm64 컨테이너를 실행할 수 있는 Linux, macOS, Windows 호스트
Compose 플러그인이 포함된 Docker Engine, 또는 Docker Desktop
영구 디스크, DNS 이름, 그리고 80 포트와 443 포트

기본 설정

Docker Compose로 설치하기

provider API key는 이 배포 파일에 넣지 마세요. 사인인 후 Console에서 추가하게 됩니다.

배포 패키지 가져오기

bash

git clone https://github.com/AgentBull/ankole.git
cd ankole/tools/deploy/docker-compose
cp .env.example .env
chmod 600 .env

독립된 secrets 세 개 생성하기

이 명령을 복사해서 실행하세요. 그런 다음 출력 전체를 .env에 붙여 넣으세요.

bash

printf '%s\n' \
  '# PostgreSQL database password' \
  'POSTGRES_PASSWORD=$(openssl rand -hex 32)' \
  '' \
  '# ANKOLE master encryption key' \
  'ANKOLE_SECRET_BASE=$(openssl rand -hex 32)' \
  '' \
  '# Authentication key shared by the ANKOLE control plane and Agent Workers' \
  'ANKOLE_RUNTIME_FABRIC_WORKER_AUTH_KEY=$(openssl rand -hex 32)'

03
공개 호스트 설정하기
ANKOLE_HOST를 이 호스트를 가리키는 DNS 이름으로 설정하세요. ACME_EMAIL에는 인증서 안내를 받을 수 있는 주소를 설정하세요.
ANKOLE_HOST
ankole.example.com
사용자와 provider callback이 사용할 HTTPS 호스트입니다.
ACME_EMAIL
ops@example.com
Caddy 인증서 관리를 위한 연락 주소입니다.
04
스택 시작 및 확인하기
Compose는 PostgreSQL을 기다렸다가 migration을 실행하고 Worker key를 저장한 뒤, control plane, Worker, Caddy를 시작합니다.
bash
```
docker compose pull
docker compose up -d
docker compose ps
```
05
첫 설정 열기
https://<ANKOLE_HOST>/setup을 열고 활성화 코드를 입력하세요.
bash
```
docker compose logs control-plane | grep "SETUP ACTIVATION CODE"
```

2. identity provider를 먼저 설정

Ankole은 엔터프라이즈 내부의 프라이빗 배포를 위해 설계되었습니다. 각 엔터프라이즈는 instance 하나를 운영합니다. 그 instance 안에서 Agent, 직원, 시스템 서비스는 Principal로 표현되고, 권한 모듈이 그들의 권한을 관리합니다.

Hermes Agent와 OpenClaw처럼 Ankole도 채팅 채널에 연결됩니다. 또한 엔터프라이즈 identity 소스에 연결하여 직원, 디렉터리 연락처, 조직 구조를 동기화합니다. 채널을 설정하기 전에 Identity Provider(IdP)를 먼저 설정하세요.

설정	제어 대상	설정 위치
Identity Provider (IdP)	Console SSO와 엔터프라이즈 디렉터리에서 동기화된 직원, 연락처, 조직 구조, 권한 그룹	먼저 `/setup`, 그다음 Console → Identity Providers
Channel Provider	메시지를 받고 Agent 답변을 보내는 IM 앱 또는 bot	Console → Signal Routing

identity 소스와 채팅 채널은 서로 다른 플랫폼을 사용할 수 있습니다. 직원은 Google Workspace로 로그인하고 Slack에서 Agent와 대화할 수 있습니다. Entra ID가 identity를 제공하고 Lark, Slack, DingTalk, Teams, WeCom이 대화를 운반할 수 있습니다.

IdP setup 완료

엔터프라이즈가 사용하는 identity 소스를 선택하세요. 각 tab은 provider console에서 시작해 첫 로그인과 디렉터리 동기화로 끝납니다.

adapter를 처음 활성화했다면 첫 로그인 후 control plane을 재시작하세요. 이 재시작이 디렉터리 연결과 Graph subscription 같은 플러그인 백그라운드 작업을 시작합니다.

Console 사인인과 workspace 멤버 및 사용자 그룹 동기화에 Slack 앱 하나를 사용합니다. 기본 설정에는 OAuth 클라이언트, Bot Token, App Token이 필요합니다.

시작하기 전에

Slack 앱을 만들고 설치할 수 있는 workspace 관리자
Ankole용 공개 HTTPS 주소
첫 사인인에 사용할 workspace 멤버 계정

기본 설정

Slack IdP 설정하기

01
Ankole에서 callback URL 복사하기
https://<ANKOLE_HOST>/setup을 열고 활성화 코드를 입력하세요. 플러그인 페이지에서 Slack Adapter를 선택하고 저장한 다음, Slack을 선택하세요.
Configuration ID(Provider ID)를 slack-main으로 유지하세요. Copy를 사용해 로그인 callback URL을 복사하세요. 이 URL을 직접 입력하거나 바꾸지 마세요.
02
Slack 앱 만들기
Slack API Your Apps를 열고 Create New App → From scratch를 선택하세요. 앱 이름을 입력하고 직원이 속한 workspace를 선택하세요.
Basic Information → App Credentials를 열고 Client ID와 Client Secret을 복사하세요.
Slack Your Apps 열기
03
로그인 callback 등록하기
OAuth & Permissions → Redirect URLs를 열고 Add New Redirect URL을 선택한 다음, Ankole에서 가져온 전체 URL을 붙여 넣고 저장하세요.
Ankole은 기본적으로 openid, profile, email 사인인 scopes를 요청합니다. 이를 chat bot scopes로 바꾸지 마세요.
Slack 사인인 가이드
04
디렉터리 액세스를 부여하고 Bot Token을 받습니다
OAuth & Permissions에서 Bot Token Scopes 아래에 아래의 세 scope를 추가합니다. 그런 다음 Install to Workspace를 선택하고 설치를 승인합니다.
- users:read
  구성원 프로필 읽기
- users:read.email
  구성원 이메일 주소 읽기
- usergroups:read
  사용자 그룹과 그 구성원 읽기
설치 후 Bot User OAuth Token을 복사합니다. 이 token은 반드시 xoxb-로 시작해야 합니다. scope를 변경할 때마다 앱을 다시 설치합니다.
05
App Token을 받고 Socket Mode를 사용 설정합니다
Basic Information → App-Level Tokens를 엽니다. Generate Token and Scopes를 선택하고 아래의 scope를 추가한 다음, 생성된 xapp- token을 복사합니다. 그런 다음 Socket Mode를 열고 Enable Socket Mode를 켭니다.
- connections:write
  App Token이 Socket Mode 연결을 열 수 있게 합니다
06
디렉터리 이벤트를 구독합니다
Event Subscriptions를 열고 이벤트를 사용 설정합니다. Subscribe to bot events 아래에 아래의 다섯 이벤트를 각각 추가합니다.
- team_join
  구성원이 workspace에 가입함
- user_change
  구성원 프로필이 변경됨
- subteam_created
  사용자 그룹이 생성됨
- subteam_updated
  사용자 그룹이 변경됨
- subteam_members_changed
  사용자 그룹 멤버십이 변경됨
Slack Socket Mode 가이드
07
Ankole에 Slack 값을 입력합니다
Sync directory와 Sync directory changes를 켠 상태로 유지합니다. Validate configuration을 선택하고 로그인합니다. 그런 다음 Slack 인증을 완료합니다.
- Client ID: Basic Information의 Client ID
- Client Secret: 같은 페이지의 Client Secret
- Workspace ID: 선택 사항입니다. Slack 웹 URL에서 /client/ 뒤의 T… 값을 입력하면 로그인할 workspace를 미리 선택할 수 있습니다. 디렉터리 동기화를 제한하지는 않습니다
- Bot User OAuth Token: xoxb- token
- App-Level Token: xapp- token
08
로그인과 최초 동기화를 확인합니다
Slack이 Ankole로 돌아오면 이 사용자가 첫 번째 루트 관리자가 됩니다. Console → Identity Providers를 열고 slack-main을 선택한 다음 Run full sync를 선택합니다.
동기화가 끝나면 Console → Principals와 Principal groups에서 workspace 구성원과 Slack 사용자 그룹을 확인합니다.

3. LLM Provider 추가 및 Agent 생성

Agent model profile은 모델 참조를 저장하므로 LLM Provider를 먼저 추가하세요. Console에 로그인합니다. Providers → New provider를 열고 provider 종류를 선택한 다음 안정적인 Provider ID를 지정하고 endpoint와 credential 필드를 입력한 뒤 저장합니다.

Provider 자격 증명은 control plane에서 암호화된 채 유지됩니다. deployment 환경 파일이나 Agent 파일에 넣지 마세요.

Agents → New Agent를 엽니다. Agent에 안정적인 UID, 명확한 표시 이름, 그리고 무엇을 담당하고 무엇이 수용 가능한 결과인지 말해주는 mission을 지정하세요.

그런 다음 model profile을 설정합니다:

Profile	첫 실행 용도
`primary`	주 추론 모델
`light`	짧고 잦은 작업
`heavy`	어려운 종합

Agent가 실행되려면 세 가지가 모두 필요합니다. 첫 대화에서는 검증된 provider와 모델을 세 profile 모두에 바인딩할 수 있습니다. 엔드투엔드 경로가 동작한 뒤에만 분리하세요.

4. 채팅 채널 연결 및 시그널 라우팅 규칙 생성

Console에서 채팅 플랫폼의 Control Plane Plugin을 활성화한 다음, 해당 플랫폼에서 bot 또는 앱을 만드세요. 같은 플랫폼을 사용하더라도 IdP 역할과 채팅 역할에는 별도 앱을 사용하세요. 이 분리는 로그인·디렉터리 권한을 bot 권한과 분리합니다. 또한 credential 순환과 앱 릴리스도 분리됩니다.

하나의 채팅 앱은 보통 하나의 bot identity를 나타냅니다. 여러 Agent가 서로 다른 bot 이름, 아바타, 권한이 필요하다면 플랫폼에 앱을 여러 개 만드세요. 앱을 준비한 뒤 Console에서 라우팅 규칙을 만들고 의도한 Agent에 연결하세요.

Slack, Teams, Lark/Feishu, DingTalk, WeCom은 엔터프라이즈 플랫폼입니다. 사용자는 IdP가 동기화한 디렉터리에서 옵니다. Telegram, Discord, LINE, WhatsApp은 소비자용 IM입니다. 사용자에게 직원 레코드가 없으므로 Agent가 응답하기 전에 관리자가 아이덴티티 → 대기 중인 매핑에서 새 발신자마다 계정에 매핑합니다. WhatsApp은 알려진 계정이 이미 그 전화번호를 소유한 경우 발신자를 스스로 매핑합니다. Email은 전용 메일함을 연결하며, 발신자는 명시적인 이메일 identity 바인딩을 통해서만 알려집니다.

Slack은 Socket Mode를 사용합니다. Ankole이 아웃바운드 WebSocket을 열기 때문에 채팅 경로에 공용 Slack webhook이 필요하지 않습니다.

시작하기 전에

Slack 앱을 만들고 설치할 권한
테스트 채널 또는 다이렉트 메시지

기본 설정

Slack 앱 준비

01
앱 생성 및 Socket Mode 활성화
Slack 앱을 처음부터 만듭니다. Basic Information에서 App-Level Token을 만들고 아래 scope를 추가한 다음 Socket Mode를 활성화합니다.
- connections:write
  App Token이 Socket Mode 연결을 열 수 있게 합니다
02
채팅 및 채널 상태 이벤트 구독
Event Subscriptions → Subscribe to bot events를 엽니다. 아래의 각 이벤트를 추가합니다. 이 목록은 Slack adapter가 구현한 메시지, 반응, 채널 상태 기능과 일치합니다.
- app_mention
  채널 @멘션 수신
- message.channels
  공개 채널 메시지 수신
- message.groups
  비공개 채널 메시지 수신
- message.im
  다이렉트 메시지 수신
- message.mpim
  여러 사람 간 다이렉트 메시지 수신
- reaction_added
  추가된 반응 수신
- reaction_removed
  제거된 반응 수신
- member_joined_channel
  채널에 참여한 구성원 동기화
- member_left_channel
  채널에서 나간 구성원 동기화
- channel_rename
  채널 이름 변경 동기화
- group_rename
  비공개 채널 이름 변경 동기화
- channel_deleted
  채널 삭제 동기화
- channel_archive
  채널 아카이브 동기화
03
다이렉트 메시지 활성화
App Home → Show Tabs를 엽니다. Display Messages 탭을 켜고 Allow users to send Slash commands and messages from the messages tab을 선택합니다. Messages 탭만으로는 화면이 표시될뿐 사용자가 Agent에게 다이렉트 메시지를 보낼 수는 없습니다.
04
Slack 기본 인터랙티비티 활성화
Interactivity & Shortcuts를 열고 Interactivity를 활성화합니다. Socket Mode가 기존 WebSocket을 통해 Block Kit 버튼 동작을 전달하므로 공용 Request URL이 필요하지 않습니다.
05
전체 채팅 scope 부여 및 앱 설치
OAuth & Permissions → Bot Token Scopes에서 아래의 각 scope를 추가합니다. 이 목록은 Ankole이 호출하는 Slack API만 포함합니다. 사용하지 않는 assistant, workflow, document, meeting scope는 부여하지 마십시오.
- app_mentions:read
  봇을 멘션한 메시지 읽기
- channels:read
  공개 채널과 그 구성원 동기화
- channels:history
  공개 채널 메시지 읽기 및 답글 조정
- groups:read
  비공개 채널과 그 구성원 동기화
- groups:history
  비공개 채널 메시지 읽기 및 답글 조정
- im:read
  다이렉트 메시지 대화 동기화
- im:history
  다이렉트 메시지 읽기 및 답글 조정
- mpim:read
  여러 사람 간 다이렉트 메시지와 그 구성원 동기화
- mpim:history
  여러 사람 간 다이렉트 메시지 읽기 및 답글 조정
- chat:write
  봇 메시지 전송, 업데이트, 삭제
- reactions:read
  반응 변경 수신
- reactions:write
  반응 추가 및 제거
- files:read
  메시지에 첨부된 파일 읽기
- files:write
  Agent가 보내는 파일 업로드
- users:read
  채널 구성원 식별 및 봇 계정 제외
scope를 변경한 후에는 워크스페이스에 앱을 다시 설치하고 새 Bot Token을 Ankole에 입력합니다.
06
Console 필드 수집
botToken
xoxb-…
Bot User OAuth Token. xoxb- 접두사가 필요합니다.
appToken
xapp-…
Socket Mode용 App-Level Token. xapp- 접두사가 필요합니다.

Console에서 연결 완료

현재 릴리스는 직접 연결을 사용합니다. 하나의 라우팅 규칙이 하나의 Channel Provider를 하나의 Agent에 연결합니다. 규칙은 adapter, 앱 자격 증명, 대상 Agent, 그룹 메시지 동작을 기록합니다. bot마다 별도의 규칙을 만드세요.

Console에서 Signal Routing → New routing rule을 열고 설정합니다:

필드	선택할 값
Target Agent	3단계에서 만든 Agent
Adapter	Slack, Teams, Lark/Feishu, DingTalk, WeCom, Telegram, Discord, LINE, WhatsApp 또는 Email
Rule name	`slack-main` 또는 `lark-main` 같은 안정적인 이름
Group message mode	`addressed_only`로 시작
Channel settings	채널 tab의 자격 증명과 값을 붙여 넣기

규칙을 저장합니다. 목록에 활성화된 상태로 표시되어야 합니다. 양식이 credential을 거부하면 IM을 테스트하기 전에 그 오류를 고치세요. adapter가 아직 연결을 열지 않았습니다.

5. IM에서 Agent와 대화

테스트 대화에 bot을 추가하세요. 그룹 채팅에서는 명시적 @멘션으로 시작하세요:

@Ankole 무엇을 할 수 있고, 어떤 팀을 서빙하나요?

첫 실제 모델 답변이 온 뒤, 팀에 맞게 Agent mission, 모델, 그룹 채팅 정책을 조정하세요.

Agent가 응답하지 않으면

한 번에 한 경계씩, 다음 순서로 확인하세요:

최신 provider 앱 버전이 게시되어 테스트 사용자가 사용할 수 있습니다.
bot이 채널, 팀 또는 대화에 설치되어 있습니다.
필요한 메시지 이벤트와 scope가 활성화되어 있습니다.
라우팅 규칙이 활성화되어 의도한 Agent를 가리킵니다.
Agent에 primary, light, heavy model profile이 있습니다.
LLM Provider 자격 증명과 모델 선택기가 유효합니다.
최소 하나의 Worker가 준비 상태입니다.

Compose에서는 docker compose logs -f control-plane worker를 확인하세요. Kubernetes에서는 control-plane과 Worker pod 로그를 확인합니다. 관련 오류만 읽고 환경 변수나 secret을 출력하지 마세요.

답변이 도착하면 Agents, Signal 라우팅 규칙 또는 Background Agent Jobs로 계속하세요.

빠른 시작

Ankole 배포 방식

이 가이드에서 사용하는 용어

Agent가 setup을 완료하게 하기

1. Ankole 배포

Docker Compose로 설치하기

배포 패키지 가져오기

독립된 secrets 세 개 생성하기

공개 호스트 설정하기

스택 시작 및 확인하기

첫 설정 열기

2. identity provider를 먼저 설정

IdP setup 완료

Slack IdP 설정하기

Ankole에서 callback URL 복사하기

Slack 앱 만들기

로그인 callback 등록하기

디렉터리 액세스를 부여하고 Bot Token을 받습니다

App Token을 받고 Socket Mode를 사용 설정합니다

디렉터리 이벤트를 구독합니다

Ankole에 Slack 값을 입력합니다

로그인과 최초 동기화를 확인합니다

3. LLM Provider 추가 및 Agent 생성

4. 채팅 채널 연결 및 시그널 라우팅 규칙 생성

Slack 앱 준비

앱 생성 및 Socket Mode 활성화

채팅 및 채널 상태 이벤트 구독

다이렉트 메시지 활성화

Slack 기본 인터랙티비티 활성화

전체 채팅 scope 부여 및 앱 설치

Console 필드 수집

Console에서 연결 완료

5. IM에서 Agent와 대화

Agent가 응답하지 않으면