본문으로 건너뛰기
FlowAgent

문서

설치부터 첫 워크플로우 작성, 흔한 막힘까지. 풀 문서 사이트는 v0.2.0 이후 확장 예정이지만 이 페이지만으로 충분히 시작할 수 있어요.

01 · 설치

OS별 설치 가이드

v0.1.0은 Node.js + pnpm 위에서 동작합니다. 첫 실행시 자동 설치되니 별도 준비할 게 없어요.

🪟 Windows 10 / 11
  1. taskflow.kr/download에서 zip 다운로드
  2. 원하는 폴더에 압축 해제
  3. start.bat 더블클릭
  4. 메모장이 열리면 ANTHROPIC_API_KEY= 뒤에 키 붙여넣기 → 저장 후 닫기

Node·pnpm 자동 설치 (corepack 또는 npm fallback)

🍎 macOS 13+
  1. Node.js 18+ 설치 (nodejs.org 또는 brew install node)
  2. corepack enable
  3. git clone + pnpm install && pnpm dev

v0.2.0에서 .app installer 출시 예정

🐧 Linux (Ubuntu 22.04+)
  1. Node.js 18+ 설치 (nvm 권장)
  2. corepack enable
  3. git clone + pnpm install && pnpm dev

v0.2.0에서 .deb + AppImage 출시 예정

02 · Quickstart

1분 안에 첫 워크플로우 실행

  1. STEP 1

    서버 시작

    Windows는 start.bat 더블클릭. macOS·Linux는 터미널에서 pnpm dev.

  2. STEP 2

    카드 클릭

    브라우저 자동 오픈 (localhost:3000). 카드 중 하나(예: weekly-report) 클릭.

  3. STEP 3

    실행 & 결과

    실행하기 → 단계별 결과가 SSE로 스트리밍됨. 결과는 runs/<timestamp>.jsonl에 저장.

03 · YAML 스키마

워크플로우 한 파일 구조

workflows/<slug>.yaml로 저장하면 자동 감지. 별도 등록 없음.

workflows/example.yaml 
name: example
description: "한 줄 설명 (카드에 표시됨)"
category: "운영 / PM"
persona: "매니저·리드"
burden: "덜어주는 부담 한 줄"

steps:
  - id: load
    run: shell
    cmd: cat data.csv

  - id: summarize
    run: llm
    prompt: |
      아래를 1-pager로 요약:
      {{ load.stdout }}

워크플로우 메타 필드

name
slug · 파일명 기준 자동, 카드 헤더에 표시
description
카드 본문 한 줄 (1~2문장 권장)
category
분류 뱃지 (CS팀·운영·영업관리 등 자유 문자열)
persona
페르소나 필터 키 (선택)
burden
덜어주는 부담 한 줄 (선택)
steps[]
실행 단계 배열 (1개 이상)

_로 시작하는 파일명(_pilot-draft-template.yaml 등)은 템플릿으로 분류돼 카드 목록에 노출되지 않습니다.

04 · Step 타입

llm · shell — 두 가지면 충분합니다

run: llm

Anthropic Claude API 호출. 본인 키 사용. 응답 텍스트는 {{ step_id.text }}로 다음 단계에서 참조.

prompt
필수. 변수 보간 가능 (| 블록 권장)
model
선택. 기본 claude-sonnet-4-6
max_tokens
선택. 기본 4096
run: shell

로컬 셸 명령 실행 (sandboxed). 출력은 {{ step_id.stdout }}로 참조. exit code 0이 아니면 워크플로우 중단.

cmd
필수. 변수 보간 가능. cross-platform은 node -e 추천
cwd
선택. 실행 디렉토리 (기본: workflow 루트)
timeout_ms
선택. 기본 60000 (60초)

💡 v0.2.0에서 http (HTTP 요청), file (파일 입출력) step 추가 예정.

05 · 변수 보간

이전 단계 결과를 다음 단계에서 쓰기

{{ ... }} 구문으로 이전 단계 출력을 참조합니다. Jinja2 비슷한 문법이지만 단순 치환만 지원.

표현식 의미 사용처
{{ step_id.text }} LLM 단계의 응답 텍스트 llm prompt, shell cmd
{{ step_id.stdout }} Shell 단계의 stdout (trailing newline trim) llm prompt, shell cmd
{{ step_id.stderr }} Shell 단계의 stderr 디버깅 / 에러 처리
{{ step_id.exit_code }} Shell 단계의 종료 코드 (정수) 조건 분기 (예정)
{{ env.VAR_NAME }} .env에서 정의한 환경변수 prompt, cmd (예정)

⚠️ 한 단계의 출력을 다음 단계에서 참조할 때만 사용. 같은 단계 내 자기 참조는 동작하지 않습니다.

06 · 환경변수

.env 파일 — 키와 옵션 설정

프로젝트 루트의 .env 파일에서 API 키와 동작 옵션을 설정합니다. 모든 값은 로컬에만 저장됩니다.

.env 
# 필수 — Anthropic API 키
ANTHROPIC_API_KEY=sk-ant-...

# 선택 — 서버 포트 (기본 3000)
PORT=3000

# 선택 — 워크플로우 폴더 (기본 workflows)
FLOWAGENT_WORKFLOWS_DIR=workflows

# 선택 — 실행 로그 폴더 (기본 runs)
FLOWAGENT_RUNS_DIR=runs

# 선택 — Pilot 미팅 신청 메일 (기본 wndnjs3865@naver.com)
FLOWAGENT_PILOT_CONTACT_EMAIL=you@company.com

🔒 .env는 .gitignore에 포함돼 있습니다. 절대 커밋되지 않으니 안심하세요.

07 · Troubleshooting

자주 마주치는 문제

start.bat 더블클릭 시 검은 창이 떴다가 즉시 닫혀요

대부분 줄바꿈(LF/CRLF) 또는 cmd 파싱 문제입니다. v0.1.0에서 fix 되었으니 GitHub Release 최신본을 다시 다운받아 보세요. 그래도 문제면 cmd 창에서 직접 start.bat을 실행해 에러 메시지를 확인할 수 있어요.

"포트 3000이 사용 중" 에러

이미 다른 FlowAgent 인스턴스 또는 다른 프로그램이 3000번 포트를 점유 중입니다. 종료 후 재시작하거나, 환경변수 PORT=3001로 포트를 바꿔 실행하세요.

# Windows (PowerShell)
$env:PORT=3001; pnpm dev

# macOS / Linux
PORT=3001 pnpm dev
API 키를 입력했는데도 LLM 단계가 실패해요

.env 파일의 ANTHROPIC_API_KEY= 뒤에 공백·따옴표 없이 키를 붙여넣었는지 확인하세요. sk-ant-로 시작하는 게 정상입니다. 저장 후 서버를 한 번 재시작 (cmd 창 닫고 start.bat 다시 더블클릭).

워크플로우 카드가 안 보여요

workflows/ 디렉토리에 .yaml 파일이 있는지 확인. 파일명이 _ (언더스코어)로 시작하면 템플릿으로 분류되어 카드에 노출되지 않습니다. YAML 문법 오류 시 카드가 빠질 수 있으니 yamllint.com으로 검증해 보세요.

macOS/Linux에서도 쓸 수 있나요?

네. start.bat은 Windows 더블클릭 진입용이고, macOS/Linux에서는 터미널에서 직접 실행하시면 됩니다. 

# 1) 저장소 클론
git clone https://github.com/wndnjs3865/flowagent.git
cd flowagent

# 2) 의존성 설치 (pnpm 권장)
pnpm install

# 3) .env 설정 후 실행
cp .env.example .env   # ANTHROPIC_API_KEY= 채우기
pnpm dev               # http://localhost:3000

PORT=3001 pnpm dev처럼 환경변수로 포트도 바꿀 수 있습니다.

회사 데이터는 노트북 안에만.
한국어 사무 자동화, 5종 워크플로 바로 시작.

풀 문서 사이트는 v0.2.0 이후 확장 예정. 그때까지 GitHub README와 이 페이지로 안내해드려요.

GitHub README ↗ 무료 다운로드