여러 코딩 에이전트의 대화·작업 폴더·실행 서버를 따로 관리하거나, 상시 켜진 서버에서 반복 작업을 돌리려는 개발자는 OpenHands Agent Canvas로 관리 화면을 모을 수 있습니다. 에이전트와 실행 환경을 선택하는 공통 화면에 자동화 관리를 더합니다. 한 에이전트로 로컬 저장소 하나를 수정하는 사람에게는 설정과 유지보수 부담이 이점보다 클 수 있습니다. 2026년 10월 7일 확인한 문서와 v1.25.0을 기준으로 이용 조건을 설명합니다. (공식 저장소)

한눈에 보기

궁금한 점 확인한 내용
어떤 도구입니까? 대화·파일·터미널·모델 설정과 자동화를 관리하는 브라우저 기반 제어 화면입니다.
어떤 에이전트를 연결합니까? OpenHands와 ACP를 통한 Claude Code·Codex·Gemini CLI 등을 연결합니다.
코드는 어디서 실행합니까? 선택한 백엔드에서 실행합니다. 로컬·Docker·VM·관리형 클라우드 등의 경로를 제공합니다.
처음 선택되는 제공자는? OpenHands 에이전트와 OpenHands 모델 제공자를 먼저 선택합니다. 설정에서 바꿉니다.
자체 호스팅은 무료입니까? 저장소 코드는 MIT입니다. 모델 호출과 인프라, 상용 서비스의 비용은 별도로 계산합니다.
Windows에서 시작합니까? Docker Desktop용 PowerShell 안내가 있습니다. 대화별 Docker 격리는 WSL 2 안내를 따릅니다.
검토 기준은? 2026년 10월 6일 공개된 v1.25.0, 커밋 50c68a1입니다.
도입 판단은? 특정 상황에 유용합니다. 여러 실행 환경이나 반복 자동화를 관리할 때 작은 범위부터 검토합니다.

기능은 공식 개요, 초기 선택은 첫 설정 안내, 버전은 릴리스에서 대조했습니다. 저장소는 확인일에 누적 90.2k stars를 표시했습니다. 프로젝트를 발견하는 인기 신호로만 사용합니다.

어떤 작업에 도움이 됩니까?

OpenHands는 코드를 읽고 고치며 명령을 실행하는 오픈소스 코딩 에이전트 프로젝트입니다. 현재 저장소 README는 Agent Canvas를 "자체 호스팅 개발자 제어 센터"로 소개합니다. OpenHands 자체 에이전트뿐 아니라 Claude Code·Codex·Gemini 같은 다른 에이전트도 같은 화면에서 띄우고, 그 에이전트가 어느 컴퓨터에서 일할지 고르는 도구입니다. (공식 저장소)

예를 들어 팀이 개인 노트북에서 기능 수정을 하고, 별도 서버에서 저장소 점검을 반복한다면 두 환경을 같은 화면에서 선택하는 데 도움이 됩니다. 여기서 백엔드는 실제 명령 실행과 상태 보관을 맡는 서비스이고, 작업 공간은 에이전트가 읽고 쓸 폴더나 컨테이너 마운트입니다. 브라우저를 내 컴퓨터에서 연다고 실행 장소까지 내 컴퓨터로 바뀌지는 않습니다. (구조와 실행 경계)

반복 작업에는 일정·웹훅·이벤트 트리거를 연결합니다. 웹훅은 다른 서비스가 사건 발생을 알려 주는 HTTP 요청입니다. Automate 화면에서는 작업의 프롬프트와 모델, 최근 실행 상태를 살펴보고 켜거나 끕니다. GitHub·Slack 등과의 연동은 해당 서비스 연결을 구성한 뒤 활용합니다. 로컬 파일 수정만 필요한 단계에서는 계정 연동 없이 대화부터 시작하는 구성이 더 단순합니다. (자동화 관리)

기존 도구와 무엇이 다릅니까?

비교의 핵심은 에이전트가 코드를 얼마나 잘 쓰느냐보다 서로 다른 실행 환경과 작업을 관리하는 방식입니다. 기존 에이전트의 파일 수정·명령 실행을 쓰면서 Agent Canvas를 추가하면, 작업 화면과 백엔드 선택, 자동화 이력 관리가 한 층 더 생깁니다. 모델의 코딩 품질이 이 화면만으로 올라간다는 측정 근거는 이번 조사에 포함하지 않습니다.

ACP는 에이전트 클라이언트와 외부 에이전트가 대화하는 프로토콜입니다. Canvas의 서버가 외부 CLI를 하위 프로세스로 띄워 메시지를 전달하고 결과를 보여 줍니다. 외부 에이전트는 자기 모델과 도구를 관리합니다. 따라서 Canvas에서 고른 일반 LLM 설정을 모든 외부 에이전트에 공통 적용한다고 생각하기보다, 선택한 에이전트의 인증·모델 설정을 함께 확인합니다. (ACP 연결 원리)

하나의 로컬 프로젝트에서 대화하며 수정 사항을 검토하는 흐름이 이미 편하다면 기존 도구를 계속 쓰는 선택이 합리적입니다. 반대로 노트북과 서버 사이를 자주 오가거나 여러 자동화의 실행 내역을 확인하는 업무에서는 제어 화면을 추가할 이유가 분명해집니다. 이 비교는 기능 구조에 따른 판단이며 실제 작업 시간 비교는 아닙니다.

어떻게 사용합니까?

구체적인 예는 빈 검색어를 제출할 때 오류가 나는 웹 프로젝트의 버그 수정입니다. 아래는 문서를 바탕으로 구성한 사용 예입니다. 입력은 프로젝트 복사본, 재현 절차, 원하는 동작이며 결과는 변경 파일과 테스트 기록으로 정합니다. 이 단계에서 GitHub 계정이나 PR 작성 권한은 연결하지 않습니다.

  1. 시험용 프로젝트를 전용 폴더에 준비합니다. 재현 조건은 “검색창을 비우고 제출하면 오류가 납니다”, 목표는 “빈 검색어를 안내하고 기존 검색 테스트를 유지합니다”처럼 적습니다.
  2. 아래 Docker 방식으로 시작하고 브라우저에서 http://localhost:8000을 엽니다. 처음 설정에서 에이전트·백엔드·모델 접근 경로를 선택합니다. 설치만으로 버그 수정이 시작되지는 않습니다.
  3. 새 대화의 작업 공간에 컨테이너 안의 /projects 아래 프로젝트를 지정합니다. “원인을 먼저 설명하고 관련 파일만 수정한 뒤 프로젝트에 정의된 테스트를 실행합니다”라는 요청과 재현 조건을 전달합니다.
  4. 대화, 변경 파일, 명령 결과를 확인합니다. 기대 결과는 작은 코드 변경과 실행한 테스트의 성공·실패 기록입니다. 변경의 적절성과 테스트 누락은 사람이 검토합니다.

요청 뒤 에이전트는 선택한 공간의 파일을 고치고 셸 명령을 실행할 수 있습니다. 시험 프로젝트에는 배포용 비밀값을 빼고, 외부 게시나 병합은 별도 단계로 둡니다. 이런 범위가 정해진 뒤에 이슈 입력이나 PR 자동화를 연결하면 파일 수정 권한과 서비스 쓰기 권한을 나누어 판단하기 좋습니다. (작업 공간 안내)

설치와 이용 조건

Windows에서는 Docker 방식으로 시작합니다

Windows README의 Docker Desktop용 명령에서 이미지 태그·포트·볼륨·세션 키 설정을 대조했습니다. 아래는 원문의 구성을 유지한 PowerShell 예입니다. projects 폴더 아래에는 에이전트에게 보여 줄 시험 프로젝트만 둡니다.

docker pull ghcr.io/openhands/agent-canvas:1.25.0
$env:PROJECTS_PATH = Join-Path $HOME "projects"
New-Item -ItemType Directory -Force -Path $env:PROJECTS_PATH, (Join-Path $env:USERPROFILE ".openhands") | Out-Null

docker run -it --rm `
  -p 127.0.0.1:8000:8000 `
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true `
  -v "$($env:USERPROFILE)\.openhands:/home/openhands/.openhands" `
  -v "$($env:PROJECTS_PATH):/projects" `
  ghcr.io/openhands/agent-canvas:1.25.0

첫 번째 docker pull은 지정한 버전의 이미지를 내려받습니다.

-v는 호스트 폴더를 컨테이너에 연결합니다. /projects 아래 파일에 대한 수정은 호스트의 프로젝트에도 반영됩니다. .openhands 볼륨에는 지속 상태를 보관합니다. --rm으로 컨테이너를 지워도 연결한 호스트 폴더는 남습니다. 세션 키는 브라우저 화면이 백엔드에 접속할 때 쓰는 키입니다. 이 예는 포트를 127.0.0.1(내 컴퓨터에서만 접속)에 한정한 상태에서 이 키를 화면에 자동으로 넣어 주는 설정을 명시적으로 켭니다. LAN이나 공개 주소로 바꿀 때는 이 옵션을 제외하고 LOCAL_BACKEND_API_KEY와 자체 호스팅 접근 제한을 구성합니다. (Windows 접속 조건)

다른 실행 방식과 OS 조건을 구분합니다

일반 로컬 실행의 공식 명령은 npm install -g @openhands/agent-canvas 다음 agent-canvas입니다. Node.js 24 이상과 uv를 전제로 합니다. 패키지를 전역 설치하고 로컬 서버 묶음을 시작하며, 에이전트 서버는 호스트 파일시스템에 직접 접근합니다. Docker 경로는 macOS·Windows의 Docker Desktop, Linux의 Docker Engine 또는 Desktop을 안내합니다. (설치 선택지)

대화마다 Docker 컨테이너를 분리하는 OH_CONVERSATION_RUNTIME=docker 경로는 또 다른 선택지입니다. Windows에서는 Docker Desktop의 WSL 통합을 켠 WSL 2 Linux 배포판 안에서 Node.js 24 이상과 uv를 준비합니다. 원문은 네이티브 Windows 호스트에서 이 런타임을 지원하지 않는다고 명시합니다. 컨테이너가 달라도 같은 호스트 작업 공간을 마운트하면 파일은 공유하므로 작업별 폴더나 worktree를 나눕니다. (실행 방식, Windows·WSL 조건)

기본 모델 선택과 외부 전송을 확인합니다

첫 설정은 OpenHands 에이전트와 OpenHands 제공자를 선택하고 추천 모델을 채웁니다. 확인한 안내에서는 기본 모델을 GPT-5.6 Sol로 설명하고, DeepSeek V4 Flash를 무료 OpenHands 경유 모델로 구분합니다. 다른 경로를 쓰려면 LLM Provider 드롭다운을 바꾸고 모델·키를 선택합니다. 이 선택으로 대화 맥락을 받을 제공자가 달라집니다. ACP를 고르면 해당 에이전트의 인증과 모델 구성을 사용합니다. (초기 설정)

외부 CLI는 실행되는 백엔드에서 자격 증명에 접근합니다. 노트북의 로그인이 깨끗한 Docker 컨테이너에 저절로 전달되지는 않으므로 컨테이너 쪽 인증 상태를 확인합니다. 문서는 CLI에 구독(OAuth) 로그인이 되어 있으면 환경에 넣은 API 키보다 그 로그인을 먼저 쓴다고 설명합니다. 같은 에이전트라도 구독 한도로 처리될지 API 사용량으로 청구될지가 백엔드의 로그인 상태에 따라 달라지는 셈입니다. 설정 화면에 입력한 API 키는 백엔드의 Secrets에서 관리하며, Settings > Secrets에서 수정하거나 제거합니다. (ACP 인증과 키 저장)

모델 요청 외에 사용 분석 전송도 살펴봤습니다. Canvas의 텔레메트리 코드는 최초 사용 이벤트를 동의 여부와 별도로 보내고, 세션·사용자 지정 이벤트는 동의 뒤 전송한다고 설명합니다. 기본 목적지는 OpenHands 프록시를 거친 PostHog입니다. 자체 호스팅 번들에서 최초 사용 분석까지 끄려면 AGENT_CANVAS_DISABLE_TELEMETRY=1을 사용합니다. 위 Docker 명령의 다른 -e 줄과 나란히 -e AGENT_CANVAS_DISABLE_TELEMETRY=1을 추가합니다. 이 설정은 분석 전송을 끄며 선택한 모델 제공자로 보내는 추론 요청은 별도로 남습니다. (텔레메트리 구현)

비용과 라이선스

2026년 10월 7일 확인한 라이선스는 MIT입니다. 사용·수정·배포·판매를 허용하고, 복사본이나 상당 부분을 배포할 때 저작권 고지와 허가 문구를 포함하는 조건을 둡니다. 소프트웨어는 보증 없이 제공됩니다.

예산은 네 갈래로 나눠 계산합니다. 저장소 코드의 이용료, 모델 사용량, 서버·Docker 실행 인프라, 관리형 Cloud·Enterprise의 서비스 조건입니다. 무료 자체 호스팅 코드를 쓴다는 사실만으로 모델 호출까지 무료가 되지는 않습니다. 개인 API 키는 제공자 과금으로, 기존 로그인 경로는 해당 계정의 이용 조건으로 확인합니다. 무료라고 안내된 특정 모델의 조건을 다른 모델로 확대하지 않습니다. (모델 연결 경로, 서비스 구분)

반복 자동화는 모델 호출과 서버 가동을 계속 만들 수 있습니다. Automate에서 작업을 끄면 설정은 유지되고 예정된 트리거 실행은 중지합니다. 실행 기록에서 백엔드가 보고한 모델 비용을 확인하고, 보고값이 없는 실행은 비용 미확인으로 취급합니다. 한국에서의 모델 접근성·결제·데이터 처리 위치는 선택한 제공자별로 확인합니다. 이번 조사에서는 한국 계정 가입이나 원화 청구 시험을 진행하지 않았습니다. (자동화와 비용 기록)

한계와 유지보수

자체 호스팅을 팀에 공개하는 단계에서는 접속 제어가 큰 판단 항목입니다. 이슈 #17397은 사용자별 로그인과 첫 관리자 설정을 요청하며, 공유 API 키 화면과 사용자 신원 관리를 구분합니다. 관련 PR #17412는 조사 시점에 열려 있습니다. PR의 AI 자동 검수 댓글에는 로그인 없이 보낸 WebSocket 연결 요청이 제안된 로그인 관문을 통과해 백엔드 데이터를 받았다는 재현 결과도 있습니다. 제안된 로그인 옵션을 현재 배포판의 완성 기능으로 안내하지 않습니다.

한편 최신 README는 로컬 접속을 루프백에 제한하고 외부 주소에서 세션 키 자동 주입을 막는 구성을 설명합니다. 이슈 본문의 예전 “인증 없는 노출” 설명과 현재 기본 실행을 그대로 동일시하지 않고, 실제 바인딩 주소와 키 설정을 함께 확인합니다. 인터넷 공개를 계획한다면 자체 호스팅 안내의 방화벽·접근 경계를 먼저 설계하고, 첫 시험은 로컬 Docker로 진행합니다.

유지보수의 근거는 10월 6일 v1.25.0 릴리스입니다. 모델 프로필·자동화 화면의 기능과 수정 사항이 기록돼 있어 최근 개발 활동을 확인할 수 있습니다. Canvas 외에도 SDK·Agent Server·자동화 서비스 등 여러 저장소가 실행을 나눠 맡으므로, 장애를 조사할 때 화면 오류인지 실행 서버 오류인지 구분합니다. 상시 운영의 부담도 이 구조에 따라 늘어납니다. (릴리스 기록, 저장소 책임 구분)

확인한 범위

문서 확인: 2026년 10월 7일 README, Windows 안내, MIT 라이선스, v1.25.0 릴리스, 공식 Canvas·LLM·ACP·자동화 문서와 인증 관련 이슈·PR을 대조했습니다. 추가로 첫 설정의 기본 제공자와 텔레메트리 코드의 전송·끄기 설정을 확인했습니다. 릴리스 기준은 50c68a1이며, 공식 웹 문서와 main의 설정 설명은 확인일 현재 내용을 사용합니다.

설치와 구성은 공식 안내를 바탕으로 설명했습니다. Docker와 한국어 작업은 직접 실행하지 않았습니다.

도입 판단

특정 상황에 유용하다고 판단합니다. 여러 에이전트와 로컬·서버 백엔드를 오가거나, 반복 작업의 설정과 실행 이력을 한 화면에서 관리할 필요가 분명할 때 도입 이유가 생깁니다. 작은 프로젝트 한 개를 Docker에 연결해 변경 파일 검토가 편해지는지부터 평가합니다.

다음 행동은 기본 제공자와 분석 전송 선택을 확인하고, 앞의 빈 검색어 버그처럼 입력·목표가 작은 작업을 한 번 수행하는 것입니다. 그 결과를 기존 도구의 흐름과 비교한 뒤 자동화와 서비스 권한을 추가합니다. 사용자별 인증과 인터넷 공개가 첫 요구라면 로그인 제안의 병합·검수 상태와 배포 구성을 더 확인한 뒤 도입 범위를 정합니다.

참고한 자료

모든 자료의 확인일은 2026년 10월 7일입니다. README와 웹 문서는 확인 시점의 내용, 릴리스는 고정된 v1.25.0을 기준으로 읽었습니다.