콘텐츠로 이동

obscli 사용자 매뉴얼

obscli는 Beak 명령줄 클라이언트입니다. 설치 및 로그인 후 다음을 수행할 수 있습니다:

  1. 계정에서 사용 가능한 모든 워크스페이스, Agent, 그리고 태스크를 확인할 수 있습니다.
  2. 선택된 워크스페이스에서 새로운 작업을 생성하거나 기존의 작업을 계속 진행할 수 있습니다.
  3. Agent와 대화하고, 관측 리소스를 참조하며, Skill을 선택합니다.
  4. 스크립트에서 일회성 작업을 제출하고 결과를 수집합니다.
  5. 로그인하여 해당 노드 또는 컨테이너에 접속한 후, 프라이빗 모드를 사용하여 local Agent와 채팅할 수 있습니다.

obscli 설치

설정 센터에서 설치하기 (권장)

Obsy Agent Teams 페이지에서, 오른쪽 상단의 아바타를 클릭한 후 개인 설정 > 개발자 도구 > obs-cli를 선택하세요.

  1. macOS, Linux, 또는 Windows를 선택하세요.
  2. 복사 명령을 클릭하세요.
  3. 터미넘에서 obscli을 사용할 명령을 실행하세요.
  4. 설치 후 obscli을 실행하여 현재 워크스페이스에 있는 Agents이 보이는지 확인하세요.

생성된 명령어에는 연결에 필요한 자격 증명 정보가 포함되어 있습니다. 개인 접근 자격 증명을 수동으로 복사할 필요는 없습니다.

설치 스크립트로 설치

Linux 및 macOS

실행:

curl -fsSL https://static.guance.com/obscli/install-obscli.sh | bash -s -- \
  --release-base-url https://static.guance.com/obscli \
  --beak-server https://agent-api.guance.com \
  --login <YOUR-USER-SK>

Linux/macOS는 기본적으로 Unix 경로를 사용합니다:

유형 기본 경로
설치 디렉터리 ~/.local/bin
실행 파일 ~/.local/bin/obscli
데이터 디렉터리 ~/.obscli
로그인 및 업데이트 설정 ~/.obscli/login.toml
로그 디렉터리 ~/.obscli/log
현재 로그 파일 ~/.obscli/log/obscli.log

설치 후 obscli를 사용할 수 없는 경우, 설치 디렉터리를 PATH에 추가하세요:

export PATH="$HOME/.local/bin:$PATH"

WSL은 Linux 환경이므로 동일한 명령과 경로를 사용합니다.

Windows PowerShell

실행:

iwr https://static.guance.com/obscli/install-obscli.ps1 -OutFile $env:TEMP\install-obscli.ps1
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
& $env:TEMP\install-obscli.ps1 `
  -ReleaseBaseUrl https://static.guance.com/obscli `
  -BeakServer https://agent-api.guance.com `
  -Login <YOUR-USER-SK>

Windows에서 obscli는 기본적으로 다음 경로에 설치됩니다:

%LOCALAPPDATA%\Programs\obscli\obscli.exe

설치 후 PowerShell을 다시 열고 실행하세요:

obscli

PowerShell을 다시 열 수 없는 경우, 전체 경로를 직접 실행하세요:

& "$env:LOCALAPPDATA\Programs\obscli\obscli.exe"

Windows 기본 디렉터리:

유형 기본 경로
설치 디렉터리 %LOCALAPPDATA%\Programs\obscli
실행 파일 %LOCALAPPDATA%\Programs\obscli\obscli.exe
데이터 디렉터리 %USERPROFILE%\.obscli
로그인 및 업데이트 설정 %USERPROFILE%\.obscli\login.toml
로그 디렉터리 %USERPROFILE%\.obscli\log
현재 로그 파일 %USERPROFILE%\.obscli\log\obscli.log

Windows에서는 PowerShell을 권장합니다. Git Bash는 자체 $HOME을 사용하여 경로를 해석합니다. Git Bash를 사용하는 경우 설치 디렉터리를 명시적으로 지정하세요:

curl.exe -fsSL https://static.guance.com/obscli/install-obscli.sh | bash -s -- \
  --release-base-url https://static.guance.com/obscli \
  --install-dir "$HOME/bin" \
  --beak-server https://agent-api.guance.com \
  --login <YOUR-USER-SK>

오프라인 패키지로 설치

시스템에 맞는 패키지를 다운로드합니다. 예:

obscli-linux-amd64-v1.2.3.tar.gz
obscli-darwin-arm64-v1.2.3.tar.gz
obscli-windows-amd64-v1.2.3.tar.gz

검증 및 설치:

sha256sum -c obscli-linux-amd64-v1.2.3.tar.gz.sha256
bash install-obscli.sh --archive ./obscli-linux-amd64-v1.2.3.tar.gz --install-dir "$HOME/.local/bin" --yes

obscli 제거

재설치 전 이전 이름에서 마이그레이션

이 머신에 이전 obsycli가 설치되어 있는 경우, obscli로 직접 덮어쓰지 마세요. 먼저 이전 실행 파일과 데이터 디렉터리를 삭제한 후, 설치 섹션에 따라 새 obscli를 재설치하고 로그인하세요.

Linux/macOS/WSL:

명령 중 하나를 선택하세요. 첫 번째는 파일 삭제 전 확인을 요청하고, 두 번째는 --yes를 사용하여 확인을 건너뜁니다:

curl -fsSL https://static.guance.com/obs-agent/uninstall-legacy.sh | sudo bash
curl -fsSL https://static.guance.com/obs-agent/uninstall-legacy.sh | sudo bash -s -- --yes

이 스크립트는 beak-agent에서 이름이 변경되기 전의 고정 시스템 레이아웃을 정리합니다. 또한 이전 obsycli의 일반적인 Linux/macOS 설치 위치도 제거합니다: /usr/local/bin/obsycli, /usr/bin/obsycli, 그리고 현재 HOME 및 SUDO_USER 홈 아래의 ~/.local/bin/obsycli와 ~/.obsycli입니다.

Windows PowerShell:

Get-Command obsycli -All
Remove-Item "$env:LOCALAPPDATA\Programs\obsycli\obsycli.exe" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\Programs\obsycli" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.obsycli" -Recurse -Force -ErrorAction SilentlyContinue

이전 버전을 제거한 후 이 문서의 obscli 설치 명령으로 재설치하세요. obscli는 ~/.obscli 또는 %USERPROFILE%\.obscli를 사용하며 이전 obsycli의 로컬 설정을 읽지 않습니다.

현재 버전 제거

Linux/macOS:

which -a obscli
rm -f ~/.local/bin/obscli
rm -rf ~/.obscli

sudo로 시스템 디렉터리에 설치한 경우:

sudo rm -f /usr/local/bin/obscli
rm -rf ~/.obscli

Windows PowerShell:

Get-Command obscli -All
Remove-Item "$env:LOCALAPPDATA\Programs\obscli\obscli.exe" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\Programs\obscli" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.obscli" -Recurse -Force -ErrorAction SilentlyContinue

obscli.exe가 다른 디렉터리에 있는 경우, Get-Command obscli -All로 표시된 파일을 삭제하세요.

Windows Git Bash:

which -a obscli
rm -f "$HOME/bin/obscli.exe"
rm -rf "$HOME/.obscli"

WSL:

which -a obscli
rm -f ~/.local/bin/obscli
rm -rf ~/.obscli

로컬 데이터 디렉터리에는 로그인 토큰, 업데이트 설정, 로그가 포함되어 있습니다. 삭제 후에는 다시 로그인해야 합니다.

Beak에 로그인

Beak 웹 페이지에서 사용자 sk를 복사한 후 실행하세요:

obscli --login <YOUR-USER-SK> --beak-server https://agent-api.guance.com

테스트 환경 인증서가 머신에서 신뢰되지 않는 경우 다음을 추가하세요:

obscli --login <YOUR-USER-SK> --beak-server https://agent-api.guance.com --insecure-skip-tls-verify

로그인이 성공하면 자격 증명이 다음에 저장됩니다:

~/.obscli/login.toml

이후 obscli를 직접 실행하면 대화형 채팅에 진입합니다.

지역 사용자 Agent와 개인적으로 채팅하기

Linux 또는 macOS 노드에서 obs-agent를 실행하거나, 그 컨테이너 내에서 프라이빗 모드에서는 유닉스 소켓을 사용합니다. Agent는 Beak 연결, Profile 동기화, 하트비트, 그리고 일반적인 웹, IM, CLI 세션들을 유지합니다.

개인 자격 증명으로 로그인하세요. 일반 모드와 비공개 모드는 같은 로그인 설정을 사용합니다. 비공개 모드에서는 Agent 또는 관리자 자격 증명을 자동으로 사용하지 않습니다.

obscli --login <YOUR-USER-SK> --beak-server https://agent-api.guance.com
obscli --private

local obs-agent가 실행되고 있어야 합니다. 기본 소켓은 /var/lib/obs-agent/private.sock입니다. 소켓이 없거나 연결에 실패하거나 접근이 거부되면 오류가 발생합니다. 클라이언트는 원격의 Agent로 전환되지 않습니다. native Windows는 지원되지 않습니다.

동일한 운영 체제 계정 하에서, 다양한 개인 계정용으로 별도의 설정 디렉터리를 사용해야 합니다:

obscli --login <YOUR-USER-SK> --beak-server https://agent-api.guance.com --config-dir ~/obscli-personal
obscli --private --config-dir ~/obscli-personal

일반 모드와의 차이점

항목/상품 일반 모드 개인 모드
시작 obscli obscli --private
채팅 및 저장 Beak은 세션을 전송하고 저장합니다. 로컬 소켓; 세션 ID, 제목, 메시지, 도구 이벤트 및 기록은 노드에 남아 있으며 Beak로 업로드되지 않습니다.
/agents 일반 모드: 워크스페이스 전체에서 사용 가능한 Agents 목록을 표시합니다. 프라이빗 모드: 로컬의 Agent만 표시합니다.
/tasks, /newtask, /attach 일반적인 Beak 작업들 로컬 Agent에 대한 개인용 태스크들
협업 권한 내에 있는 A2A A2A 및 원격 발견 기능이 비활성화된 상태입니다. 로컬 서브 에이전트는 프라이빗 모드 제한 조건 하에서 여전히 사용 가능합니다.
기타 도구들 Agent의 기능과 권한들 Beak 첨부 파일 전송, 예약된 작업, Agent 설정 정보의 읽기/쓰기 기능, 그리고 진단 관련 파일 업로드 기능이 비활성화되었습니다. 그러나 로컬 파일, 명령어, 그리고 허용된 외부 도구는 여전히 사용할 수 있습니다.
스크립트들 obscli run 지원 오직 대화형 채팅만 가능합니다. obscli run는 개인 모드를 지원하지 않습니다.

세션 목록은 별도로 유지됩니다. 다른 모드에서 생성된 작업 ID는 다른 모드로 전송될 수 없습니다. 프라이빗 작업은 모드를 전환하거나 종료할 때에도 비공개 상태로 유지됩니다. 스트리밍, 추론, 도구 승인, 취소 및 재연재는 여전히 사용 가능합니다. 프라이빗 작업도 업그레이드된 유휴 보호 기능을 사용합니다.

세션 저장 및 복구

로컬 Agent는 개인 신원을 기준으로 비공개 작업의 소유권을 관리합니다. 수락된 작업은 obscli를 종료해도 계속 실행되며 승인은 재연결을 기다립니다. 같은 신원으로 로그인하고 같은 Agent에 연결하여 기록을 복원하세요. Agent가 재시작되면 로컬 기록을 읽지만 미완료 실행은 실패 상태가 됩니다. 도구를 다시 실행하거나 이전의 대기 중인 승인을 실행하지 않습니다.

AGENT_PRIVATE_DATA_DIR는 개인 데이터 디렉터리를 선택합니다. 기본적으로는 AGENT_PROFILE_CACHE_DIR와 -private을 합친 것이며, 예를 들어 /var/lib/obs-agent/profile-cache-private와 같은 형태입니다.

위치/장소 콘텐츠
tasks/ 세션 데이터, 메시지, 그리고 실행 이벤트
transcripts/ 실행 기록
work/ 개인 작업 디렉터리
runtime.log, worker.log 로컬 실행 로그

obscli는 세션을 보관하기 위해 private/<connection-scope-id>/에 별도의 캐시를 유지하며, 일반적으로는 ~/.obscli/private/에 저장됩니다. --config-dir는 그 위치를 변경합니다. 이 클라이언트 캐시는 Agent 데이터와는 별개입니다. 세션을 보존하기 위해 Agent 개인 데이터 디렉터리를 백업해야 합니다.

서비스들도 여전히 접근 가능합니다.

첫 번째 연결 및 재연결 시, Agent은 Beak에게 개인 신분증과 현지 Agent의 접근 권한을 확인하도록 요청합니다. 만약 Beak에 접속할 수 없다면 새로운 연결은 실패합니다. 기존 연결 및 승인된 작업은 일시적인 인증 중단 동안 자동으로 중단되지 않지만, 개인 토큰의 유효 기간이 만료되면 연결이 종료됩니다.

클라이언트는 여전히 @ 리소스와 $, Skill 목록을 Beak에서 읽을 수 있습니다. 이러한 쿼리에는 비공개 메시지, 초안, 세션 ID가 포함되어 있지 않습니다. 선택된 항목은 로컬 소켓을 통해 메시지와 함께 전송됩니다. 일반적인 Profile 동기화는 계속 진행됩니다; 비공개 실행은 준비된 Skills 및 MCP 설정을 사용합니다.

구성된 모델 서비스와 외부 도구는 여전히 작업에 필요한 입력을 받습니다. 프라이빗 모드는 별도의 운영 체제 샌드박스가 아닙니다. 운영 체제 계정을 공유하는 사용자도 해당 계정이 접근할 수 있는 파일들을 여전히 읽을 수 있습니다.

obscli 자동 업데이트 방식

설치 스크립트로 설치한 경우, obscli는 시작 시 새 버전을 확인합니다. 새 버전이 있으면 다음과 같이 안내합니다:

New obscli version available: v1.2.3 -> v1.2.4. Update now? [y/N]

y 또는 yes를 입력하면 obscli는 현재 시스템용 패키지를 다운로드하고, .sha256을 검증한 후 로컬 실행 파일을 교체합니다. Linux/macOS는 업데이트 후 obscli를 자동으로 재시작합니다. Windows는 현재 프로세스가 종료된 후 교체가 완료되므로 obscli를 다시 실행해야 합니다.

현재 환경에서 시작 시 업데이트 확인을 비활성화하려면 다음을 설정하세요:

export OBSCLI_NO_UPDATE_CHECK=1

주요 명령어

명령어 용도
obscli 대화형 클라이언트 진입
obscli --private 로컬 Agent와 비공개 대화형 세션을 엽니다. 비공개 모드를 참조하세요.
/agents 일반 모드: 워크스페이스 전체에서 사용 가능한 Agents 목록을 표시합니다. 프라이빗 모드: 로컬의 Agent만 표시합니다.
/tasks 일반 모드: 워크스페이스 전체에서 열린 태스크를 목록으로 표시합니다. 프라이빗 모드: 오직 로컬의 프라이빗 태스크만 표시합니다.
/newtask <number> 지정 번호의 Agent로 Task 생성
/model 또는 /model select 모델 메뉴를 열어 자동, 빠른, 표준, 프로 또는 사용 중인 특정 모델 및 추론 설정을 선택합니다.
/model <model-id> [on\|off\|<effort>] 지원되는 모델에 따라, 현재 작업 모델을 직접 설정할 수 있습니다. 또는 특정 모델에 대해 별도의 레벨을 지정할 수도 있습니다.
/attach <number> 기존 Task 열기
/close <number> 현재 Task 또는 지정 번호의 Task 닫기
/compact 현재의 작업에서 컴팩트한 오래된 역사들을 수동으로 처리합니다.
/copy 가장 최근에 완성된 LLM 최종 답변을 로컬 시스템 클립보드에 복사합니다.
/clear 화면 지우기
/subagent <task> Agent에게 먼저 여러 하위 에이전트로 작업을 분할하도록 요청
/statusline 상태 표시줄 필드를 설정하고 ~/.obscli/config.toml에 저장
/yolo YOLO/Full access 모드 전환으로 파일 접근 제한 및 승인 프롬프트 해제
/exit 종료

표에서 <number>는 /agents 또는 /tasks의 # 열에 표시되는 임시 번호를 의미합니다. /newtask <number>는 /agents의 # 번호를 사용하고, /attach <number> 및 /close <number>는 /tasks의 # 번호를 사용합니다.

/agents와 /tasks에 워크스페이스 열을 표시합니다. /newtask <number> 또는 /attach <number> 후 현재 Session은 해당 워크스페이스로 전환됩니다. 메시지, 승인, 기록, 첨부 파일, @ 리소스 및 $ Skills는 계속 해당 워크스페이스를 사용합니다. 현재 Task를 닫으면 로그인 설정의 기본 워크스페이스로 돌아갑니다. 하단 표시줄은 현재 워크스페이스에 별도의 workspace 항목을, Agent/Task에 agent_task를 사용합니다. 둘 다 /statusline으로 조정할 수 있습니다.

닫힌 Task는 새 메시지를 받을 수 없습니다. 대화를 계속하려면 새 Task를 생성하세요.

읽기 전용의 IM 검사

일반 모드에서는 워크스페이스 소유자와 wsAdmins가 /tasks를 사용하여 자신의 관리 권한 내에서 일반 IM 세션과 IM Bot의 주요 대화 및 하위 작업을 목록화할 수 있습니다. /attach <number>를 사용하면 메시지, 첨부 파일, 도구의 이력을 확인할 수 있습니다. 일반 회원은 이러한 기능을 사용할 수 없습니다. 프라이빗 모드에서는 이러한 세션이 포함되지 않습니다.

클라이언트는 읽기 전용 알림을 표시합니다. 역사 내용을 확인하고 세션을 전환할 수 있지만, 메시지를 전송하거나 작업 승인, 취소 또는 종료, 모델 변경, 또는 다른 세션 설정 변경은 불가능합니다. 승인 및 작업 관련 작업은 원본 IM 채팅에서 요청자의 권한 하에 처리됩니다. 이 기능은 웹 봇의 상호 작용을 지원하지 않습니다.

모델과 추론 수준을 선택하세요.

작업에 들어간 후 /model을 실행하여 Auto, Fast, Standard, Pro 또는 Agent가 지원하는 특정 모델을 선택하세요. 메뉴에는 모델 설명과 배수가 표시됩니다. 추론 설정이 있는 모델은 지원되는 수준이나 켜기/끄기 옵션을 제공하며 기본 수준이 미리 선택됩니다. 어느 메뉴든 취소하면 변경 사항을 저장하지 않습니다.

또한 /model Vendor/Model-A high 또는 /model Vendor/Model-A off를 입력할 수도 있습니다. 특정 모델 ID는 대소문자를 구분합니다. 메뉴에는 지원되는 추론 수준 목록이 나와 있습니다. 네 가지 고정된 모드에서는 여전히 auto, auto:fast, auto:standard, auto:advanced를 사용하며, 수동적인 추론 매개변수는 허용되지 않습니다.

재부착은 작업의 모델과 추론 설정을 복원합니다. 새로운 작업은 현재 워크스페이스에서 계정이 최근에 내린 명시적인 선택을 상속합니다. 모델이 일시적으로 사용할 수 없다면, 메뉴는 선택된 내용을 유지하며 현재 전환이 자동 모드를 사용한다는 것을 나타냅니다. 카탈로그 오류는 재시도를 제공하며, 고정된 모드도 사용할 수 있습니다.

상태 라인에는 model <selected-name>(R:<levels>) -> <true-provider-name>와 같은 값이 표시됩니다. 예를 들어 model MiniMax-M3.1-Flash-Preview(R:on) -> MiniMax/MiniMax-M3.1-Flash-Preview와 같은 값도 있습니다. 왼쪽에는 선택된 모델과 추론 설정이 표시됩니다. 예를 들어 on, off, low, high, max와 같은 값들이 있습니다. 오른쪽에는 AIHub 이름 매핑 후에 반환된 실제 제공자 모델이 표시됩니다. 실제 모델 이름이 전달되기 전에는 오직 왼쪽에 있는 값만 표시됩니다. (R:...)는 수동적인 추론 설정 없이 생략됩니다.

Agent 접근 제어

/yolo는 토글입니다:

  • 첫 번째 사용: Full access 모드 진입. Agent가 작업 디렉터리 외부의 파일에 접근할 수 있으며, 도구 호출 시 승인을 요청하지 않습니다.
  • 두 번째 사용: 일반 모드로 복귀하여 파일 접근 제한 및 승인 프롬프트를 복원합니다.

현재 Agent와 Task 컨텍스트를 신뢰하는 경우에만 YOLO를 활성화하세요.

하위 에이전트로 작업 분할

작업을 독립적인 부분으로 나눌 수 있는 경우, /subagent <task>를 사용하여 Agent에게 먼저 하위 에이전트를 활용하도록 요청합니다. 예:

/subagent Check error logs, slow queries, and alert events from the past hour separately, then summarize root-cause clues

obscli는 각 하위 에이전트의 시작, 대기 및 완료 상태를 표시합니다. 메인 Agent가 최종 결과를 요약합니다. 방향키로 입력 기록에서 전체 명령을 불러올 수 있습니다.

컴팩트한 작업 기록을 수동으로 관리합니다.

만약 장기간 지속되는 작업이 모델 컨텐츠의 제한에 도달하면, Agent는 자동으로 더 오래된 대화 및 도구 관련 정보를 압축합니다. 컨텐츠 공간을 더 빨리 확보하기 위해, 현재 작업 내에서 다음 명령을 실행하세요:

/compact

압축 기능은 최근의 원시 데이터를 보관하고, 더 오래된 데이터를 세션 요약 정보로 변환합니다. 이 과정에서 작업을 종료하거나 세션 이벤트 기록을 완전히 삭제하지 않습니다. obscli는 세션의 시작 및 완료 상태를 표시합니다. 만약 현재 보관된 데이터가 보관 예산 내에 있다면, Agent는 압축이 필요하지 않다고 보고합니다.

최종적인 답변을 복사하세요.

현재의 작업에서 /copy를 실행하여, 최근에 완성된 LLM의 최종 답변을 마크다운 형식으로 원본 그대로 시스템 클립보드에 저장합니다. 이 작업은 obscli가 실행 중인 머신에서 이루어집니다.

/copy

/copy는 어떠한 인수도 받지 않으며, 오직 최종 결과만을 복사합니다. 이는 사고 과정, 해석, 도구 호출, 태스크 인사이트, 서브앱티브의 전달 등 런타임 관련 세부 정보를 제외한 것입니다. plan_final도 복사 가능한 최종 결과로 간주됩니다. 진단 관련 정보를 수집하기 위해, Agent를 사용하여 런타임 세부 정보를 클립보드를 통해 전송하는 대신 collect_bug_report를 사용하도록 지시해야 합니다.

만약 최신 전환 과정에서 최종적인 답변을 얻지 못했다면, obscli은 이전에 완성된 답변을 복사하여 경고를 표시합니다.

복잡한 작업의 계획 및 실행

/plan을 사용하여 Plan 모드에 진입합니다:

/plan [prompt]

예:

/plan I want to build a dashboard. Please create a plan.

계획을 받은 후 승인, 거부, 수정 요청 또는 중단할 수 있습니다:

/plan-approve
/plan-approve /subagent [instruction]
/plan-reject [reason]
/plan-revise <feedback>
/plan-interrupt [reason]
명령어 용도
/plan Plan 모드 진입 후 계획 요청 대기
/plan <prompt> Plan 모드 진입 후 즉시 계획 요청 제출
/plan-approve 최신 계획 승인
/plan-approve /subagent [instruction] 계획을 승인하고 하위 에이전트 분할 실행을 우선 적용
/plan-reject [reason] 계획을 거부하고 이유 설명
/plan-revise <feedback> 수정 피드백 제출
/plan-interrupt [reason] 현재 계획을 중단하고 Plan 모드 종료

일반 메시지는 자동으로 Plan 모드에 진입하지 않습니다. 활성 계획이 있는 Task를 닫으면 해당 계획도 중단됩니다.

스크립트에서 단일 프롬프트 실행

obscli run을 사용하여 일회성 작업을 제출하고 Agent의 응답을 기다린 후 종료합니다. 셸 스크립트 및 자동화에 사용됩니다.

임시 자격 증명이 필요한 작업에서는 --import-credential /secure/credentials.json를 사용하여 텍스트와 파일을 가져올 수 있습니다. 프롬프트는 모든 업로드가 확인된 후에만 전송됩니다. 작업을 완료하면 세션이 종료되며 자격 증명도 취소됩니다. 형식과 경로에 대한 정보는 Private Session Credentials를 참조하십시오. 프롬프트에는 비밀 정보를 입력하지 마십시오.

먼저 obscli --login <YOUR-USER-SK>로 로그인하세요. run은 기존의 로그인 설정을 읽어오므로 스크립트가 자격 증명을 다시 전달할 필요가 없습니다.

obscli -h 또는 obscli run -h를 실행하여 지원되는 모든 run 옵션을 확인하세요.

만약 에이전트 UUID를 모르는 경우, 계정의 워크스페이스 전체에서 사용 가능한 Agents 목록을 확인하세요.

obscli run --list-agents
obscli run --list-agents --json
obscli run --list-agents --workspace-uuid <WORKSPACE_UUID>

기본 출력에는 워크스페이스, Agent UUID, 이름, 그리고 creating, idle, busy, 또는 offline 상태가 포함됩니다. --json에는 스크립트용 workspace_uuid과 workspace_name도 포함됩니다. --workspace-uuid, obscli은 계정 수준 목록을 먼저 읽고 클라이언트에서 필터링합니다. 이 명령어는 작업을 생성하지 않습니다.

프롬프트 직접 전달:

answer="$(obscli run --agent-uuid <AGENT_UUID> --prompt 'Check errors from the past hour and summarize them briefly')"
printf '%s\n' "$answer"

기본적으로, 작업은 로그인 설정에 따라 워크스페이스에 생성됩니다. 다른 워크스페이스에서 실행하려면, 명시적으로 지정해야 합니다:

obscli run --workspace-uuid <WORKSPACE_UUID> --agent-uuid <AGENT_UUID> --prompt 'Check the current status'

작업을 생성하기 전에, run는 선택된 워크스페이스에 Agent가 존재하고 현재 계정에 접근 가능한지 확인합니다. 다른 워크스페이스에서 Agents나 Agents가 없으면 선택 과정에서 즉시 실패합니다. --json에서 발생하는 오류 코드는 agent_not_found이며, 종료 코드는 2입니다. 인증, 네트워크 또는 서비스 관련 문제로 인해 작업 생성이 중단될 수도 있습니다. 일시적으로 오프라인 상태인 등록된 Agents도 여전히 작업을 받을 수 있습니다. 이 명령어는 복구 및 응답이 도착할 때까지 대기합니다.

모델과 추론 수준을 선택하기 위해:

obscli run --agent-uuid <AGENT_UUID> --model <MODEL_ID> --reasoning high --prompt 'Analyze the current status'

--reasoning는 해당 모델의 사용 가능한 레벨, 즉 on와 off를 지원하며, 특정 모델 ID가 필요합니다. 추론을 생략하면 해당 모델의 기본 동작이 사용됩니다. 모델을 생략하면 서버가 가장 최신의 명시적인 선택 내용을 따르도록 합니다. obscli chat도 마찬가지로 --model와 --reasoning 옵션을 지원합니다.

여러 줄의 파일 또는 stdin 읽기:

obscli run --agent-uuid <AGENT_UUID> --prompt-file ./prompt.md
printf '%s\n' 'Summarize the health of the current workspace' | \
  obscli run --agent-uuid <AGENT_UUID> --prompt-file -

정규화된 프롬프트는 기본적인 작업 제목입니다. 스크립트는 --title를 사용하여 별도의 제목을 지정할 수 있습니다. 이 제목은 Agent에게 전송되는 프롬프트에는 포함되지 않습니다.

printf '%s\n' '分析最近两小时的错误日志' | \
  obscli run --agent-uuid <AGENT_UUID> --title gceval-l4-log-pattern --prompt-file -

기본적으로 stdout에는 Agent가 반환한 원시 Markdown만 포함되며 정상 진행 상황은 stderr에 기록되지 않습니다. 구조화된 결과를 얻으려면 --json을 사용하세요:

obscli run --agent-uuid <AGENT_UUID> --prompt 'Return a one-line status summary' --json

JSON 결과에는 응답, 관련 UUID, Agent UUID, Task 이름이 포함됩니다. 사용량 및 첨부 파일 정보도 가능한 경우 반환됩니다.

obscli run의 기본 종단 간 제한 시간은 2시간이며 작업 준비, 프롬프트 제출 및 최종 응답까지 포함합니다. --timeout 90s로 변경할 수 있습니다. 이 제한은 대화형 채팅이 아닌 단일 run 명령에 적용됩니다. 개별 모델 요청과 도구 실행은 각각의 제한 시간을 유지합니다. -v, -vv, -vvv 또는 --verbose=1|2|3으로 진단 정보 수준을 선택하여 표준 오류에 출력합니다. 기본적으로 Agent가 위험한 도구의 승인을 요청하면 명령은 해당 턴을 취소하고 코드 3으로 종료합니다. Full access의 위험을 명시적으로 수락할 때만 --yolo를 사용하세요.

일회성 작업에서 하위 에이전트를 우선 사용하도록 하려면 --subagent를 추가하세요:

obscli run --agent-uuid <AGENT_UUID> --subagent \
  --prompt 'Check errors, slow queries, and alerts from the past hour separately, then summarize the evidence'

작업을 합리적으로 분할할 수 없는 경우, Agent가 이유를 설명하고 직접 응답합니다. --subagent는 --list-agents와 함께 사용할 수 없습니다.

obscli run은 Plan 모드를 지원하지 않습니다. 계획은 여러 차례의 확인이 필요하기 때문입니다. 계획을 승인하거나 수정하려면 대화형 obscli를 사용하세요.

주요 종료 코드:

종료 코드 의미
0 응답을 수신하고 Task가 성공적으로 완료됨
1 API, 메시지 스트림, Agent 실행 또는 Task 정리 실패
2 잘못된 인수 또는 로컬 프롬프트 입력 오류
3 도구 호출에 승인이 필요함
4 Agent가 추가 입력을 요청했으나 일회성 Task에서는 대화형으로 계속할 수 없음
124 실행 시간 초과
130 / 143 SIGINT / SIGTERM 수신

--json 모드에서 실패 시 stdout은 비어 있으며 stderr에 error.code 및 error.message를 포함하는 JSON 객체가 반환됩니다. 스크립트는 종료 코드와 이 필드를 사용하여 결과를 판별해야 합니다.

메시지에서 리소스 및 Skill 참조

현재 세션의 워크스페이스에서 관찰 자원을 참조하기 위해 인터랙티브 입력란에 @를 입력하세요.

  • Service
  • Dashboards
  • Application
  • Hosts
  • Containers

방향키 또는 Tab으로 탐색하고, Space로 하나 이상의 항목을 선택한 후 Enter로 확인합니다. 입력하면 리소스 이름과 유형을 검색할 수 있습니다. 선택된 리소스는 @resource-name으로 표시되며 Agent에 쿼리 컨텍스트를 제공합니다.

단일 Agent Task에 연결된 상태에서 $를 입력하면 해당 Agent가 제공하는 Skill을 선택할 수 있습니다. 검색은 Skill 이름과 설명을 매칭하며 공백을 무시하므로, rootcause로 Root cause analysis를 검색할 수 있습니다. 선택 방식은 리소스 목록과 동일하며, 선택된 모든 Skill은 전체 메시지에 적용됩니다.

두 목록 모두 Enter로 확인하기 전에 Space로 선택해야 합니다. 검색해도 기존 선택은 유지됩니다.

@resource-name 또는 $skill-name의 경계에서 Backspace 또는 Delete를 누르면 전체 참조가 삭제됩니다. 방향키 또는 Ctrl+R로 메시지를 불러오면 리소스와 Skill도 함께 복원됩니다.

리터럴 @ 또는 $를 입력하려면 목록이 열린 후 Esc를 누르세요. 붙여넣은 @ 및 $도 일반 텍스트로 유지됩니다.

Task를 연 후 메시지를 입력하고 Enter를 누르세요. Task에 Agent가 하나인 경우 해당 Agent에게 메시지가 전송됩니다. 여러 Agent가 있는 경우 모든 Agent에게 메시지가 브로드캐스트됩니다.

키보드 단축키 사용

일반 입력에서 지원하는 단축키:

일반 입력:

키 동작
Enter 현재 입력 전송; 슬래시 명령 선택 시 강조된 명령 수락
Shift+Enter / Alt+Enter 줄바꿈 삽입
Esc 현재 입력 취소 확인 표시
Esc 두 번 현재 입력 또는 현재 채팅 취소
↑ / ↓ 입력 기록 탐색; 슬래시 명령 선택 시 강조 이동
← / → 커서를 좌우로 이동
Home / End 줄의 시작 또는 끝으로 이동
Backspace 커서 앞 문자 삭제
Delete 커서 위치의 문자 삭제
Tab 슬래시 명령의 공통 접두사 완성
Ctrl+A / Ctrl+E 줄의 시작 또는 끝으로 이동
Ctrl+C 비어 있지 않은 입력 지우기; 입력이 비어 있으면 현재 상호작용 종료
Ctrl+L 화면을 지우고 현재 입력 유지
Ctrl+R 입력 기록 검색
Ctrl+T 전체 화면 모드로 도구 세부 정보를 열어보세요. q는 채팅창으로 돌아가서 드래프트를 복원합니다.
Ctrl+W 이전 단어 삭제
텍스트 직접 입력 커서 위치에 텍스트 삽입

슬래시 명령어가 Beak를 기다리는 동안, Ctrl+C 또는 Esc을 두 번 누르면 로컬 수준의 대기 상태를 중단할 수 있습니다. 대기 중에 입력된 텍스트는 초안으로 남아 있으며, 다시 Enter 키를 눌러 제출해야 합니다. 취소는 이미 완료된 서버 작업을 취소하지 않습니다. 만약 어떤 작업이 이미 이루어졌다면, 다시 시도하기 전에 그 작업의 상태를 확인해야 합니다.

자격 증명 양식도 네트워크 응답을 기다리는 동안 이 취소 키를 지원합니다. 대기 중에 입력하거나 붙여 넣은 텍스트는 폐기하므로 비밀 정보가 일반 채팅 초안, 로그 또는 캐시에 들어가지 않습니다.

도구 상세 화면에서는 방향키나 마우스 휠로 스크롤하고 PageUp/PageDown으로 페이지를 바꾸며 Home/End로 처음/끝으로 이동합니다. Ctrl+P/Ctrl+N으로 호출 간 이동을 합니다. 뷰어를 열면 가장 최근 호출의 시작 부분이 선택됩니다. 입력, 붙여넣기 및 Enter는 채팅 메시지를 수정하거나 제출하지 않습니다. 새 결과가 도착해도 읽던 위치를 유지합니다. 끝까지 스크롤하면 새 내용을 따라갑니다. 승인이 도착하면 q로 돌아가 처리하세요.

일반 모드에서는, 로드된 후 수신된 채팅 내용이 ~/.obscli/cache/sessions/YYYY/MM/DD/<session-id>.jsonl에 캐싱됩니다. 이때 도구의 세부 정보는 고려되지 않습니다. 각 세션은 재시작 및 첨부 과정에서 원래의 캐싱 날짜 디렉터리를 유지합니다. 프라이빗 모드는 별도의 캐싱을 사용합니다. 세션 저장 및 복구에 대한 내용은 Session storage and recovery를 참조하세요. 이 기능은 로컬 Agent에서 기록된 정보를 가져옵니다. 일반 모드에서는, 인터랙티브 터미널이 최근의 로컬 채팅 내용을 먼저 표시한 후, 백그라운드에서 사용 가능한 모든 Beak 기록을 펼쳐줍니다. 파이프나 스크립트 입력이 가능한 경우, 다음 명령어를 읽기 전에 기록을 먼저 로드하여, /save나 /exit와 같은 명령어들의 순서를 유지합니다. 저장된 메시지 체크포인트에서 새로운 이력을 다시 불러오고, 연결이 끊기기 전에 미완료된 “답변 실행” 관련 정보도 별도로 확인합니다. 이미 동일한 버전으로 동기화된 완료된 통화 내용의 세부 정보는 다시 다운로드되지 않습니다. 동기화 실패로 History sync incomplete 상태가 표시됩니다. 다시 연결하거나 도구 세부 정보를 열어 시도해보세요. 미완료된 과정의 페이지 넘어짐을 계속 진행할 수 있습니다. 이전에 동기화된 도구 정보는 Ctrl+T에서 확인할 수 있습니다. 일반 채팅창에서는 최근 메시지와 도구 예시가 표시됩니다.

같은 세션과 Agent 내에서 각 tool_call_id는 하나의 호출을 식별합니다. 기존 로컬 인수, 설명 및 전체 결과를 우선 유지합니다. 원격 기록은 누락된 내용과 오프라인 중 생성된 최종 상태 또는 결과를 채웁니다. 마스킹된 요약은 전체 로컬 텍스트를 덮어쓰지 않으며 종료 상태가 실행 중으로 되돌아가지 않습니다. 일반 채팅 기능과 Ctrl+T 기능은 동일한 기록을 읽습니다. 순서와 관련 없는 충돌이 발생할 경우, 이전 상태가 유지됩니다. SQLite 측면 파일에는 JSONL 오프셋, 순서, 중복 제거, 동기화 인덱스만 저장되며, 매번 열기될 때마다 다시 생성됩니다. 텍스트, 원본 정보, 동기화 점검점은 JSONL에 남아 있습니다. 기존의 캐시는 이동할 필요가 없습니다. 세션 전환이나 종료는 백그라운드 요청을 취소합니다. 캐시가 쓰기 불가능한 경우, 사용 가능한 기록만 표시되며, 그에 대한 설명도 함께 제공됩니다. 캐시 인증은 서버, 워크스페이스, 사용자, 세션을 확인합니다. 30일 동안 변경되지 않은 사용되지 않은 파일들은 정리됩니다.

도구의 세부 정보는 256 KiB/통화당 또는 최신 50 통화 수에만 국한되지 않습니다. 기존의 Beak 편집, 단축, 참조 텍스트는 그대로 유지됩니다. 시청자는 채팅 도구의 제목, 분리자, 명령어 강조 표시를 그대로 유지하며, 스크롤 및 크기 조정 과정에서도 indented JSON 및 Markdown 형식을 유지할 수 있습니다. 진행 상황에 대한 피드백과 코멘트는 완료 후에도 여전히 사용할 수 있습니다.

완전한 논증을 제시하기 위해서는 새로운 Agent가 필요합니다. 구형 Agents 또는 완전한 논증이 없는 캐시는 사용할 수 없는 메시지를 표시하며, 기존의 요약 정보도 함께 표시됩니다. 역사적인 논증들은 Beak의 편집된 형태를 유지합니다. 줄이 짧은 논증, 명령어, 해석, 그리고 결과들은 ...+<n> lines (ctrl+t to view transcript)를 사용합니다.

도구 번호는 각 세션 캐시에서 1부터 시작하며 처음 나타난 순서를 따릅니다. 대화 턴이나 재접속 후에도 유지됩니다. 일반 채팅에서는 기본적으로 숨겨집니다. /tool-index on|off는 보관된 기록과 실행 중인 도구를 즉시 다시 그리고 ~/.obscli/config.toml에 show_tool_index를 저장합니다. 번호는 회색 (n)으로 표시되며 배치의 [i/count]와 구분됩니다. Ctrl+T에서는 항상 번호를 표시합니다. g를 누르고 번호를 입력한 후 Enter를 누르면 해당 위치로 이동하고 Esc는 취소합니다. 잘못된 번호는 현재 위치를 유지합니다. 이동하면 자동 따라가기를 중지합니다. Ctrl+P/N은 계속 채팅 순서를 따릅니다. 번호는 같은 로컬 캐시 내에서만 안정적이며 캐시를 사용할 수 없으면 대체 번호를 생성하지 않습니다.

도구 제목에는 read_skill와 read_skill_file와 같은 도구 이름이 표시되며, Skill라는 이름과 경로는 아래에 위치합니다. 도구 이름이 없는 오래된 기록들은 기존의 표시 이름을 그대로 유지합니다.

추론 과정에서, Thinking...는 최신 5줄의 텍스트를 유지하며, 긴 텍스트는 자동으로 잘려서 표시됩니다. 완성된 결과물은 제한된 미리보기 형태로 남아 있으며, 완전한 이벤트 정보는 캐싱되어 저장됩니다. 비대화형 출력 결과물은 모든 텍스트를 그대로 유지합니다. 120 유니코드 문자보다 긴 각 문자열은 head (x omitted...) tail로 단축되며, x는 생략된 문자 수를 나타냅니다. 미리보기 결과는 120 범위 내에 유지되며, 처음의 60 내용도 그대로 유지됩니다. 생략된 부분에 대한 알림도 함께 표시됩니다. 다른 인수들은 그대로 유지되며, JSON 객체는 전체적으로 잘려서 표시되지 않습니다. Ctrl+T를 사용하면 전체 인수와 결과를 확인할 수 있으며, 민감한 값들은 숨겨져 있습니다. 전체 텍스트가 없는 과거 저장된 요약문은 설명적인 알림을 유지합니다. 캐싱이나 기록 관련 오류가 발생할 경우, 세부 정보가 표시되지 않는 알림이 나타나며, 다른 콘텐츠는 여전히 읽을 수 있습니다.

팝업 선택:

키 동작
↑ / Ctrl+P 강조를 위로 이동; 첫 번째 항목에서 마지막 항목으로 순환
↓ / Tab / Ctrl+N 강조를 아래로 이동; 마지막 항목에서 첫 번째 항목으로 순환
Shift+Tab 강조를 위로 이동; 첫 번째 항목에서 마지막 항목으로 순환
Space 강조 이동 없이 현재 항목 토글; 실패한 리소스 유형 재시도 후 로딩 성공 시 선택
Enter 선택된 모든 항목 제출; 선택된 항목이 없으면 팝업 유지
Esc 현재 팝업 취소; 리소스 항목 목록에서는 먼저 유형 목록으로 복귀; 승인 팝업에서는 현재 채팅 취소
Ctrl+C 팝업을 취소하고 현재 상호작용 종료
Backspace 검색 텍스트의 마지막 문자 삭제
Ctrl+U 검색 텍스트 지우기
텍스트 직접 입력 또는 붙여넣기 목록을 퍼지 필터링하고 강조를 첫 번째 항목으로 초기화

터미널에서 방향키 또는 제어 키가 작동하지 않는 경우, 먼저 터미널이 해당 단축키를 외부 애플리케이션에 바인딩했는지 확인하세요. 문제가 지속되면 ~/.obscli/log/obscli.log를 열고 터미널 이름, 버전, 키 동작을 기록하세요.

로컬 파일

obscli는 기본적으로 다음 로컬 경로를 사용합니다:

Linux/macOS:

~/.obscli/login.toml
~/.obscli/log/obscli.log

Windows:

%USERPROFILE%\.obscli\login.toml
%USERPROFILE%\.obscli\log\obscli.log

로그는 자동으로 로테이션됩니다. 단일 로그 파일의 기본 최대 크기는 32 MiB입니다.

문제 해결

로그인 실패 시 다음을 확인하세요:

  • --beak-server가 Beak 서비스 주소를 가리키는지 확인합니다.
  • 설치 스크립트를 통해 로그인하는 경우, --beak-server가 Beak 서비스 주소를 가리키는지 확인합니다.
  • 사용자 sk가 현재 Beak 웹 페이지에서 복사한 유효한 자격 증명인지 확인합니다.
  • HTTPS 테스트 환경에 --insecure-skip-tls-verify가 필요한지 확인합니다.

채팅 진입 후 Task가 없는 경우 다음을 실행하세요:

/agents
/newtask <number>

여기서 <number>는 /agents의 # 열에 표시되는 번호입니다.

지역 진단 보고서

obscli bug-report view ./report.zip를 사용하여 완전히 오프라인 상태에서 진단 보기를 열 수 있습니다. --no-open를 추가하여 브라우저를 실행하지 않도록 합니다. 이 서비스는 무작위로 할당된 루프백 포트를 통해만 작동합니다. 자세한 내용은 로컬 버그 보고서 보기를 참조하십시오.

문서 평가

이 페이지가 도움이 되었나요?