한국어
문서
에이전트

에이전트

전문 에이전트를 설정하고 사용하세요.

에이전트는 특정 작업과 워크플로우를 위해 설정할 수 있는 전문 AI 어시스턴트입니다. 사용자 정의 프롬프트, 모델, 도구 접근 권한을 가진 집중된 도구를 만들 수 있습니다.

팁: plan 에이전트를 사용하여 코드를 분석하고 코드 변경 없이 제안을 검토하세요.

세션 중에 에이전트를 전환하거나 @ 멘션으로 호출할 수 있습니다.

유형

OpenCode에는 두 가지 유형의 에이전트가 있습니다: 기본 에이전트와 서브에이전트.

기본 에이전트

기본 에이전트는 직접 상호작용하는 주요 어시스턴트입니다. Tab 키 또는 설정된 switch_agent 키바인드를 사용하여 순환할 수 있습니다. 이 에이전트들은 주요 대화를 처리합니다. 도구 접근은 권한을 통해 설정됩니다 — 예를 들어, Build는 모든 도구가 활성화되어 있고 Plan은 제한됩니다.

팁: 세션 중에 Tab 키를 사용하여 기본 에이전트 간에 전환할 수 있습니다.

OpenCode에는 두 개의 내장 기본 에이전트인 Build와 Plan이 있습니다. 아래에서 살펴보겠습니다.

서브에이전트

서브에이전트는 기본 에이전트가 특정 작업을 위해 호출할 수 있는 전문 어시스턴트입니다. 메시지에서 @ 멘션을 통해 수동으로 호출할 수도 있습니다.

OpenCode에는 두 개의 내장 서브에이전트인 General과 Explore가 있습니다. 아래에서 살펴보겠습니다.

내장 에이전트

OpenCode에는 두 개의 내장 기본 에이전트와 두 개의 내장 서브에이전트가 있습니다.

Build 사용

모드: primary

Build는 모든 도구가 활성화된 기본 기본 에이전트입니다. 파일 작업과 시스템 명령에 대한 전체 접근이 필요한 개발 작업을 위한 표준 에이전트입니다.

Plan 사용

모드: primary

계획 및 분석을 위해 설계된 제한된 에이전트입니다. 더 많은 제어를 제공하고 의도하지 않은 변경을 방지하기 위해 권한 시스템을 사용합니다. 기본적으로 다음 모든 항목이 ask로 설정됩니다:

  • file edits: 모든 쓰기, 패치, 편집
  • bash: 모든 bash 명령

이 에이전트는 LLM이 코드베이스에 실제 수정을 하지 않고 코드를 분석하거나, 변경을 제안하거나, 계획을 만들기를 원할 때 유용합니다.

General 사용

모드: subagent

복잡한 질문을 연구하고 다단계 작업을 실행하기 위한 범용 에이전트입니다. 전체 도구 접근 권한이 있어(todo 제외) 필요할 때 파일을 변경할 수 있습니다. 여러 작업 단위를 병렬로 실행하는 데 사용하세요.

Explore 사용

모드: subagent

코드베이스를 탐색하기 위한 빠른 읽기 전용 에이전트입니다. 파일을 수정할 수 없습니다. 패턴으로 파일을 빠르게 찾거나, 키워드로 코드를 검색하거나, 코드베이스에 대한 질문에 답해야 할 때 사용하세요.

Compaction 사용

모드: primary

긴 컨텍스트를 더 작은 요약으로 압축하는 숨겨진 시스템 에이전트입니다. 필요할 때 자동으로 실행되며 UI에서 선택할 수 없습니다.

Title 사용

모드: primary

짧은 세션 제목을 생성하는 숨겨진 시스템 에이전트입니다. 자동으로 실행되며 UI에서 선택할 수 없습니다.

Summary 사용

모드: primary

세션 요약을 생성하는 숨겨진 시스템 에이전트입니다. 자동으로 실행되며 UI에서 선택할 수 없습니다.

사용법

  • 기본 에이전트의 경우, 세션 중에 Tab 키를 사용하여 순환하세요. 설정된 switch_agent 키바인드를 사용할 수도 있습니다.

  • 서브에이전트는 다음과 같이 호출할 수 있습니다:

    • 설명에 따라 특정 작업을 위해 기본 에이전트에 의해 자동으로.

    • 메시지에서 서브에이전트를 @ 멘션하여 수동으로. 예:

      @general help me search for this function

  • 세션 간 탐색: 서브에이전트가 자체 하위 세션을 생성할 때, 다음을 사용하여 부모 세션과 모든 하위 세션 간에 탐색할 수 있습니다:

    • <Leader>+Right (또는 설정된 session_child_cycle 키바인드)로 부모 → 하위1 → 하위2 → … → 부모 순으로 앞으로 순환
    • <Leader>+Left (또는 설정된 session_child_cycle_reverse 키바인드)로 부모 ← 하위1 ← 하위2 ← … ← 부모 순으로 뒤로 순환

    이를 통해 주요 대화와 전문 서브에이전트 작업 간에 원활하게 전환할 수 있습니다.

설정

내장 에이전트를 사용자 정의하거나 설정을 통해 직접 만들 수 있습니다. 에이전트는 두 가지 방법으로 설정할 수 있습니다:

JSON

opencode.json 설정 파일에서 에이전트를 설정하세요:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

마크다운 파일을 사용하여 에이전트를 정의할 수도 있습니다. 다음 위치에 배치하세요:

  • 전역: ~/.config/opencode/agents/
  • 프로젝트별: .opencode/agents/
~/.config/opencode/agents/review.md
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---
 
You are in code review mode. Focus on:
 
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations
 
Provide constructive feedback without making direct changes.

마크다운 파일 이름이 에이전트 이름이 됩니다. 예를 들어, review.md는 review 에이전트를 생성합니다.

옵션

이러한 설정 옵션을 자세히 살펴보겠습니다.

Description

description 옵션을 사용하여 에이전트가 무엇을 하고 언제 사용해야 하는지에 대한 간단한 설명을 제공하세요.

opencode.json
{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

이것은 필수 설정 옵션입니다.

Temperature

temperature 설정으로 LLM 응답의 무작위성과 창의성을 제어하세요.

낮은 값은 응답을 더 집중적이고 결정적으로 만들고, 높은 값은 창의성과 변동성을 증가시킵니다.

opencode.json
{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Temperature 값은 일반적으로 0.0에서 1.0 사이입니다:

  • 0.0-0.2: 매우 집중적이고 결정적인 응답, 코드 분석 및 계획에 이상적
  • 0.3-0.5: 약간의 창의성이 있는 균형 잡힌 응답, 일반 개발 작업에 적합
  • 0.6-1.0: 더 창의적이고 다양한 응답, 브레인스토밍 및 탐색에 유용
opencode.json
{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

temperature가 지정되지 않으면 OpenCode는 모델별 기본값을 사용합니다; 대부분의 모델에서 일반적으로 0, Qwen 모델에서는 0.55입니다.

Max steps

에이전트가 텍스트로만 응답하도록 강제되기 전에 수행할 수 있는 에이전트 반복의 최대 횟수를 제어합니다. 이를 통해 비용을 제어하려는 사용자가 에이전트 작업에 제한을 설정할 수 있습니다.

설정하지 않으면 에이전트는 모델이 중지를 선택하거나 사용자가 세션을 중단할 때까지 계속 반복합니다.

opencode.json
{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

제한에 도달하면 에이전트는 작업 요약과 권장 남은 작업으로 응답하도록 지시하는 특별한 시스템 프롬프트를 받습니다.

주의: 레거시 maxSteps 필드는 더 이상 사용되지 않습니다. 대신 steps를 사용하세요.

Disable

에이전트를 비활성화하려면 true로 설정하세요.

opencode.json
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

prompt 설정으로 이 에이전트에 대한 사용자 정의 시스템 프롬프트 파일을 지정하세요. 프롬프트 파일에는 에이전트의 목적에 맞는 지침이 포함되어야 합니다.

opencode.json
{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

이 경로는 설정 파일이 있는 위치를 기준으로 합니다. 따라서 전역 OpenCode 설정과 프로젝트별 설정 모두에서 작동합니다.

Model

model 설정을 사용하여 이 에이전트의 모델을 재정의하세요. 다른 작업에 최적화된 다른 모델을 사용하는 데 유용합니다. 예를 들어, 계획에는 더 빠른 모델, 구현에는 더 강력한 모델.

팁: 모델을 지정하지 않으면 기본 에이전트는 전역으로 설정된 모델을 사용하고 서브에이전트는 서브에이전트를 호출한 기본 에이전트의 모델을 사용합니다.

opencode.json
{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

OpenCode 설정의 모델 ID는 provider/model-id 형식을 사용합니다. 예를 들어, OpenCode Zen을 사용하는 경우 GPT 5.1 Codex에 opencode/gpt-5.1-codex를 사용합니다.

Tools

tools 설정으로 이 에이전트에서 사용할 수 있는 도구를 제어하세요. true 또는 false로 설정하여 특정 도구를 활성화하거나 비활성화할 수 있습니다.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

참고: 에이전트별 설정이 전역 설정을 재정의합니다.

와일드카드를 사용하여 여러 도구를 한 번에 제어할 수도 있습니다. 예를 들어, MCP 서버의 모든 도구를 비활성화하려면:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

도구에 대해 자세히 알아보기.

Permissions

에이전트가 수행할 수 있는 작업을 관리하기 위해 권한을 설정할 수 있습니다. 현재 edit, bash, webfetch 도구에 대한 권한을 다음과 같이 설정할 수 있습니다:

  • "ask" — 도구 실행 전 승인 요청
  • "allow" — 승인 없이 모든 작업 허용
  • "deny" — 도구 비활성화
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

에이전트별로 이러한 권한을 재정의할 수 있습니다.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

Markdown 에이전트에서도 권한을 설정할 수 있습니다.

~/.config/opencode/agents/review.md
---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---
 
Only analyze code and suggest changes.

특정 bash 명령에 대한 권한을 설정할 수 있습니다.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

glob 패턴을 사용할 수 있습니다.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

* 와일드카드를 사용하여 모든 명령에 대한 권한을 관리할 수도 있습니다. 마지막으로 일치하는 규칙이 우선하므로 * 와일드카드를 먼저 넣고 특정 규칙을 나중에 넣으세요.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

권한에 대해 자세히 알아보기.

Mode

mode 설정으로 에이전트의 모드를 제어하세요. mode 옵션은 에이전트를 어떻게 사용할 수 있는지 결정하는 데 사용됩니다.

opencode.json
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

mode 옵션은 primary, subagent 또는 all로 설정할 수 있습니다. mode가 지정되지 않으면 기본값은 all입니다.

Hidden

hidden: true로 @ 자동완성 메뉴에서 서브에이전트를 숨기세요. Task 도구를 통해 다른 에이전트에 의해 프로그래밍 방식으로만 호출되어야 하는 내부 서브에이전트에 유용합니다.

opencode.json
{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

이것은 자동완성 메뉴에서의 사용자 가시성에만 영향을 미칩니다. 숨겨진 에이전트는 권한이 허용하는 경우 Task 도구를 통해 모델에 의해 여전히 호출될 수 있습니다.

참고: mode: subagent 에이전트에만 적용됩니다.

Task permissions

permission.task로 에이전트가 Task 도구를 통해 호출할 수 있는 서브에이전트를 제어하세요. 유연한 매칭을 위해 glob 패턴을 사용합니다.

opencode.json
{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

deny로 설정하면 서브에이전트가 Task 도구 설명에서 완전히 제거되어 모델이 호출을 시도하지 않습니다.

팁: 규칙은 순서대로 평가되며 마지막으로 일치하는 규칙이 우선합니다. 위의 예에서 orchestrator-planner는 * (deny)와 orchestrator-* (allow) 모두와 일치하지만, orchestrator-*가 * 뒤에 오므로 결과는 allow입니다.

팁: 사용자는 에이전트의 task 권한이 거부하더라도 @ 자동완성 메뉴를 통해 항상 모든 서브에이전트를 직접 호출할 수 있습니다.

Color

color 옵션으로 UI에서 에이전트의 시각적 모양을 사용자 정의하세요. 이것은 인터페이스에서 에이전트가 어떻게 나타나는지에 영향을 미칩니다.

유효한 hex 색상(예: #FF5733) 또는 테마 색상을 사용하세요: primary, secondary, accent, success, warning, error, info.

opencode.json
{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

top_p 옵션으로 응답 다양성을 제어하세요. 무작위성을 제어하기 위한 temperature의 대안입니다.

opencode.json
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

값은 0.0에서 1.0 사이입니다. 낮은 값은 더 집중적이고, 높은 값은 더 다양합니다.

Additional

에이전트 설정에서 지정하는 다른 옵션은 모델 옵션으로 프로바이더에 직접 전달됩니다. 이를 통해 프로바이더별 기능과 매개변수를 사용할 수 있습니다.

예를 들어, OpenAI의 추론 모델에서 추론 노력을 제어할 수 있습니다:

opencode.json
{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

이러한 추가 옵션은 모델 및 프로바이더에 따라 다릅니다. 사용 가능한 매개변수는 프로바이더 문서를 확인하세요.

팁: opencode models를 실행하여 사용 가능한 모델 목록을 확인하세요.

에이전트 생성

다음 명령을 사용하여 새 에이전트를 생성할 수 있습니다:

opencode agent create

이 대화형 명령은:

  • 에이전트를 저장할 위치를 묻습니다; 전역 또는 프로젝트별.
  • 에이전트가 해야 할 일에 대한 설명.
  • 적절한 시스템 프롬프트와 식별자를 생성합니다.
  • 에이전트가 접근할 수 있는 도구를 선택하게 합니다.
  • 마지막으로 에이전트 설정이 포함된 마크다운 파일을 생성합니다.

사용 사례

다양한 에이전트에 대한 일반적인 사용 사례입니다.

  • Build 에이전트: 모든 도구가 활성화된 전체 개발 작업
  • Plan 에이전트: 변경 없이 분석 및 계획
  • Review 에이전트: 읽기 전용 접근과 문서 도구를 사용한 코드 리뷰
  • Debug 에이전트: bash와 읽기 도구가 활성화된 조사에 집중
  • Docs 에이전트: 시스템 명령 없이 파일 작업을 사용한 문서 작성

예제

유용할 수 있는 예제 에이전트입니다.

팁: 공유하고 싶은 에이전트가 있나요? PR을 제출하세요 (opens in a new tab).

문서 에이전트

~/.config/opencode/agents/docs-writer.md
---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---
 
You are a technical writer. Create clear, comprehensive documentation.
 
Focus on:
 
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

보안 감사자

~/.config/opencode/agents/security-auditor.md
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---
 
You are a security expert. Focus on identifying potential security issues.
 
Look for:
 
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues
규칙모델