# OpenDevin(OpenHands) Docker 실행

docker pull ghcr.io/all-hands-ai/openhands:0.14



docker run -it --rm \

-e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.io/nikolaik/python-nodejs:python3.11-nodejs22 \

-e LOG_ALL_EVENTS=true \

-v /var/run/docker.sock:/var/run/docker.sock \

-v ~/.openhands-state:/.openhands-state \

-p 3000:3000 \

--add-host host.docker.internal:host-gateway \

--name openhands-app \

ghcr.io/all-hands-ai/openhands:0.14

# 저장소 클론

git clone https://github.com/All-Hands-AI/OpenHands.git

cd OpenHands



# Poetry로 Python 의존성 설치

pip install poetry

poetry install



# 프론트엔드 의존성 설치

cd frontend

npm install

npm run build

cd ..



# 환경변수 설정 (.env 파일 생성)

cp config.template.toml config.toml

# config.toml 파일에서 LLM 설정 수정



# 백엔드 서버 실행

poetry run python -m openhands.server.listen

[llm]

# OpenAI GPT-4 사용 시

model = "gpt-4o"

api_key = "sk-your-openai-api-key-here"



# Anthropic Claude 사용 시

# model = "claude-3-5-sonnet-20241022"

# api_key = "sk-ant-your-anthropic-key"



# Google Gemini 사용 시

# model = "gemini/gemini-1.5-pro"

# api_key = "your-google-api-key"



[core]

workspace_base = "./workspace"

max_iterations = 100

# 이런 명령을 내리면...

"FastAPI를 사용한 간단한 TODO API 서버를 만들어줘.

CRUD 기능 포함, SQLite 데이터베이스 사용,

Docker 컨테이너화까지 해줘."



# OpenDevin이 생성하는 파일들:

# ├── main.py          (FastAPI 앱)

# ├── models.py        (데이터 모델)

# ├── database.py      (DB 연결)

# ├── requirements.txt (의존성)

# ├── Dockerfile       (컨테이너 설정)

# └── docker-compose.yml

openhands/

└── agenthub/

├── __init__.py

├── codeact_agent/      # 기본 에이전트

│   ├── __init__.py

│   └── codeact_agent.py

└── my_custom_agent/    # 내가 만들 에이전트!

├── __init__.py

└── my_agent.py

from openhands.controller.agent import Agent

from openhands.controller.state.state import State

from openhands.core.config import AgentConfig

from openhands.events.action import Action, AgentFinishAction

from openhands.events.action.message import MessageAction

from openhands.llm.llm import LLM



class MyCustomAgent(Agent):

"""나만의 커스텀 에이전트"""



VERSION = "1.0.0"



def __init__(self, llm: LLM, config: AgentConfig):

super().__init__(llm, config)

# 에이전트 초기화 로직

self.system_prompt = """

당신은 Python 전문가 에이전트입니다.

항상 PEP8 스타일 가이드를 따르고,

타입 힌트를 반드시 포함하세요.

"""



def step(self, state: State) -> Action:

"""에이전트의 핵심 로직 - 매 스텝마다 호출됨"""



# 현재 상태에서 메시지 히스토리 가져오기

messages = self._get_messages(state)



# LLM에 요청

response = self.llm.completion(

messages=messages,

temperature=0.1

)



# 응답 파싱 및 액션 반환

action = self._parse_response(response)

return action



# 에이전트 등록

Agent.register("MyCustomAgent", MyCustomAgent)

SYSTEM_PROMPT = """

당신은 시니어 풀스택 개발자 에이전트입니다.



## 핵심 원칙

1. 코드를 작성하기 전에 항상 계획을 먼저 세우세요

2. 각 단계마다 코드를 실행하고 결과를 확인하세요

3. 에러가 발생하면 원인을 분석하고 수정하세요

4. 완료 후 반드시 테스트를 실행하세요



## 코드 품질 기준

- 타입 힌트 필수 사용

- 함수/클래스에 docstring 작성

- 에러 처리 코드 포함

- 단위 테스트 작성



## 작업 완료 조건

모든 테스트가 통과하고 코드가 정상 실행될 때

AgentFinishAction을 반환하세요.

"""

# config.toml에 MCP 서버 설정

[mcp]

# GitHub MCP 서버 연동

[[mcp.servers]]

name = "github"

command = "npx"

args = ["-y", "@modelcontextprotocol/server-github"]

env = {GITHUB_PERSONAL_ACCESS_TOKEN = "your-token"}



# 파일시스템 MCP 서버

[[mcp.servers]]

name = "filesystem"

command = "npx"

args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

# GitHub Actions 워크플로우 예시

# .github/workflows/openhands.yml



name: OpenDevin Auto-Fix

on:

issues:

types: [labeled]



jobs:

auto-fix:

if: github.event.label.name == 'ai-fix'

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- name: Run OpenDevin

uses: all-hands-ai/openhands-resolver@v0.1

with:

github_token: ${{ secrets.GITHUB_TOKEN }}

llm_model: "claude-3-5-sonnet-20241022"

llm_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

# 오케스트레이터 에이전트 설정 예시

from openhands.controller.agent import Agent

from openhands.agenthub.delegator_agent import DelegatorAgent



class ProjectManagerAgent(Agent):

"""프로젝트 전체를 관리하는 오케스트레이터"""



SYSTEM_PROMPT = """

당신은 프로젝트 매니저 에이전트입니다.

복잡한 작업을 받으면 다음과 같이 처리하세요:



1. 작업을 분석하고 하위 작업으로 분해

2. 각 하위 작업을 적절한 전문 에이전트에 위임

- 코딩 작업 → CodeActAgent

- 웹 리서치 → BrowsingAgent

- 버그 찾기 → LocAgent

3. 결과를 통합하고 최종 검토

"""



def step(self, state):

# 작업 분석 및 위임 로직

subtask = self._analyze_and_delegate(state)

return AgentDelegateAction(

agent="CodeActAgent",

inputs={"task": subtask}

)

# config.toml 성능 최적화 설정

[core]

max_iterations = 50          # 최대 반복 횟수 제한

max_budget_per_task = 2.0    # 작업당 최대 비용 ($)



[llm]

model = "claude-3-5-sonnet-20241022"

temperature = 0.0            # 결정론적 출력 (비용 절감)

max_output_tokens = 4096     # 출력 토큰 제한

caching_prompt = true        # 프롬프트 캐싱 활성화



[sandbox]

timeout = 120                # 샌드박스 타임아웃 (초)

use_host_network = false     # 보안을 위해 호스트 네트워크 차단

# 환경변수로 상세 로깅 활성화

export LOG_ALL_EVENTS=true

export DEBUG=true



# 로그 파일 확인

tail -f logs/openhands.log



# 특정 세션의 이벤트 스트림 확인

# 웹 UI → Sessions → 해당 세션 클릭 → Events 탭

# 보안 강화 Docker 실행 예시

docker run -it --rm \

--network=none \          # 네트워크 완전 차단 (필요시 조정)

--memory=4g \             # 메모리 제한

--cpus=2 \                # CPU 제한

--read-only \             # 읽기 전용 파일시스템

--tmpfs /tmp \            # 임시 파일만 쓰기 가능

-e OPENAI_API_KEY=$OPENAI_API_KEY \  # 환경변수로 키 전달

ghcr.io/all-hands-ai/openhands:latest

# 기여 시작하기

git clone https://github.com/All-Hands-AI/OpenHands.git

cd OpenHands



# 개발 환경 설정

poetry install --with dev

pre-commit install



# 테스트 실행

poetry run pytest tests/unit/



# 새 브랜치에서 작업

git checkout -b feature/my-awesome-feature

# ... 코드 작성 ...

git push origin feature/my-awesome-feature

# GitHub에서 PR 생성!