콘텐츠로 이동
OpenCode
app.header.homeapp.header.docs

Agents

Configure and use specialized agents.

에이전트는 특정 작업과 워크플로우를 구성할 수 있는 AI 보조를 전문으로 합니다. 사용자 정의 프롬프트, 모델 및 도구 액세스와 초점을 맞춘 도구를 만들 수 있습니다.

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

유형

OpenCode의 두 가지 유형이 있습니다; 기본 에이전트와 subagents.

주요 에이전트

주요 에이전트은 당신이 직접 상호 작용하는 주요 조수입니다. Tab 키 또는 설정된 switch_agent keybind를 사용하여 주기 할 수 있습니다. 이 에이전트은 당신의 주요 대화를 취급합니다. 도구 액세스는 권한을 통해 구성된다 — 예를 들어, Build는 Plan이 제한되는 동안 모든 도구를 사용할 수 있습니다.

OpenCode는 두 개의 내장 기본 에이전트, Build 및 Plan와 함께 제공됩니다. 우리는 아래에서 보기.

Subagents

Subagents는 기본 에이전트가 특정 작업을 위해 호출 할 수있는 전문 보조입니다. 또한 수동으로 그들을 호출 할 수 있습니다 ** @ 언급 ** 메시지에서 그들.

OpenCode는 두 개의 내장 subagents, General 및 Explore. 아래에서 볼 수 있습니다.

내장

OpenCode는 기본 에이전트와 두 개의 내장 subagents로 제공됩니다.

사용 Build

모드: primary

Build는 default 모든 도구가 활성화된 기본 에이전트입니다. 이것은 당신이 파일 가동 및 체계 명령에 가득 차있는 접근을 필요로 하는 발달 일을 위한 표준 에이전트입니다.

사용 Plan

모드: primary

계획 및 분석을 위해 설계된 제한된 에이전트. 우리는 더 많은 통제를 주고 무인화한 변화를 방지하기 위하여 허가 체계를 이용합니다. 기본적으로, 뒤에 오는 전부는 ask로 놓입니다:

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

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

사용 General

모드: subagent

복잡한 질문을 연구하고 다중 단계 작업을 실행하기위한 범용 에이전트. 전체 도구 액세스 (todo 제외), 그래서 필요할 때 파일 변경을 만들 수 있습니다. 평행한에 있는 일의 다수 단위를 달리기 위하여 이것을 사용하십시오.

사용 Explore

모드: subagent

Codebases를 탐구하는 빠르고, 읽기 전용 에이전트. 파일을 수정할 수 없습니다. 이 작업을 사용하면 패턴, 키워드 검색 코드, 또는 codebase에 대한 질문에 신속하게 파일을 찾을 수 있습니다.

사용 Compaction

모드: primary

더 작은 요약으로 긴 맥락을 압축하는 숨겨진 시스템 에이전트. 필요한 경우 자동으로 실행되며 UI에서 선택할 수 없습니다.

사용 Title

모드: primary

짧은 세션 타이틀을 생성하는 숨겨진 시스템 에이전트. 그것은 자동으로 실행하고 UI에서 선택할 수 없습니다.

사용 Summary

모드: primary

세션 summaries를 만드는 숨겨진 시스템 에이전트. 그것은 자동으로 실행하고 UI에서 선택할 수 없습니다.

사용법

  1. 주요 에이전트을 위해, **Tab ** 열쇠를 사용하여 세션 도중 주기. 구성 된 switch_agent keybind도 사용할 수 있습니다.

  2. Subagents은 invoked 일 수 있습니다:

    • Automatically 그들의 설명에 근거를 둔 특화된 업무를 위한 주요 에이전트에 의하여.

    • 메시지에 대한 subagents**. 예를 들어.

      @general help me search for this function

  3. ** 세션 간의 편차 **: subagents는 자신의 자녀 세션을 만들 때, 부모 세션과 모든 어린이 세션을 사용하여 탐색 할 수 있습니다.

    • <Leader>+Right (또는 부모 → Child1 → Child2 →를 통해 전달하기 위해 설정된 session_child_cycle keybind)
    • <Leader>+Left (또는 session_child_cycle_reverse keybind) 부모를 통해 돌아 가기 위해 ← child1 ← child2 ← … ← 부모

    이로 인해 주요 대화와 특이한 subagent 작업을 원활하게 전환할 수 있습니다.

구성

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

JSON

opencode.json config 파일에 에이전트 구성:

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

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.

markdown 파일 이름은 에이전트 이름입니다. 예를 들어, review.md는 review 에이전트을 만듭니다.

옵션

이 구성 옵션을 자세히 살펴봅시다.

묘사

description 옵션을 사용하여 에이전트가 작동하고 사용할 때의 간단한 설명을 제공합니다.

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

** config 옵션이 필요합니다.

온도

temperature config와 LLM의 응답의 임의성과 창의성을 제어합니다.

더 낮은 값은 더 집중하고 세심한 응답을 만듭니다. 더 높은 값은 창의력과 가변성을 증가하면서.

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

온도 값은 일반적으로 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}"
    }
  }
}

온도가 지정되지 않은 경우, opencode는 모델 별 기본을 사용합니다. 일반적으로 대부분의 모델의 경우 0, Qwen 모델의 경우 0.55.

최대 단계

에이전트의 최대 수를 통제하는 에이전트은 원본과 반응하기 전에 실행할 수 있습니다. 이 사용자는 에이전트 행동에 제한을 설정하는 비용을 제어 할 수 있습니다.

이 설정되지 않은 경우, 에이전트는 모델이 중지하거나 사용자가 세션을 중단하도록 선택할 때까지 계속됩니다.

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

제한이 도달되면, 에이전트는 특별한 시스템을 신속하게 작업의 요약과 권장되는 나머지 작업에 응답하도록 지시합니다.

비활성화

true로 에이전트를 비활성화합니다.

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

프롬프트

prompt config를 가진 이 에이전트을 위한 주문 체계 prompt 파일을 지정하십시오. prompt 파일은 에이전트의 목적에 따라 지시를 포함해야합니다.

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

이 경로는 config 파일이 있는 곳에 관계됩니다. 그래서 이것은 글로벌 opencode 구성과 프로젝트 특정 구성 모두를 위해 작동합니다.

모형

model config를 사용하여이 에이전트에 대한 모델을 삭제합니다. 다른 작업에 최적화 된 다른 모델을 사용하는 데 유용합니다. 예를 들어, 계획을위한 빠른 모델, 구현을위한 더 많은 모델.

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

opencode config의 모델 ID는 provider/model-id 형식을 사용합니다. 예를 들어, OpenCode Zen을 사용한다면, GPT 5.1 Codex에 opencode/gpt-5.1-codex를 사용할 수 있습니다.

도구

tools config로 이 에이전트에서 사용할 수있는 제어. 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
      }
    }
  }
}

공구에 대해 더 알아보기.

# 권한

에이전트가 수행 할 수있는 작업을 관리 할 수있는 권한을 구성 할 수 있습니다. 현재 edit, bash 및 webfetch 도구에 대한 권한은 다음과 같습니다.

  • "ask" - 도구 실행하기 전에 승인을위한 Prompt
  • "allow" - 승인없이 모든 작업을 허용
  • "deny" - 도구 비활성화
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

당신은 에이전트 당이 허가를 override 할 수 있습니다.

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 config로 에이전트 모드를 제어합니다. mode 선택권은 에이전트이 사용될 수 있는 방법을 결정하기 위하여 이용됩니다.

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

mode 선택권은 primary, subagent, 또는 all에 놓일 수 있습니다. mode가 지정되지 않은 경우 all로 기본값입니다.

#숨겨진

@를 사용해 hidden: true 자동 완성 메뉴에서 시약을 숨깁니다. 작업 도구를 통해 다른 에이전트에 의해 invoked programmatically 있어야하는 내부 시약에 유용합니다.

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

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

작업 권한

에이전트가 permission.task와 작업 도구를 통해 호출 할 수있는 제어. 유연한 일치를 위한 glob 본을 사용합니다.

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

deny로 설정할 때, Subagent는 작업 도구 설명에서 완전히 제거됩니다. 그래서 모델은 그것을 호출하려고하지 않습니다.

색깔

color 옵션과 UI에서 에이전트의 시각적 외관을 사용자 정의합니다. 이것은 어떻게 에이전트가 인터페이스에 나타납니다.

유효한 hex 색깔을 사용하십시오 (예를들면, #FF5733) 또는 주제 색깔: primary, secondary, accent, success, warning, error, info.

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

정상 P

top_p 선택권을 가진 응답 다양성을 통제하십시오. 무작위 통제를 위한 온도에 대안.

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

가치는 0.0에서 1.0에 배열합니다. 더 낮은 가치는 더 집중되고, 더 높은 가치는 더 다양합니다.

추가

에이전트 구성에 지정하는 다른 옵션은 ** 직접 통과 ** 모델 옵션으로 공급자. 이 공급자 별 기능 및 매개 변수를 사용할 수 있습니다.

예를 들어, OpenAI의 이유 모델과 함께, 당신은 이유를 제어 할 수 있습니다 노력:

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

이 추가 옵션은 모델과 공급자 별입니다. 공급자의 문서 확인 가능 매개 변수.

에이전트 만들기

다음 명령을 사용하여 새로운 에이전트를 만들 수 있습니다:

Terminal window
opencode agent create

이 대화 형 명령은:

  1. 에이전트을 저장하는 곳에게; 세계적인 프로젝트 별.
  2. 에이전트이 해야 하는 무슨의 묘사.
  3. 적절한 시스템 프롬프트 및 식별자를 생성한다.
  4. 당신은 에이전트이 접근할 수 있는 어떤 공구를 선정하자.
  5. 마지막으로, 에이전트 구성을 가진 markdown 파일을 창조하십시오.

사용 사례

다른 에이전트을 위한 몇몇 일반적인 사용 사례는 여기 있습니다.

  • 빌딩 에이전트: 모든 도구와 함께 전체 개발 작업
  • ** 플랜 에이전트**: 변화없이 분석 및 계획
  • 리뷰 에이전트: Code review with read-only access plus 문서 도구
  • ** 디버그 에이전트**: bash 및 읽기 도구와 함께 조사에 집중
  • **Docs 에이전트 **: 파일 작업과 문서 작성하지만 시스템 명령 없음

예제

여기에 유용 할 수있는 몇 가지 예 에이전트가 있습니다.

문서 에이전트

~/.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