한국어
문서
에이전트

에이전트

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

에이전트는 특정 작업과 워크플로우에 맞게 설정할 수 있는 전문화된 AI 어시스턴트입니다. 커스텀 프롬프트, 모델, 도구 접근 권한을 갖춘 집중형 도구를 만들 수 있습니다.

Tip: plan 에이전트를 사용하면 코드를 변경하지 않고도 코드를 분석하고 제안을 검토할 수 있습니다.

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

유형

OpenCode에는 두 가지 유형의 에이전트가 있습니다. 기본(primary) 에이전트와 서브에이전트(subagent)입니다.

기본 에이전트

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

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

OpenCode에는 두 개의 내장 기본 에이전트인 Build와 Plan이 함께 제공됩니다. 아래에서 이들을 살펴보겠습니다.

서브에이전트

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

OpenCode에는 세 개의 내장 서브에이전트인 General, Explore, Scout가 함께 제공됩니다. 아래에서 이를 살펴보겠습니다.

내장

OpenCode에는 두 개의 내장 기본 에이전트와 세 개의 내장 서브에이전트가 함께 제공됩니다.

build 사용

모드: primary

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

plan 사용

모드: primary

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

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

이 에이전트는 코드베이스를 실제로 변경하지 않고 LLM이 코드를 분석하거나 변경을 제안하거나 계획을 세우길 원할 때 유용합니다.

general 사용

모드: subagent

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

explore 사용

모드: subagent

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

scout 사용

모드: subagent

외부 문서 및 의존성 조사를 위한 읽기 전용 에이전트입니다. 의존성 저장소를 OpenCode가 관리하는 캐시에 클론하거나, 라이브러리 소스를 검사하거나, 작업 공간을 수정하지 않고 로컬 코드를 업스트림 구현과 교차 참조해야 할 때 사용하세요.

compaction 사용

모드: primary

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

title 사용

모드: primary

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

summary 사용

모드: primary

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

사용법

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

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

    • 설명을 기반으로 기본 에이전트가 전문화된 작업을 위해 자동으로 호출.

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

      @general help me search for this function

  3. 세션 간 탐색: 서브에이전트가 자식 세션을 생성하면, session_child_first(기본값: <Leader>+Down)를 사용하여 부모에서 첫 번째 자식 세션으로 진입합니다.

  4. 자식 세션에 들어가면 다음을 사용합니다:

    • session_child_cycle(기본값: Right)로 다음 자식 세션으로 순환
    • session_child_cycle_reverse(기본값: Left)로 이전 자식 세션으로 순환
    • session_parent(기본값: Up)로 부모 세션으로 복귀

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

설정

내장 에이전트를 커스터마이즈하거나 설정을 통해 직접 만들 수 있습니다. 에이전트는 두 가지 방식으로 설정할 수 있습니다:

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}",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "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.",
      "permission": {
        "edit": "deny"
      }
    }
  }
}

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
permission:
  edit: deny
  bash: deny
---
 
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
    }
  }
}

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

Caution: 레거시 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 설정을 사용하여 이 에이전트의 모델을 재정의합니다. 서로 다른 작업에 최적화된 다른 모델을 사용할 때 유용합니다. 예를 들어 계획 수립에는 더 빠른 모델, 구현에는 더 강력한 모델을 사용할 수 있습니다.

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

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 (deprecated)

tools는 더 이상 사용되지 않습니다. 새 설정, 업데이트, 더 세밀한 제어에는 에이전트의 permission 필드를 사용하는 것이 좋습니다.

이 에이전트에서 사용할 수 있는 도구를 제어할 수 있습니다. 특정 도구를 true 또는 false로 설정하여 활성화하거나 비활성화할 수 있습니다. 에이전트의 tools 설정에서 true는 {"*": "allow"} 권한과 동일하고 false는 {"*": "deny"} 권한과 동일합니다.

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

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

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

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

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

Permissions

에이전트가 수행할 수 있는 작업을 관리하도록 권한을 설정할 수 있습니다. 각 권한 키는 다음으로 설정할 수 있습니다:

  • "ask" — 도구 실행 전에 승인을 요청
  • "allow" — 승인 없이 모든 작업 허용
  • "deny" — 도구 비활성화

사용 가능한 권한 키는 다음과 같습니다:

키제어하는 도구
readread
editwrite, edit, apply_patch
globglob
grepgrep
listlist
bashbash
tasktask
external_directory프로젝트 워크트리 외부의 파일을 읽거나 쓰는 모든 도구
todowritetodowrite, todoread
webfetchwebfetch
websearchwebsearch
lsplsp
skillskill
questionquestion
doom_loop에이전트가 멈춘 것으로 보일 때의 복구 프롬프트

read, edit, glob, grep, list, bash, task, external_directory, lsp, skill은 단축 액션("allow" | "ask" | "deny") 또는 세밀한 제어를 위한 glob/패턴 → 액션 객체를 받습니다. 나머지 키는 단축 액션만 받습니다.

Note: 권한 키는 기본 도구 이름에 대해 와일드카드 패턴으로 매칭되므로, 내장 도구, 커스텀 도구, MCP 도구에 동일한 구문이 적용됩니다. 예를 들어 "mymcp_*": "deny"는 MCP 서버의 모든 도구를 거부하고, "mymcp_search": "ask"는 단일 도구를 대상으로 합니다.

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 도구를 통해 여전히 호출할 수 있습니다.

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

Task permissions

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

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

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

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

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

Color

color 옵션으로 UI에서 에이전트의 시각적 표시를 커스터마이즈합니다. 이는 인터페이스에서 에이전트가 표시되는 방식에 영향을 줍니다.

유효한 16진수 색상(예: #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의 추론 모델에서는 추론 노력(reasoning effort)을 제어할 수 있습니다:

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

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

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

에이전트 생성

다음 명령으로 새 에이전트를 만들 수 있습니다:

opencode agent create

이 대화형 명령은 다음을 수행합니다:

  1. 에이전트를 어디에 저장할지 묻습니다. 전역 또는 프로젝트별.
  2. 에이전트가 무엇을 해야 하는지에 대한 설명.
  3. 적절한 시스템 프롬프트와 식별자를 생성합니다.
  4. 에이전트에 허용할 권한을 선택하게 합니다(선택하지 않은 것은 거부됨).
  5. 마지막으로 에이전트 설정이 담긴 마크다운 파일을 생성합니다.

사용 사례

다음은 여러 에이전트에 대한 일반적인 사용 사례입니다.

  • Build 에이전트 : 모든 도구가 활성화된 완전한 개발 작업
  • Plan 에이전트 : 변경 없이 분석과 계획 수립
  • Review 에이전트 : 읽기 전용 접근에 문서 도구를 더한 코드 리뷰
  • Debug 에이전트 : bash 및 read 도구가 활성화된 조사 중심
  • Docs 에이전트 : 파일 작업은 가능하지만 시스템 명령은 없는 문서 작성

예시

유용하게 쓸 수 있는 몇 가지 예시 에이전트입니다.

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

문서 에이전트

~/.config/opencode/agents/docs-writer.md
---
description: Writes and maintains project documentation
mode: subagent
permission:
  bash: deny
---
 
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
permission:
  edit: deny
---
 
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
규칙모델