CLI commands
에이전트
openclaw agents
격리된 에이전트(작업 공간 + 인증 + 라우팅)를 관리합니다. 하위 명령 없이 openclaw agents를 실행하면 openclaw agents list를 실행하는 것과 같습니다.
관련 문서:
- 다중 에이전트 라우팅
- 에이전트 작업 공간
- Skills 구성: Skills 표시 범위 구성.
예시
openclaw agents listopenclaw agents list --bindingsopenclaw agents add work --workspace ~/.openclaw/workspace-workopenclaw agents add work --workspace ~/.openclaw/workspace-work --bind telegram:*openclaw agents add ops --workspace ~/.openclaw/workspace-ops --bind telegram:ops --non-interactiveopenclaw agents bindingsopenclaw agents bind --agent work --bind telegram:opsopenclaw agents unbind --agent work --bind telegram:opsopenclaw agents set-identity --workspace ~/.openclaw/workspace --from-identityopenclaw agents set-identity --agent main --avatar avatars/openclaw.pngopenclaw agents delete work명령 표면
agents list
옵션: --json, --bindings(에이전트별 개수/요약뿐만 아니라 전체 라우팅 규칙도 포함).
agents add [name]
옵션: --workspace <dir>, --model <id>, --agent-dir <dir>, --bind <channel[:accountId]>(반복 가능), --non-interactive, --json.
- 명시적인 추가 플래그를 하나라도 전달하면 명령이 비대화형 경로로 전환됩니다.
- 비대화형 모드에는 에이전트 이름과
--workspace가 모두 필요합니다. main은 예약되어 있으므로 새 에이전트 ID로 사용할 수 없습니다.- 대화형 모드는 자격 증명에서
copyToAgents: false로 제외하지 않는 한 이식 가능한 정적 자격 증명(api_key및 정적token프로필)만 복사하여 인증을 초기화합니다. 공급자가copyToAgents: true로 명시적으로 허용하지 않는 한 OAuth 갱신 토큰 프로필은 복사되지 않습니다. 복사본이 없으면 OAuth는 실제main에이전트 저장소의 읽기 통과 상속을 통해서만 사용할 수 있습니다. 구성된 기본 에이전트가main이 아니면 새 에이전트에서 OAuth 프로필에 별도로 로그인하세요.
agents bindings
옵션: --agent <id>, --json.
agents bind
옵션: --agent <id>(현재 기본 에이전트가 기본값), --bind <channel[:accountId]>(반복 가능), --json.
agents unbind
옵션: --agent <id>(현재 기본 에이전트가 기본값), --bind <channel[:accountId]>(반복 가능), --all, --json. --all 또는 하나 이상의 --bind 값 중 하나만 사용할 수 있으며, 둘을 함께 사용할 수는 없습니다.
agents set-identity
옵션: --agent <id>, --workspace <dir>, --identity-file <path>, --from-identity, --name <name>, --theme <theme>, --emoji <emoji>, --avatar <value>, --json. 아래의 정체성 설정을 참조하세요.
agents delete <id>
옵션: --force, --json.
main은 삭제할 수 없습니다.--force를 사용하지 않으면 대화형 확인이 필요합니다(TTY가 아닌 세션에서는 실패하며--force를 사용하여 다시 실행해야 합니다).- 작업 공간, 에이전트 상태 및 세션 기록 디렉터리는 영구 삭제되지 않고 휴지통으로 이동합니다.
- Gateway에 연결할 수 있으면 삭제가 Gateway를 통해 라우팅되므로 구성 및 세션 저장소 정리가 런타임 트래픽과 동일한 작성자를 공유합니다. Gateway에 연결할 수 없으면 CLI가 오프라인 로컬 경로로 대체합니다.
- 다른 에이전트의 작업 공간이 동일한 경로이거나 이 작업 공간 내부에 있거나 이 작업 공간을 포함하면 작업 공간이 유지되며,
--json은workspaceRetained,workspaceRetainedReason,workspaceSharedWith를 보고합니다.
라우팅 바인딩
라우팅 바인딩을 사용하여 수신 채널 트래픽을 특정 에이전트에 고정합니다.
에이전트별로 표시되는 Skills도 다르게 하려면 openclaw.json에서 agents.defaults.skills와 agents.list[].skills를 구성하세요. Skills 구성과 구성 참조를 참조하세요.
바인딩 목록 표시:
openclaw agents bindingsopenclaw agents bindings --agent workopenclaw agents bindings --json바인딩 추가:
openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a에이전트를 생성할 때 바인딩을 추가할 수도 있습니다.
openclaw agents add work --workspace ~/.openclaw/workspace-work --bind telegram:* --bind discord:*accountId를 생략하면(--bind <channel>) OpenClaw는 Plugin 설정 훅, 강제 계정 바인딩 또는 채널에 구성된 계정 수를 사용하여 이를 결정합니다.
bind 또는 unbind에서 --agent를 생략하면 OpenClaw는 현재 기본 에이전트를 대상으로 지정합니다.
--bind 형식
| 형식 | 의미 |
|---|---|
--bind <channel>:* |
채널의 모든 계정과 일치합니다. |
--bind <channel>:<account> |
하나의 계정과 일치합니다. |
--bind <channel> |
CLI가 Plugin별 계정 범위를 안전하게 결정할 수 있는 경우를 제외하고 기본 계정에만 일치합니다. |
바인딩 범위 동작
- 저장된 바인딩에
accountId가 없으면 채널 기본 계정에만 일치합니다. accountId: "*"는 채널 전체 대체 경로(모든 계정)이며 명시적인 계정 바인딩보다 구체성이 낮습니다.- 동일한 에이전트에 이미
accountId가 없는 일치 채널 바인딩이 있고 나중에 명시적이거나 결정된accountId를 사용하여 바인딩하면, OpenClaw는 중복 항목을 추가하는 대신 기존 바인딩을 그 자리에서 업그레이드합니다.
예시:
# 채널의 모든 계정과 일치openclaw agents bind --agent work --bind telegram:* # 특정 계정과 일치openclaw agents bind --agent work --bind telegram:ops # 초기 채널 전용 바인딩openclaw agents bind --agent work --bind telegram # 이후 계정 범위 바인딩으로 업그레이드openclaw agents bind --agent work --bind telegram:alerts업그레이드 후 해당 바인딩의 라우팅 범위는 telegram:alerts로 제한됩니다. 기본 계정 라우팅도 사용하려면 명시적으로 추가하세요(예: --bind telegram:default).
바인딩 제거:
openclaw agents unbind --agent work --bind telegram:opsopenclaw agents unbind --agent work --all정체성 파일
각 에이전트 작업 공간은 작업 공간 루트에 IDENTITY.md를 포함할 수 있습니다.
- 경로 예시:
~/.openclaw/workspace/IDENTITY.md set-identity --from-identity는 작업 공간 루트(또는 명시적인--identity-file)에서 읽습니다.
아바타 경로는 작업 공간 루트를 기준으로 결정되며 심볼릭 링크를 통하더라도 작업 공간을 벗어날 수 없습니다.
정체성 설정
set-identity는 agents.list[].identity에 name, theme, emoji, avatar(작업 공간 기준 상대 경로, http(s) URL 또는 데이터 URI) 필드를 기록합니다.
--agent또는--workspace로 대상 에이전트를 선택합니다.--workspace가 둘 이상의 에이전트와 일치하면 명령이 실패하고--agent를 전달하라는 메시지가 표시됩니다.- 로컬 작업 공간 기준 상대 아바타 이미지 파일은 2MB로 제한됩니다. HTTP(S) URL과
data:URI에는 로컬 파일 크기 제한이 적용되지 않습니다. - 명시적인 정체성 필드를 제공하지 않으면 명령이
IDENTITY.md에서 정체성 데이터를 읽습니다.
IDENTITY.md에서 불러오기:
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity필드를 명시적으로 재정의:
openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --avatar avatars/openclaw.png구성 예시:
{ agents: { list: [ { id: "main", identity: { name: "OpenClaw", theme: "space lobster", emoji: "🦞", avatar: "avatars/openclaw.png", }, }, ], },}