OpenClaw 에이전트 관리: 워크스페이스 및 ID 설정 가이드

여러 프로젝트를 동시에 진행하다 보면 AI 에이전트의 설정이 서로 뒤섞여 곤란했던 적이 있으시죠? 업무용 에이전트와 개인용 프로젝트 에이전트가 같은 공간을 사용하면 보안이나 효율성 면에서 문제가 생길 수 있어요.

OpenClaw의 agents 명령어를 사용하면 워크스페이스, 인증, 라우팅이 분리된 독립적인 에이전트를 아주 쉽게 관리할 수 있습니다. 각 프로젝트에 딱 맞는 에이전트를 구성하고 관리하는 방법을 함께 알아볼게요.

`openclaw agents`

독립된 에이전트(워크스페이스 + 인증 + 라우팅)를 관리합니다.

예시

openclaw agents list
openclaw agents list --bindings
openclaw agents add work --workspace ~/.openclaw/workspace-work
openclaw agents add ops --workspace ~/.openclaw/workspace-ops --bind telegram:ops --non-interactive
openclaw agents bindings
openclaw agents bind --agent work --bind telegram:ops
openclaw agents unbind --agent work --bind telegram:ops
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
openclaw agents set-identity --agent main --avatar avatars/openclaw.png
openclaw agents delete work

라우팅 바인딩

라우팅 바인딩을 사용하면 특정 채널에서 들어오는 트래픽을 특정 에이전트에 고정할 수 있어요.

에이전트마다 서로 다른 스킬을 보여주고 싶다면 openclaw.json 파일에서 agents.defaults.skills와 agents.list[].skills를 설정해 보세요. 자세한 내용은 Skills config와 Configuration Reference를 확인해 주시기 바랍니다.

바인딩 목록 확인:

openclaw agents bindings
openclaw agents bindings --agent work
openclaw agents bindings --json

바인딩 추가:

openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a

accountId를 생략하고 --bind <channel>만 입력하면, OpenClaw는 채널 기본값이나 플러그인 설정 훅을 통해 가능한 경우 자동으로 ID를 찾아냅니다.

bind나 unbind 명령어에서 --agent를 생략하면 현재 기본 에이전트를 대상으로 작업이 수행돼요.

바인딩 스코프 동작 방식

accountId가 없는 바인딩은 채널의 기본 계정에만 매칭됩니다.
accountId: "*"는 채널 전체에 대한 폴백(모든 계정) 역할을 하며, 특정 계정을 명시한 바인딩보다 우선순위가 낮습니다.
동일한 에이전트에 이미 accountId가 없는 채널 바인딩이 있고, 나중에 명시적이거나 확인된 accountId로 다시 바인딩하면 OpenClaw는 중복으로 추가하는 대신 기존 바인딩을 업데이트합니다.

예시:

# initial channel-only binding
openclaw agents bind --agent work --bind telegram

# later upgrade to account-scoped binding
openclaw agents bind --agent work --bind telegram:ops

업그레이드 후에는 해당 바인딩의 라우팅이 telegram:ops 스코프로 제한됩니다. 만약 기본 계정 라우팅도 계속 유지하고 싶다면 --bind telegram:default처럼 명시적으로 추가해 주세요.

바인딩 제거:

openclaw agents unbind --agent work --bind telegram:ops
openclaw agents unbind --agent work --all

unbind 명령어는 --all 또는 하나 이상의 --bind 값 중 하나만 사용할 수 있습니다.

명령어 구성

`agents`

하위 명령어 없이 openclaw agents를 실행하면 openclaw agents list와 동일하게 동작합니다.

`agents list`

옵션:

--json
--bindings: 에이전트별 요약 정보뿐만 아니라 전체 라우팅 규칙을 포함합니다.

`agents add [name]`

옵션:

--workspace <dir>
--model <id>
--agent-dir <dir>
--bind <channel[:accountId]> (중복 사용 가능)
--non-interactive
--json

참고 사항:

명시적인 추가 플래그를 하나라도 전달하면 비대화형(non-interactive) 경로로 전환됩니다.
비대화형 모드에서는 에이전트 이름과 --workspace 경로가 모두 필요합니다.
main은 예약된 이름이므로 새로운 에이전트 ID로 사용할 수 없습니다.

`agents bindings`

옵션:

--agent <id>
--json

`agents bind`

옵션:

--agent <id> (기본값은 현재 기본 에이전트)
--bind <channel[:accountId]> (중복 사용 가능)
--json

`agents unbind`

옵션:

--agent <id> (기본값은 현재 기본 에이전트)
--bind <channel[:accountId]> (중복 사용 가능)
--all
--json

`agents delete <id>`

옵션:

--force
--json

참고 사항:

main 에이전트는 삭제할 수 없습니다.
--force 옵션이 없으면 대화형 확인 절차가 필요합니다.
워크스페이스, 에이전트 상태, 세션 트랜스크립트 디렉토리는 완전히 삭제되지 않고 휴지통으로 이동됩니다.

ID 파일

각 에이전트 워크스페이스의 루트에 IDENTITY.md 파일을 포함할 수 있어요.

경로 예시: ~/.openclaw/workspace/IDENTITY.md
set-identity --from-identity 명령어는 워크스페이스 루트(또는 --identity-file로 명시한 경로)에서 파일을 읽습니다.

아바타 경로는 워크스페이스 루트를 기준으로 해석됩니다.

ID 설정

set-identity 명령어는 agents.list[].identity 내의 다음 필드들을 작성합니다.

name
theme
emoji
avatar (워크스페이스 상대 경로, http(s) URL 또는 data URI)

옵션:

--agent <id>
--workspace <dir>
--identity-file <path>
--from-identity
--name <name>
--theme <theme>
--emoji <emoji>
--avatar <value>
--json

참고 사항:

--agent 또는 --workspace를 사용하여 대상 에이전트를 선택할 수 있습니다.
--workspace를 사용했는데 여러 에이전트가 해당 워크스페이스를 공유하고 있다면, 명령어가 실패하며 --agent를 명시하라는 메시지가 표시됩니다.
명시적인 ID 필드가 제공되지 않으면 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",
        },
      },
    ],
  },
}

에이전트 설정에 대해 더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.