Flaq AI 에이전트 가이드

Flaq AI의 OpenAI 호환 API로 DeepSeek Harness를 사용하는 실용 가이드

Flaq AI의 OpenAI 호환 엔드포인트로 오픈 소스 DeepSeek Harness Web UI를 실행한 다음, 지원되는 DeepSeek v4 모델을 연결하여 저장소 분석 및 코딩 워크플로에 활용하세요. DeepSeek Harness는 “모든 것이 플러그인”인 아키텍처를 따르므로 모델 어댑터, 도구, 에이전트 루프, 세션 저장소, 권한, 샌드박싱, 텔레메트리, Web UI를 플러그인과 설정을 통해 조합하거나 교체할 수 있습니다.

에이전트 가이드

Claude Code/cc-apiOpenAI Codex/codex-api/v1Hermes Agent/api/v1DeepSeek Harness/api/v1ZCode/api/v1

설치

DeepSeek Harness 실행하기

DeepSeek Harness에는 Node.js 22.19 이상 또는 24 이상의 릴리스가 필요합니다. 기본 파일 시스템 위치로 사용할 프로젝트 디렉터리에서 실행하세요. 공식 npm 명령은 기본적으로 http://127.0.0.1:3080에서 Web UI를 시작합니다.

1

DeepSeek Harness Web UI 실행하기

공식 npm 패키지를 사용하여 Web UI를 시작하세요. DeepSeek Harness를 사용하는 동안 이 터미널을 계속 실행해 두세요.

처음 실행하면 현재 @deepseek-ai/dsh 패키지를 다운로드하고 Web UI 프로필을 초기화합니다.

공식 npm 명령

npx @deepseek-ai/dsh web

저장소: 최신 설치 안내, 릴리스, 호환성 참고 사항 및 소스 코드는 공식 DeepSeek Harness GitHub 저장소에서 확인하세요.

설정

DeepSeek Harness를 Flaq AI에 연결하기

DeepSeek Harness에서 Settings → Models를 열고 Flaq AI를 사용자 지정 공급자로 추가한 후 Flaq API 키를 입력하세요. Provider ID는 저장한 뒤에는 변경할 수 없으므로 의도적으로 다른 경로 이름이 필요한 경우가 아니라면 flaq를 사용하세요. 공급자를 저장한 후 세션을 시작하기 전에 워크스페이스를 선택하세요.

더 강력한 추론이 유용한 저장소 분석, 코딩 작업 및 워크플로에 권장되는 DeepSeek v4 Pro 모델입니다.

Settings → Models에서 Add provider → Add a custom provider를 선택하세요. 아래 값을 입력하고 Fetch available models를 사용하지 말고 선택한 모델 ID를 직접 추가하세요. 공급자를 저장한 다음 새 세션에서 해당 모델을 선택하세요. 추가 모달리티를 선언하지 않으면 DeepSeek Harness는 직접 입력한 모델을 텍스트 전용으로 취급합니다.

  • Flaq 기본 URL과 openai-completions 프로토콜을 정확히 사용하세요.
  • 자리표시자를 Flaq API 키로 바꾸고 모델 ID는 표시된 그대로 유지하세요.

Flaq AI 사용자 지정 공급자

Provider ID: flaqDisplay name: Flaq AIBase URL: https://api.flaq.ai/api/v1API protocol: openai-completionsCredential / API key: Your_Flaq_Api_KeyModel ID: deepseek-v4-pro-text-to-text

검증

DeepSeek Harness에서 Flaq 확인하기

Web UI를 열고 DeepSeek Harness를 시작한 프로젝트 디렉터리를 선택한 다음, 구성된 Flaq 모델을 선택하고 새 세션을 만드세요. 워크스페이스를 선택하기 전에는 작성기를 사용할 수 없습니다.

  • DeepSeek Harness는 활성 URL을 터미널에 출력합니다.
  • 기본 로컬 주소는 아래와 같습니다.

Web UI 열기

http://127.0.0.1:3080
  • 먼저 읽기 전용 작업을 보내세요.
  • 선택한 워크스페이스를 반영하는 정상적인 답변이 오면 DeepSeek Harness가 Flaq 엔드포인트에 접근하고 구성된 모델을 사용할 수 있음을 확인할 수 있습니다.

저장소 접근 테스트하기

Summarize this repository and identify its main packages. Do not modify any files.

플러그인 예시

DeepSeek Harness 플러그인 설치하기

DeepSeek Harness의 “모든 것이 플러그인”인 아키텍처를 보여 주는 구체적인 예로 DSH OpenPencil을 사용하세요. 위의 Flaq 공급자 구성과 확인을 완료하고, 실행 중인 Web UI를 중지한 다음, web 프로필에 플러그인을 추가하고 동일한 DeepSeek Harness 버전을 다시 시작하세요. DSH OpenPencil은 대화 안에서 .op 디자인 문서를 생성하고, 미리 보고, 검사하고, 편집하는 도구를 추가합니다.

1

DSH OpenPencil 설치하기

플러그인에서 현재 테스트한 DeepSeek Harness 버전으로 공개 OpenPencil 패키지를 web 프로필에 추가하세요. DeepSeek Harness에 사용하는 것과 동일한 프로젝트 디렉터리에서 이 명령을 실행하세요.

DSH OpenPencil 설치하기

npx --yes -p @deepseek-ai/[email protected] dsh plugin --profile web add @zseven-w/dsh-openpencil@latest

저장소: 소스 코드, 설정 요구 사항, 릴리스 및 호환성 참고 사항은 DSH OpenPencil GitHub 저장소에서 확인하세요.

2

Web UI 다시 시작하기

테스트한 DeepSeek Harness 버전을 다시 시작하여 web 프로필이 DSH OpenPencil을 로드하도록 하세요. Web UI를 다시 여는 동안 이 터미널을 계속 실행해 두세요.

Web UI 다시 시작하기

npx --yes -p @deepseek-ai/[email protected] dsh web
3

Flaq AI로 DSH OpenPencil 테스트하기

구성된 Flaq 모델과 워크스페이스를 선택하고 새 세션을 시작한 다음 아래 요청을 보내세요. OpenPencil 바이너리를 사용할 수 있으면 플러그인이 .op 문서를 만들고 대화에 편집 가능한 미리 보기를 표시합니다.

Flaq AI로 DSH OpenPencil 테스트하기

Create a simple editable OpenPencil document with a title, a subtitle, and two feature cards. Save it as openpencil-demo.op, then render an editable preview.

오픈 소스

공식 DeepSeek Harness 저장소 살펴보기

DeepSeek Harness는 DeepSeek AI에서 개발한 오픈 소스 에이전트 하네스입니다. 공식 저장소에서 소스 코드를 검토하고, 릴리스와 호환성 변경 사항을 확인하며, 최신 문서를 읽고, 개발자 프리뷰 중 발생한 문제를 보고할 수 있습니다.

GitHub의 DeepSeek Harness

소스 코드, 설정 문서, 개발 참고 사항, 토론 및 프로젝트 업데이트를 확인하려면 공식 DeepSeek Harness 저장소를 여세요.

오픈 소스 가이드

Flaq AI의 오픈 소스 DeepSeek Harness 가이드 살펴보기

초기 설정을 넘어 Flaq AI가 독립적으로 커뮤니티에서 관리하는 DeepSeek Harness 가이드를 활용하세요. 플러그인 트리, 프로필, 번들, 패치 레이어, 교체 가능한 에이전트 루프, 모델 어댑터, 도구, 세션 서비스, 권한 정책, 샌드박스 및 Web UI 확장 기능이 사용자 지정 에이전트 워크플로를 어떻게 지원하는지 알아볼 수 있습니다.

GitHub의 DeepSeek Harness 가이드

DeepSeek Harness를 이해하고 확장하며 이를 기반으로 개발하기 위한 실용적인 아키텍처 참고 사항, 사용 안내서, 플러그인 개발 레시피, 다국어 문서 및 재사용 가능한 에이전트 스킬을 살펴보세요.

문제 해결

DeepSeek Harness 자주 묻는 질문

이 가이드의 설정으로 사용할 경우 token 사용량이 크게 늘어날 수 있습니다.

X(Twitter)의 DeepSeek Harness 토론

오픈 소스 에이전트 하네스인 DeepSeek Harness(DSH)에 관해 개발자와 초기 참여자들이 나누는 토론을 살펴보세요. “모든 것이 플러그인”인 아키텍처, 조합 가능한 런타임, 플러그인 생태계 및 실제 사용 경험을 다룹니다.