동작 방식
헬피코드는 화면(Renderer), 호스트 서버(Host), AI 엔진 세 부분으로 이루어집니다. 이 문서는 요청이 어떻게 처리되고, AI가 무엇을 할 수 있으며, 어디까지 접근하는지 설명합니다.
구성 요소
┌──────────────────┐ ┌──────────────────┐ ┌────────────────────┐
│ 화면 │────▶│ 호스트 서버 │────▶│ AI 엔진 사이드카 │
│ (대화·설정 UI) │◀────│ │◀────│ │
└──────────────────┘ │ │ └────────────────────┘
│ │ ┌────────────────────┐
│ │────▶│ 엘리스 서버 │
└──────────────────┘◀────│ (계정·모델·사용량) │
└────────────────────┘
| 구성 요소 | 역할 |
|---|---|
| 화면(Renderer) | 대화 UI, 설정, 패널을 그립니다. 호스트 서버하고만 통신합니다. |
| 호스트 서버 | 사이드카(AI 엔진) 프로세스를 실행·감시하고, 엘리스 API 호출에 로그인 토큰을 붙여 전달합니다. 토큰은 화면으로 전달되지 않습니다. |
| AI 엔진 사이드카 | 실제 AI 에이전트입니다. 127.0.0.1의 빈 포트에서 실행되며 도구 실행, 권한 판단, 세션 기록을 담당합니다. |
| 엘리스 API | 계정, 기관, 모델 목록, 토큰 사용량, 모델 추론을 제공합니다. |
AI 엔진은 오픈소스 AI 코딩 에이전트를 엘리스가 확장한 버전이며, 앱은 배포된 바이너리를 그대로 실행합니다.
요청이 처리되는 흐름
- 사용자가 메시지를 보냅니다. 화면은 호스트 서버로 전달합니다.
- AI 엔진이 기관에서 활성화한 모델에 요청을 보냅니다. 요청은 호스트 서버를 거쳐 엘리스 서버로 가며, 이때 로그인 토큰과 기관 정보가 붙습니다. 토큰 사용량은 대화(세션) 단위로 집계됩니다.
- 모델은 응답하거나 도구 호출을 요청합니다(파일 읽기, 편집, 명령 실행 등).
- 도구를 실행하기 전에 권한 판단을 거칩니다. 허용이면 실행하고, 확인이 필 요하면 화면에 권한 패널을 띄우며, 거부면 막습니다. 권한을 참고하세요.
- 도구 결과가 모델에 돌아가고, 모델이 더 호출하거나 최종 답을 하면 이 과정이 끝납니다.
AI가 할 수 있는 일
| 범주 | 도구 | 설명 |
|---|---|---|
| 파일 | read, glob, grep, edit, write, apply_patch | 파일 읽기·검색·편집·생성 |
| 명령 | bash(shell) | 터미널 명령 실행 |
| 웹 | webfetch, websearch | URL 내용 가져오기, 웹 검색 |
| 문서 | document_* | PDF·Word·Excel·PowerPoint(·HWP) 읽기·편집·생성 |
| 작업 관리 | todowrite, plan_*, question | 할 일 목록, 계획 모드, 사용자에게 질문 |
| 위임 | task | 서브에이전트에게 작업 위임 |
| 확장 | skill, MCP 도구 | 스킬 로드, 외부 서비스 도구 |
| 결과 | present_files | 만든 파일을 대화 안에 파일 카드로 보여 주기 |
도구별 상세는 내장 도구 참조에 있습니다.
컨텍스트: AI가 아는 것
AI는 매 대화 시작 시 다음 정보를 받습니다.
- 프로젝트 지침: 프로젝트 폴더에서 위로 올라가며 찾은 첫
AGENTS.md와 전역AGENTS.md. 지침 - 사용 가능한 스킬 목록: 이름과 설명만 포함하고, 본문은 필요할 때
skill도구로 불러옵니다. 스킬 - 사용 가능한 서브에이전트 목록: 서브에이전트
- MCP 도구: 켜져 있는 서버의 도구. MCP
대화가 길어지면 /compact로 요약해 컨텍스트를 확보합니다. 스킬 목록처럼 바뀔 수 있는 정보는 /reload-skills 등으로 다시 불러올 수 있습니다.
어디까지 접근하나요
- AI의 작업 기준 위치는 프로젝트 폴더(또는 임시 작업 폴더)입니다.
- 프로젝트 밖 경로, 외부 네트워크, 환경 변수 파일(
.env) 같은 민감한 파일은 권한 요청 대상입니다. - 설정 파일과 에이전트 구성(
AGENTS.md,.opencode,.git/hooks등)은 수정 시 모든 모드에서 확인을 거칩니다.
경고
헬피코드의 경로 검사는 최선의 노력(best effort) 입니다. 모델이 어떤 도구를 쓸지 고르고 명령 분류가 완벽하지 않으므로, 프로젝트 밖 접근이 항상 차단된다고 보장하지 않습니다. OS 수준의 샌드박스는 제공하지 않습니다. 보안과 개인정보를 참고하세요.
데스크톱과 런박스
두 환경은 같은 호스트 서버와 AI 엔진을 사용합니다. 차이는 로그인 방식, 폴더 위치, 브라우저 패널 구현 등입니다. 데스크톱과 런박스를 참고하세요.