OpenHarness

KO | EN

gitlite — search

#react #ai #llm #golang #android #deep-learning #docker #macos #nodejs #windows #awesome #cli #openai #mcp

(★ 15,392)

"OpenHarness: Open Agent Harness with a Built-in Personal Agent--Ohmo!"

OpenHarness 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# OpenHarness    ohmo `oh` — OpenHarness & `ohmo`

[**English**](README.md) ·
[**简体中文**](README.zh-CN.md)

\*\*OpenHarness\*\*는 도구 사용, 스킬, 메모리, 멀티 에이전트 조율 등 핵심 경량 에이전트 인프라를 제공합니다.
\*\*ohmo\*\*는 OpenHarness를 기반으로 구축된 개인용 AI 에이전트입니다. 단순한 챗봇이 아니라, 오랜 세션 동안 여러분을 위해 실제로 일하는 어시스턴트입니다. Feishu / Slack / Telegram / Discord에서 ohmo와 대화하면, 스스로 브랜치를 파고, 코드를 작성하고, 테스트를 실행하며, PR을 엽니다. ohmo는 기존 Claude Code 또는 Codex 구독으로 실행되므로 별도의 API 키가 필요하지 않습니다.
\*\*커뮤니티에 참여하세요\*\*: 오픈 에이전트 개발을 위한 \*\*Harness\*\*를 기여해 주세요.

[![Quick Start](https://img.shields.io/badge/Quick_Start-5_min-blue?style=for-the-badge)](#-quick-start)
[![Architecture](https://img.shields.io/badge/Harness-Architecture-ff69b4?style=for-the-badge)](#-harness-architecture)
[![Tools](https://img.shields.io/badge/Tools-43+-green?style=for-the-badge)](#-features)
[![Tests](https://img.shields.io/badge/Tests-114_Passing-brightgreen?style=for-the-badge)](#-test-results)
[![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](LICENSE)

![Python](https://img.shields.io/badge/python-≥3.10-blue?logo=python&logoColor=white)
![React](https://img.shields.io/badge/React+Ink-TUI-61DAFB?logo=react&logoColor=white)
![Pytest](https://img.shields.io/badge/pytest-114_pass-brightgreen)
![E2E](https://img.shields.io/badge/E2E-6_suites-orange)
![Output](https://img.shields.io/badge/output-text_|_json_|_stream--json-blueviolet)
[![CI](https://github.com/HKUDS/OpenHarness/actions/workflows/ci.yml/badge.svg)](https://github.com/HKUDS/OpenHarness/actions/workflows/ci.yml)
[![Feishu](https://img.shields.io/badge/Feishu-Group-E9DBFC?style=flat&logo=feishu&logoColor=white)](https://github.com/HKUDS/.github/blob/main/profile/README.md)
[![WeChat](https://img.shields.io/badge/WeChat-Group-C5EAB4?style=flat&logo=wechat&logoColor=white)](https://github.com/HKUDS/.github/blob/main/profile/README.md)

단 하나의 명령어(\*\*oh\*\*)로 \*\*OpenHarness\*\*를 실행하고 모든 에이전트 Harness를 잠금 해제하세요.
OpenClaw, nanobot, Cursor 등을 포함한 CLI 에이전트 통합을 지원합니다.

![OpenHarness Terminal Demo](assets/cli-typing.gif)

---
## ✨ OpenHarness의 주요 Harness 기능

|  |  |  |  |  |
| --- | --- | --- | --- | --- |
| 🔄 Agent Loop Engine  **• 스트리밍 툴콜 주기**  **• 지수 백오프를사용한 API 재시도**  **• 병렬 도구 실행**  **• 토큰 카운팅 및 비용 추적** | 🔧 Harness Toolkit Toolkit  **• 43개의 도구 (파일, 셸, 검색, 웹, MCP)**  **• 온디맨드 스킬 로딩 (.md)**  **• 플러그인 생태계 (스킬 + 훅 + 에이전트)**  **• anthropics/skills 및 플러그인과 호환** | 🧠 Context & Memory Context  **• CLAUDE.md 발견 및 주입**  **• 컨텍스트 압축 (자동 컴팩트)**  **• MEMORY.md 영구 메모리**  **• 세션 재개 및 기록** | 🛡️ Governance Governance  **• 다단 권한 모드**  **• 경로 수준 및 명령어 규칙**  **• PreToolUse / PostToolUse 훅**  **• 대화형 승인 대화상자** | 🤝 Swarm Coordination Swarm  **• 서브에이전트 생성 및 위임**  **• 팀 레지스트리 및 작업 관리**  **• 백그라운드 작업 생명주기**  **• [ClawTeam](https://github.com/HKUDS/ClawTeam) 통합 (로드맵)** |

---
## 🤔 에이전트 Harness란 무엇인가요?
\*\*에이전트 Harness\*\*는 LLM을 감싸서 기능적인 에이전트로 만들어 주는 완전한 인프라입니다. 모델이 지능을 제공한다면, harness는 \*\*손, 눈, 메모리, 그리고 안전 경계\*\*를 제공합니다.

![Harness = Tools + Knowledge + Observation + Action + Permissions](assets/harness-equation.png)

OpenHarness는 \*\*연구원, 개발자 및 커뮤니티\*\*를 위해 설계된 오픈소스 Python 구현체입니다.
- 프로덕션 AI 에이전트가 내부적으로 작동하는 방식을 \*\*이해(Understand)\*\*할 수 있습니다.
- 최첨단 도구, 스킬, 에이전트 조정 패턴을 \*\* 실험(Experiment)\*\*할 수 있습니다.
- 커스텀 플러그인, 프로바이더, 도메인 지식을 통해 하네스를 \*\*확장(Extend)\*\*할 수 있습니다.
- 검증된 아키텍처를 바탕으로 특화된 에이전트를 \*\*구축(Build)\*\*할 수 있습니다.
---
## 📰 새로운 소식
- \*\*미출시(Unreleased)\*\* 🔍 \*\*드라이런 안전 미리보기(Dry-run safe preview)\*\*:
- `oh --dry-run`은 모델, 도구, 서브에이전트를 실행하지 않고도 해결된 런타임 설정, 인증 상태, 스킬, 명령어, 도구, 설정된 MCP 서버를 미리 보여줍니다.
- 이제 드라이런은 인증 수정, MCP 설정 수정, 프롬프트 직접 실행 등 구체적인 다음 단계 제안과 함께 `ready` / `warning` / `blocked` 준비 상태 판정을 보고합니다.
- 프롬프트 미리보기에는 일치할 가능성이 높은 스킬과 도구가 포함되며, 슬래시 명령어 미리보기는 해당 명령어가 주로 읽기 전용인지 상태를 유지하는지 보여줍니다.
- \*\*2026-04-18\*\* ⚙️ \*\*v0.1.7\*\* — 패키징 및 TUI 개선:
- 이제 설치 스크립트는 가상환경의 `bin` 디렉토리를 `PATH`에 앞에 추가하는 대신 `oh`, `ohmo`, `openharness`를 `~/.local/bin`에 심볼릭 링크하여 Conda가 관리하는 셸이 손상되는 것을 방지합니다.
- React TUI는 일반 `Enter`는 제출용으로 유지하면서 `Shift+Enter`로 줄바꿈을 삽입하는 기능을 지원합니다.
- React TUI의 작업 중 상태 애니메이션은 보수적인 스피너 프레임과 줄어든 깜빡임 덕분에 Windows 터미널에서 더 조용하고 오류가 적습니다.
- \*\*2026-04-10\*\* 🧠 \*\*v0.1.6\*\* — 자동 압축 및 Markdown TUI:
- 자동 압축(Auto-Compaction)은 컨텍스트 압축 전반에 걸쳐 작업 상태와 채널 로그를 보존합니다. 에이전트는 수동 압축/지우기 없이 며칠 동안 세션을 실행할 수 있습니다.
- 서브프로세스 팀원들이 헤드리스 워커 모드로 실행되며, 에이전트 팀 생성이 안정화되었습니다.
- 이제 어시스턴트 메시지가 React TUI에서 전체 Markdown을 렌더링합니다.
- `ohmo`에 채널 슬래시 명령어와 멀티모달 첨부 파일 지원이 추가되었습니다.
- \*\*2026-04-08\*\* 🔌 \*\*v0.1.5\*\* — MCP HTTP 전송 및 Swarm 폴링:
- MCP 프로토콜에 HTTP 전송, 연결 끊김 시 자동 재연결, 도구 전용 서버 호환성이 추가되었습니다.
- 수동 타입 매핑 없이 MCP 도구 입력을 위한 JSON Schema 타입이 추론됩니다.
- `ohmo` 채널이 파일 첨부 파일 및 멀티모달 게이트웨이 메시지를 지원합니다.
- 실제 실행 시 서브프로세스 에이전트를 이제 폴링할 수 있으며, 입력이 무시되는 것을 방지하기 위해 권한 모달이 직렬화되었습니다.
- \*\*2026-04-08\*\* 🌙 \*\*v0.1.4\*\* — 멀티 프로바이더 인증 및 Moonshot/Kimi:
- 사고(thinking) 모델을 위한 `reasoning\_content`를 지원하는 네이티브 Moonshot/Kimi 프로바이더
- 인증 전면 개선: 프로바이더 전환 키 불일치 수정, `OPENAI\_BASE\_URL` 환경 변수 오버라이드, 프로필 범위 자격 증명 우선순위 설정
- `call\_tool` / `read\_resource`에서 MCP가 연결이 끊긴 서버를 정상적으로 처리
- 보안: PermissionChecker에 내장된 민감한 경로 보호, 강화된 `web\_fetch` URL 유효성 검사
- 안정성: Ink TUI의 EIO 충돌 복구, `--debug` 로깅, Windows cmd 깜빡임 수정
- \*\*2026-04-06\*\* 🚀 \*\*v0.1.2\*\* — 통합 설정 흐름 및 `ohmo` 개인 에이전트 앱:
- `oh setup`은 이제 원시 인증/프로바이더 내부 구조를 노출하는 대신 워크플로우로 프로바이더 선택을 안내합니다.
- 호환 가능한 API 설정이 이제 프로필 범위로 지정되므로 Anthropic/OpenAI 호환 엔드포인트가 별도의 키를 유지할 수 있습니다.
- `ohmo`는 `~/.ohmo` 워크スペース, 게이트웨이, 부트스트랩 프롬프트 및 채널 설정 흐름이 포함된 패키지 앱으로 제공됩니다.
- \*\*2026-04-01\*\* 🎨 \*\*v0.1.0\*\* — 완전한 하네스 아키텍처를 특징으로 하는 초기 \*\*OpenHarness\*\* 오픈소스 출시:

**여기서 시작하세요:**
[빠른 시작](#-quick-start) ·
[프로바이더 호환성](#-provider-compatibility) ·
[쇼케이스](docs/SHOWCASE.md) ·
[기여하기](CONTRIBUTING.md) ·
[변경 로그](CHANGELOG.md)

---
## 🚀 빠른 시작
### 1. 설치
#### Linux / macOS / WSL
```bash
# One-click install
curl -fsSL https://raw.githubusercontent.com/HKUDS/OpenHarness/main/scripts/install.sh | bash
# Or via pip
pip install openharness-ai
```
#### Windows (네이티브)
```powershell
# One-click install (PowerShell)
iex (Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/HKUDS/OpenHarness/main/scripts/install.ps1')
# Or via pip
pip install openharness-ai
```
\*\*참고\*\*: 이제 Windows가 네이티브로 지원됩니다. PowerShell에서는 `oh`가 내장 `Out-Host` 별칭으로 해석될 수 있으므로 `oh` 대신 `openh`를 사용하세요.
### 2. 설정
```bash
oh setup # interactive wizard — pick a provider, authenticate, done
# On Windows PowerShell, use: openh setup
```
\*\*Claude / OpenAI / Copilot / Codex / Moonshot(Kimi) / GLM / MiniMax / NVIDIA NIM\*\* 및 기타 호환 가능한 엔드포인트를 지원합니다.
### 3. 실행
```bash
oh
# On Windows PowerShell, use: openh
```

![OpenHarness Landing Screen](assets/landing.png)

### 4. ohmo 설정하기 (퍼스널 에이전트)
Feishu / Slack / Telegram / Discord에서 나를 위해 일하는 AI 에이전트를 원하시나요?
```bash
ohmo init # ~/.ohmo 워크스페이스 초기화
ohmo config # 채널 및 프로바이더 설정
ohmo gateway start # 게이트웨이 시작 — 이제 채팅 앱에서 ohmo를 사용할 수 있습니다
```
ohmo는 기존의 \*\*Claude Code 구독\*\* 또는 \*\*Codex 구독\*\*으로 실행되므로 별도의 API 키가 필요 없습니다.
### 비대화형 모드 (파이프 및 스크립트)
```bash
# 단일 프롬프트 → stdout
oh -p "Explain this codebase"
# 프로그래밍 방식으로 사용하기 위한 JSON 출력
oh -p "List all functions in main.py" --output-format json
# 실시간으로 JSON 이벤트 스트리밍
oh -p "Fix the bug" --output-format stream-json
```
### 드라이런 (안전한 미리보기)
실제 실행이 시작되기 전에 OpenHarness가 무엇을 사용할지 검사하고 싶을 때 `--dry-run`을 사용하세요.
```bash
# 대화형 세션 설정 미리보기
oh --dry-run
# 모델이나 도구를 실행하지 않고 하나의 프롬프트 미리보기
oh --dry-run -p "Review this bug fix and grep for failing tests"
# 슬래시 명령어 경로 미리보기
oh --dry-run -p "/plugin list"
# 스크립트나 채널용 구조화된 출력 가져오기
oh --dry-run -p "Explain this repository" --output-format json
```
드라이런은 의도적으로 정적입니다:
- 모델을 호출하지 \*\*않습니다\*\*
- 도구를 실행하거나 하위 에이전트를 생성하지 \*\*않습니다\*\*
- MCP 서버에 연결하지 \*\*않습니다\*\*
- 설정, 인증 상태, 프롬프트 조합, 스킬, 명령어, 도구 및 명백한 MCP 설정 문제를 해결(\*\*합니다\*\*)
준비 수준(Readiness levels):
- `ready`: 설정이 사용 가능해 보입니다. 다음 권장 작업은 대개 프롬프트를 직접 실행하는 것입니다.
- `warning`: OpenHarness가 세션을 해결할 수 있지만, 손상된 MCP 설정이나 추후 모델 작업을 위한 인증 누락 등 여전히 잘못되어 보이는 중요한 부분이 있습니다.
- `blocked`: 알 수 없는 슬래시 명령어이나 런타임 클라이언트를 해결할 수 없는 프롬프트 등, 요청된 경로가 현재 상태로는 성공적으로 실행되지 않습니다.
드라이런 출력의 `next actions`는 다음과 같은 가장 빠른 수정 방법이나 후속 조치 단계를 알려줍니다:
- `oh auth login` 실행
- 손상된 MCP 설정 수정 또는 비활성화
- `oh -p "..."`로 프롬프트를 직접 실행하거나 `oh`로 대화형 UI 열기
## 🔌 프로바이더 호환성
OpenHarness는 프로바이더를 명명된 프로필이 뒷받침하는 \*\*워크플로우\*\*로 취급합니다. 일상적인 사용 시 다음을 선호합니다:
```bash
oh setup
oh provider list
oh provider use 
```
### 내장 워크플로우
| 워크플로우 | 설명 | 일반적인 백엔드 |
|----------|------------|------------------|
| \*\*Anthropic 호환 API\*\* | Anthropic 스타일 요청 형식 | Claude 공식, Kimi, GLM, MiniMax, 내부 Anthropic 호환 게이트웨이 |
| \*\*Claude 구독\*\* | Claude CLI 구독 브리지 | 로컬 `~/.claude/.credentials.json` |
| \*\*OpenAI 호환 API\*\* | OpenAI 스타일 요청 형식 | OpenAI 공식, OpenRouter, DashScope, DeepSeek, SiliconFlow, Groq, Ollama, GitHub Models |
| \*\*Codex 구독\*\* | Codex CLI 구독 브리지 | 로컬 `~/.codex/auth.json` |
| \*\*GitHub Copilot\*\* | Copilot OAuth 워크플로우 | GitHub Copilot 기기 흐름(device-flow) 로그인 |
### 호환되는 API 패밀리
#### Anthropic 호환 API
일반적인 예시:
| 백엔드 | 베이스 URL | 예시 모델 |
|---------|----------|----------------|
| \*\*Claude 공식\*\* | `https://api.anthropic.com` | `claude-sonnet-4-6`, `claude-opus-4-6` |
| \*\*Moonshot / Kimi\*\* | `https://api.moonshot.cn/anthropic` | `kimi-k2.5` |
| \*\*Zhipu / GLM\*\* | 사용자 지정 Anthropic 호환 엔드포인트 | `glm-4.5` |
| \*\*MiniMax\*\* | 사용자 지정 Anthropic 호환 엔드포인트 | `minimax-m1` |
#### OpenAI 호환 API
OpenAI `/v1/chat/completions` 스타일 API를 구현하는 모든 프로바이더가 작동합니다:
| 백엔드 | 베이스 URL | 예시 모델 |
|---------|----------|----------------|
| \*\*OpenAI\*\* | `https://api.openai.com/v1` | `gpt-5.4`, `gpt-4.1` |
| \*\*OpenRouter\*\* | `https://openrouter.ai/api/v1` | 프로바이더별 지정 |
| \*\*Alibaba DashScope\*\* | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen3.5-flash`, `qwen3-max`, `deepseek-r1` |
| \*\*DeepSeek\*\* | `https://

api.deepseek.com` | `deepseek-chat`, `deepseek-reasoner` |
| \*\*GitHub Models\*\* | `https://models.inference.ai.azure.com` | `gpt-4o`, `Meta-Llama-3.1-405B-Instruct` |
| \*\*SiliconFlow\*\* | `https://api.siliconflow.cn/v1` | `deepseek-ai/DeepSeek-V3` |
| \*\*NVIDIA NIM\*\* | `https://integrate.api.nvidia.com/v1` | `openai/gpt-oss-120b`, `nvidia/llama-3.3-nemotron-super-49b-v1` |
| \*\*Google Gemini\*\* | `https://generativelanguage.googleapis.com/v1beta/openai` | `gemini-2.5-flash`, `gemini-2.5-pro` |
| \*\*Groq\*\* | `https://api.groq.com/openai/v1` | `llama-3.3-70b-versatile` |
| \*\*Ollama (local)\*\* | `http://localhost:11434/v1` | 모든 로컬 모델 |
### 고급 프로필 관리
```bash
# List saved workflows
oh provider list
# Switch the active workflow
oh provider use codex
# Add your own compatible endpoint
oh provider add my-endpoint \
--label "My Endpoint" \
--provider openai \
--api-format openai \
--auth-source openai\_api\_key \
--model my-model \
--base-url https://example.com/v1
```
커스텀 호환 엔드포인트의 경우, OpenHarness는 모든 Anthropic 호환 또는 OpenAI 호환 백엔드가 동일한 API 키를 공유하도록 강제하는 대신 프로필별로 자격 증명을 바인딩할 수 있습니다.
### Ollama (로컬 모델)
Ollama의 OpenAI 호환 엔드포인트를 통해 로컬 모델을 실행합니다:
```bash
# Add an Ollama provider profile
oh provider add ollama \
--label "Ollama" \
--provider Ollama \
--api-format openai \
--auth-source openai\_api\_key \
--model glm-4.7-flash:q8\_0 \
--base-url http://localhost:11434/v1
```
```
Saved provider profile: ollama
```
```bash
# Activate and verify
oh provider use ollama
```
```
Activated provider profile: ollama
```
```bash
oh provider list
```
```
claude-api: Anthropic-Compatible API [ready]
...
moonshot: Moonshot (Kimi) [missing auth]
auth=moonshot\_api\_key model=kimi-k2.5 base\_url=https://api.moonshot.cn/v1
\* ollama: Ollama [ready]
auth=openai\_api\_key model=glm-4.7-flash:q8\_0 base\_url=http://localhost:11434/v1
```
### GitHub Copilot 형식 (`--api-format copilot`)
기존 GitHub Copilot 구독을 LLM 백엔드로 사용하세요. 인증은 GitHub의 OAuth 디바이스 플로우를 사용하므로 API 키가 필요 없습니다.
```bash
# One-time login (opens browser for GitHub authorization)
oh auth copilot-login
# Then launch with Copilot as the provider
uv run oh --api-format copilot
# Or via environment variable
export OPENHARNESS\_API\_FORMAT=copilot
uv run oh
# Check auth status
oh auth status
# Remove stored credentials
oh auth copilot-logout
```
| 기능 | 세부 정보 |
|---------|---------|
| \*\*인증 방법\*\* | GitHub OAuth 디바이스 플로우 (API 키 불필요) |
| \*\*토큰 관리\*\* | 수명이 짧은 세션 토큰 자동 갱신 |
| \*\*엔터프라이즈\*\* | `--github-domain` 플래그를 통한 GitHub Enterprise 지원 |
| \*\*모델\*\* | Copilot의 기본 모델 선택 사용 |
| \*\*API\*\* | 내부적으로 OpenAI 호환 채팅 완성(chat completions) 사용 |
---
## 🏗️ 하니스 아키텍처
OpenHarness는 10개의 서브시스템을 갖춘 핵심 에이전트 하니스 패턴을 구현합니다:
```
openharness/
engine/ # 🧠 Agent Loop — query → stream → tool-call → loop
tools/ # 🔧 43 Tools — file I/O, shell, search, web, MCP
skills/ # 📚 Knowledge — on-demand skill loading (.md files)
plugins/ # 🔌 Extensions — commands, hooks, agents, MCP servers
permissions/ # 🛡️ Safety — multi-level modes, path rules, command deny
hooks/ # ⚡ Lifecycle — PreToolUse/PostToolUse event hooks
commands/ # 💬 54 Commands — /help, /commit, /plan, /resume, ...
mcp/ # 🌐 MCP — Model Context Protocol client
memory/ # 🧠 Memory — persistent cross-session knowledge
tasks/ # 📋 Tasks — background task management
coordinator/ # 🤝 Multi-Agent — subagent spawning, team coordination
prompts/ # 📝 Context — system prompt assembly, CLAUDE.md, skills
config/ # ⚙️ Settings — multi-layer config, migrations
ui/ # 🖥️ React TUI — backend protocol + frontend
```
### 에이전트 루프
하니스의 심장부. 끝없이 조합 가능한 단일 루프:
```python
while True:
response = await api.stream(messages, tools)
if response.stop\_reason !=

"tool\_use":
break # 모델 작업 완료
for tool\_call in response.tool\_uses:
# 권한 검사 → 훅(Hook) → 실행 → 훅(Hook) → 결과
result = await harness.execute\_tool(tool\_call)
messages.append(tool\_results)
# 루프 계속 진행 — 모델이 결과를 확인하고 다음 행동을 결정함
```
모델은 \*\*무엇을(what)\*\* 할지 결정합니다. 하네스(harness)는 안전하고 효율적으로, 완전한 관측 가능성을 바탕으로 \*\*어떻게(how)\*\* 할지를 처리합니다.
### 하네스 흐름 (Harness Flow)
```mermaid
flowchart LR
U[User Prompt] --> C[CLI or React TUI]
C --> R[RuntimeBundle]
R --> Q[QueryEngine]
Q --> A[Anthropic-compatible API Client]
A -->|tool\_use| T[Tool Registry]
T --> P[Permissions + Hooks]
P --> X[Files Shell Web MCP Tasks]
X --> Q
```
---
## ✨ 주요 기능
### 🔧 도구 (43개 이상)
| 카테고리 | 도구 | 설명 |
|----------|-------|-------------|
| \*\*File I/O\*\* | Bash, Read, Write, Edit, Glob, Grep | 권한 검사가 포함된 핵심 파일 연산 |
| \*\*Search\*\* | WebFetch, WebSearch, ToolSearch, LSP | 웹 및 코드 검색 기능 |
| \*\*Notebook\*\* | NotebookEdit | Jupyter 노트북 셀 편집 |
| \*\*Agent\*\* | Agent, SendMessage, TeamCreate/Delete | 하위 에이전트 생성 및 조정 |
| \*\*Task\*\* | TaskCreate/Get/List/Update/Stop/Output | 백그라운드 태스크 관리 |
| \*\*MCP\*\* | MCPTool, ListMcpResources, ReadMcpResource | Model Context Protocol 연동 |
| \*\*Mode\*\* | EnterPlanMode, ExitPlanMode, Worktree | 워크플로우 모드 전환 |
| \*\*Schedule\*\* | CronCreate/List/Delete, RemoteTrigger | 예약 및 원격 실행 |
| \*\*Meta\*\* | Skill, Config, Brief, Sleep, AskUser | 지식 로드, 설정, 상호작용 |
모든 도구의 공통 특징:
- \*\*Pydantic 입력 검증\*\* — 구조화되고 타입 안전한 입력
- \*\*자체 설명형 JSON Schema\*\* — 모델이 도구를 자동으로 이해
- \*\*권한 통합\*\* — 모든 실행 전에 검사 수행
- \*\*훅(Hook) 지원\*\* — PreToolUse/PostToolUse 라이프사이클 이벤트
### 📚 스킬 시스템 (Skills System)
스킬은 모델이 필요할 때만 로드되는 \*\*온디맨드 지식(on-demand knowledge)\*\*입니다:
```
사용 가능한 스킬:
- commit: 깔끔하고 구조화된 git 커밋 생성
- review: 버그, 보안 문제, 품질 측면의 코드 리뷰
- debug: 체계적인 버그 진단 및 수정
- plan: 코딩 전 구현 계획 설계
- test: 코드를 위한 테스트 작성 및 실행
- simplify: 더 간단하고 유지보수하기 쉬운 코드로 리팩토링
- pdf: pypdf를 활용한 PDF 처리 (anthropics/skills 제공)
- xlsx: Excel 연산 (anthropics/skills 제공)
- ... 40개 이상 추가
```
스킬은 번들, 사용자, ohmo, 프로젝트 또는 플러그인 디렉토리에 위치할 수 있습니다. 사용자 레벨 스킬은 다음 경로에서 로드됩니다:
```text
~/.openharness/skills//SKILL.md
~/.claude/skills//SKILL.md
~/.agents/skills//SKILL.md
```
프로젝트 레벨 스킬은 기본적으로 활성화되어 있으며, 현재 작업 디렉토리부터 git 루트까지 탐색됩니다:
```text
/.openharness/skills//SKILL.md
/.agents/skills//SKILL.md
/.claude/skills//SKILL.md
```
신뢰할 수 없는 저장소의 경우 다음 명령어로 프로젝트 스킬을 비활성화할 수 있습니다:
```bash
oh config set allow\_project\_skills false
```
`/skills`를 사용하여 로드된 스킬의 소스와 경로를 확인할 수 있습니다. 사용자가 직접 호출할 수 있는 스킬은 `/deploy staging`과 같이 슬래시 명령어로 바로 실행할 수 있습니다.
\*\*[anthropics/skills](https://github.com/anthropics/skills)와 호환됨\*\* — 위의 `SKILL.md` 디렉토리 구조를 사용하세요.
### 🌐 웹 검색 및 프록시 설정
기본 내장된 `web\_search`는 DuckDuckGo HTML 검색을 기본으로 사용합니다. 해당 엔드포인트에 접근할 수 없는 지역에서는 OpenHarness를 신뢰할 수 있는 공용 HTML 검색 엔드포인트나 자체 SearXNG 인스턴스로 지정하세요:
```bash
export OPENHARNESS\_WEB\_SEARCH\_URL="https://your-searxng.example/search"
```
`web\_search`와 `web\_fetch`는 SSRF 안전을 위해 `trust\_env=False`를 유지하므로, `HTTP\_PROXY` / `HTTPS\_PROXY`를 자동으로 상속하지 않습니다. 프록시가 필요한 경우 OpenHarness 전용 변수를 설정하여 활성화하세요:
```bash
export OPENHARNESS\_WEB\_PROXY="http://127.0.0.1:7890"
```
프록시 URL은 HTTP/HTTPS여야 하며 내부에 자격 증명(credentials)을 포함할 수 없습니다.
### 🔌 플러그인 시스템
\*\*[claude-code plugins](https://gi

thub.com/anthropics/claude-code/tree/main/plugins)\*\*. 12개의 공식 플러그인으로 테스트 완료:
| 플러그인 | 유형 | 기능 |
|--------|------|-------------|
| `commit-commands` | 명령어 | Git 커밋, 푸시, PR 워크플로우 |
| `security-guidance` | 훅 | 파일 수정 시 보안 경고 |
| `hookify` | 명령어 + 에이전트 | 커스텀 동작 훅 생성 |
| `feature-dev` | 명령어 | 기능 개발 워크플로우 |
| `code-review` | 에이전트 | 멀티 에이전트 PR 리뷰 |
| `pr-review-toolkit` | 에이전트 | 특화된 PR 리뷰 에이전트 |
```bash
# Manage plugins
oh plugin list
oh plugin install 
oh plugin enable 
```
### 🤝 생태계 워크플로우
OpenHarness는 Claude 스타일의 툴링 컨벤션을 감싸는 경량 하니스 계층으로 유용합니다:
- \*\*OpenClaw 지향 워크플로우\*\*는 마크다운 우선 지식과 명령어 기반 협업 패턴을 재사용할 수 있습니다.
- \*\*Claude 스타일 플러그인 및 스킬\*\*은 OpenHarness가 해당 형식들을 친숙하게 유지해주므로 이식성이 유지됩니다.
- \*\*ClawTeam 스타일 멀티 에이전트 작업\*\*은 내장된 팀, 태스크, 백그라운드 실행 프리미티브와 잘 맞아떨어집니다.
추상적인 주장 대신 구체적인 사용 아이디어를 보려면 [`docs/SHOWCASE.md`](docs/SHOWCASE.md)를 참고하세요.
### 🛡️ 권한
세밀한 제어가 가능한 다단계 안전 기능:
| 모드 | 동작 | 사용 사례 |
|------|----------|----------|
| \*\*기본값 (Default)\*\* | 쓰기/실행 전 확인 | 일상적인 개발 |
| \*\*자동 (Auto)\*\* | 모든 것 허용 | 샌드박스 환경 |
| \*\*계획 모드 (Plan Mode)\*\* | 모든 쓰기 차단 | 대규모 리팩토링, 사전 검토 |
`settings.json`의 \*\*경로 수준 규칙 (Path-level rules)\*\*:
```json
{
"permission": {
"mode": "default",
"path\_rules": [{"pattern": "/etc/\*", "allow": false}],
"denied\_commands": ["rm -rf /", "DROP TABLE \*"]
}
}
```
### 🖥️ 터미널 UI
완벽한 대화형 경험을 제공하는 React/Ink TUI:
- \*\*명령어 선택기\*\*: `/` 입력 → 방향키로 선택 → Enter
- \*\*권한 대화상자\*\*: 툴 세부 정보가 포함된 대화형 y/n
- \*\*모드 전환기\*\*: `/permissions` → 목록에서 선택
- \*\*세션 재개\*\*: `/resume` → 기록에서 선택
- \*\*애니메이션 스피너\*\*: 툴 실행 중 실시간 피드백
- \*\*키보드 단축키\*\*: 하단에 표시되며 컨텍스트 인식 가능
### 📡 CLI
```
oh [OPTIONS] COMMAND [ARGS]
Session: -c/--continue, -r/--resume, -n/--name
Model: -m/--model, --effort, --max-turns
Output: -p/--print, --output-format text|json|stream-json
Permissions: --permission-mode, --dangerously-skip-permissions
Context: -s/--system-prompt, --append-system-prompt, --settings
Advanced: -d/--debug, --mcp-config, --bare
Subcommands: oh setup | oh provider | oh auth | oh mcp | oh plugin
```
### 🧑‍💼 ohmo 퍼스널 에이전트
`ohmo`는 OpenHarness를 기반으로 구축된 퍼스널 에이전트 앱입니다. 자체 워크스페이스 및 게이트웨이와 함께 `oh`와 패키지로 제공됩니다:
```bash
# Initialize personal workspace
ohmo init
# Configure gateway channels and pick a provider profile
ohmo config
# Run the personal agent
ohmo
# Run the gateway in foreground
ohmo gateway run
# Check or restart the gateway
ohmo gateway status
ohmo gateway restart
```
핵심 개념:
- `~/.ohmo/`
- 퍼스널 워크스페이스 루트
- `soul.md`
- 장기적인 에이전트 성격 및 행동 양식
- `identity.md`
- `ohmo`의 정체성
- `user.md`
- 사용자 프로필 및 환경 설정
- `BOOTSTRAP.md`
- 최초 실행 시 랜딩 리추얼
- `memory/`
- 개인 기억
- `gateway.json`
- 선택된 프로바이더 프로필 및 채널 설정
`ohmo config`는 `oh setup`과 동일한 워크플로우 언어를 사용하므로, 퍼스널 에이전트 게이트웨이를 다음 대상으로 지정할 수 있습니다:
- `Anthropic-Compatible API`
- `Claude Subscription`
- `OpenAI-Compatible API`
- `Codex Subscription`
- `GitHub Copilot`
`ohmo init`은 홈 워크스페이스를 한 번 생성합니다. 그 이후에는 `ohmo config`를 사용하여 프로바이더 및 채널 설정을 업데이트할 수 있습니다. 게이트웨이가 이미 실행 중인 경우 설정 흐름을 통해 게이트웨이를 자동으로 재시작할 수 있습니다.
현재 `ohmo init` / `ohmo config`는 다음 플랫폼의 채널 설정을 지원합니다:
- Telegram
- Slack
- Discord
- Feishu
---
## 📊 테스트 결과
| 스위트 | 테스트 수 | 상태 |
|-------|-------|--------|
| 유닛 + 통합 | 114 | ✅ 모두 통과 |
| CLI 플래그 E2E | 6 | ✅ R

eal model calls |
| Harness Features E2E | 9 | ✅ 재시도, 스킬, 병렬, 권한 |
| React TUI E2E | 3 | ✅ 환영, 대화, 상태 |
| TUI Interactions E2E | 4 | ✅ 명령어, 권한, 단축키 |
| Real Skills + Plugins | 12 | ✅ anthropics/skills + claude-code/plugins |
```bash
# Run all tests
uv run pytest -q # 114 unit/integration
python scripts/test\_harness\_features.py # Harness E2E
python scripts/test\_real\_skills\_plugins.py # Real plugins E2E
```
---
## 🔧 OpenHarness 확장하기
### 커스텀 Tool 추가하기
```python
from pydantic import BaseModel, Field
from openharness.tools.base import BaseTool, ToolExecutionContext, ToolResult
class MyToolInput(BaseModel):
query: str = Field(description="Search query")
class MyTool(BaseTool):
name = "my\_tool"
description = "Does something useful"
input\_model = MyToolInput
async def execute(self, arguments: MyToolInput, context: ToolExecutionContext) -> ToolResult:
return ToolResult(output=f"Result for: {arguments.query}")
```
### 커스텀 Skill 추가하기
`~/.openharness/skills/my-skill.md` 파일을 생성합니다:
```markdown
---
name: my-skill
description: Expert guidance for my specific domain
---
# My Skill
## When to use
Use when the user asks about [your domain].
## Workflow
1. Step one
2. Step two
...
```
### Plugin 추가하기
`.openharness/plugins/my-plugin/.claude-plugin/plugin.json` 파일을 생성합니다:
```json
{
"name": "plugin-name",
"version": "1.0.0",
"description": "나만의 커스텀 플러그인"
}
```
`commands/\*.md`에 명령어를, `hooks/hooks.json`에 훅을, `agents/\*.md`에 에이전트를 추가하세요.
---
## 🌍 쇼케이스 (Showcase)
OpenHarness는 실제 워크플로우에 맞게 조정할 수 있는 작고 내부를 들여다볼 수 있는 하네스로 사용할 때 가장 유용합니다:
- 코드를 읽고, 파일을 패치하고, 로컬에서 검사를 실행하기 위한 \*\*저장소 코딩 어시스턴트\*\*
- 자동화 흐름에서 `json` 및 `stream-json` 출력을 위한 \*\*헤드리스 스크립팅 도구\*\*
- Claude 스타일의 확장을 실험하기 위한 \*\*플러그인 및 스킬 테스트베드\*\*
- 작업 위임 및 백그라운드 실행을 위한 \*\*멀티 에이전트 프로토타이핑 하네스\*\*
- Anthropic 호환 백엔드 전반의 \*\*프로바이더 비교 샌드박스\*\*
간단하고 재현 가능한 예제는 [`docs/SHOWCASE.md`](docs/SHOWCASE.md)를 참조하세요.
---
## 🤝 기여하기 (Contributing)
OpenHarness는 \*\*커뮤니티 주도형 연구 프로젝트\*\*입니다. 다음 분야의 기여를 환영합니다:
| 영역 | 예시 |
|------|---------|
| \*\*Tools\*\* | 특정 도메인을 위한 새로운 도구 구현 |
| \*\*Skills\*\* | 도메인 지식 `.md` 파일 (금융, 과학, DevOps 등) |
| \*\*Plugins\*\* | 명령어, 훅, 에이전트가 포함된 워크플로우 플러그인 |
| \*\*Providers\*\* | 더 많은 LLM 백엔드 지원 (OpenAI, Ollama 등) |
| \*\*Multi-Agent\*\* | 조정 프로토콜, 팀 패턴 |
| \*\*Testing\*\* | E2E 시나리오, 엣지 케이스, 벤치마크 |
| \*\*Documentation\*\* | 아키텍처 가이드, 튜토리얼, 번역 |
```bash
# Development setup
git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness
uv sync --extra dev
uv run pytest -q # Verify everything works
```
유용한 기여자 진입점:
- 설정, 검사, PR 기대치에 대해서는 [`CONTRIBUTING.md`](CONTRIBUTING.md) 참조
- 사용자에게 보이는 변경 사항은 [`CHANGELOG.md`](CHANGELOG.md) 참조
- 문서화할 가치가 있는 실제 사용 패턴은 [`docs/SHOWCASE.md`](docs/SHOWCASE.md) 참조
---
## 🔧 문제 해결 (Troubleshooting)
### macOS Terminal.app에서의 백스페이스(Backspace) 키
OpenHarness는 macOS Terminal.app이 백스페이스용으로 전송하는 원시 `DEL` 바이트(`0x7f`)를 포함하여 일반적인 터미널 삭제 시퀀스를 모두 처리합니다. 백스페이스가 텍스트를 지우는 대신 공백이나 제어 문자를 입력하는 경우, 먼저 OpenHarness를 업그레이드하세요.
이 수정 사항이 포함되지 않은 이전 버전을 사용하는 경우, 표준 백스페이스 시퀀스를 전송하는 터미널을 사용하거나 임시 우회 방법으로 터미널 키보드 프로필을 조정하세요.
---
## 📄 라이선스 (License)
MIT — [LICENSE](LICENSE) 참조.
---

![OpenHarness](assets/logo.png)
  
**Oh my Harness!**
  
*The model is the agent. The code is the harness.*

[![Star History Chart](https://api.star-history.com/svg?repos=HKUDS/OpenHarness&type=Date)](https://star-history.com/#HKUDS/OpenHarness&Date)

*OpenHarness ✨을 방문해 주셔서 감사합니다!*  
  
![Views](https://visitor-badge.laobi.icu/badge?page_id=HKUDS.OpenHarness&style=for-the-badge&color=00d4ff)

OpenHarness

OpenHarness 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

OpenHarness

OpenHarness 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README