AI 에이전트를
어디든 함께 가지고 다니세요

사전 요구 사항

• OpenCode 2.x 설치됨 (opencode --version이 2.x 표시)
• 아직 opencode 1.x를 사용 중인가요? opencode 탭을 사용하세요. OpenCode 2는 새로운 플러그인 API를 사용합니다

OpenCode 2 설치 (공식)

OpenCode 2는 별도의 메이저 버전입니다. 공식 설치 방법:

# macOS / Linux (공식 원라이너)
curl -fsSL https://opencode.ai/v2/install | bash

# npm (macOS / Linux / Windows)
npm install -g @opencode/cli

# Homebrew
brew install anomalyco/tap/opencode-v2

OpenCode 2는 Windows 패키지 관리자(Chocolatey / Scoop)를 지원하지 않습니다. npm 또는 독립 실행 바이너리를 사용하세요.

tunnelbox 어댑터 설치

// opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["@tunnelbox/opencode2"]
}

실행 및 페어링

opencode serve

선택 설정 및 팁

공식 릴레이 연결에는 설정이 필요 없습니다. 사용자 지정 릴레이를 쓰려면 TUNNELBOX_RELAY_URL을 설정하거나 객체 형식으로 options.relayUrl을 전달하세요:

// opencode.jsonc (사용자 지정 릴레이)
{
  "plugins": [{ "package": "@tunnelbox/opencode2", "options": { "relayUrl": "wss://relay.tunnelbox.top" } }]
}

상태 파일은 ~/.tunnelbox/remote-state.json에 저장됩니다. 1.x 어댑터(@tunnelbox/opencode)와 이 2.x 어댑터는 같은 PC에서 별행 실행되며 각각 독립적으로 페어링됩니다.

사전 요구 사항

• Node.js ≥ 22 (tunnelbox 어댑터 필요)
• 유료 Claude 플랜(Pro / Max / Team) 또는 Anthropic Console API 키

Claude Code 설치(공식)

먼저 Claude Code 본체를 설치하세요(공식 네이티브 설치 프로그램——자동 업데이트, 추가 런타임 불필요):

# macOS / Linux / WSL (official native installer)
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

설치 후 claude --version이 작동하면 성공입니다. 첫 실행 시 유료 Claude 계정으로 로그인하세요.

설치 단계

# no repo clone needed
npm install -g @tunnelbox/claude-code

실행 및 페어링

tunnelbox-claude-code

선택 설정 및 팁

모두 선택 사항입니다. 일반적인 예:

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_CWD=D:/workspace/project \
TUNNELBOX_CLAUDE_MODE=plan \
tunnelbox-claude-code

도구 승인은 기본적으로 스마트폰으로 전송됩니다(허용 / 거부 / 항상 허용). 연결이 끊기거나 120초가 초과되면 자동으로 거부됩니다(fail-closed)——자동 승인되지 않습니다. 모드: default / plan / acceptEdits / bypassPermissions.

사전 요구 사항

• Node.js ≥ 22
• OpenAI 계정(ChatGPT Plus / Pro 또는 플랫폼 API 키)과 codex app-server 하위 명령을 지원하는 Codex CLI

Codex CLI 설치(공식)

먼저 Codex CLI 본체를 설치하세요(공식 설치 프로그램 또는 npm):

# macOS / Linux (official installer)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows PowerShell
irm https://chatgpt.com/codex/install.ps1 | iex

# or Node: npm install -g @openai/codex
npm install -g @openai/codex

codex --version으로 확인한 뒤 codex login으로 로그인하세요. 어댑터 자체 점검: tunnelbox-codex --check(codex app-server 사용 가능 여부 확인).

설치 단계

# no repo clone needed
npm install -g @tunnelbox/codex

실행 및 페어링

tunnelbox-codex

선택 설정 및 팁

모두 선택 사항입니다. 일반적인 예:

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_CODEX_SANDBOX=workspace-write \
tunnelbox-codex

# optional: TUNNELBOX_CODEX_APPSERVER_ARGS="--stdio"

승인과 선택은 네이티브입니다: codex가 도구 승인 요청과 객관식 질문을 스마트폰으로 바로 보내며(허용 / 거부, 옵션 선택), 추론 과정은 실시간 스트리밍됩니다. 연결 끊김 / 시간 초과는 자동 거부(fail-closed)입니다. 허용 범위는 여전히 TUNNELBOX_CODEX_SANDBOX에 따릅니다(read-only / workspace-write / danger-full-access).

사전 요구 사항

• Node.js ^22.19 또는 >=24
• DeepSeek API 키(dsh 자격 증명은 $DSH_HOME/.credentials.yaml, 기본값 ~/.dsh)

DeepSeek Harness 설치(공식)

먼저 dsh 본체를 설치하세요(DeepSeek 공식 npm 패키지, Node.js ^22.19 또는 >=24 필요):

# Install dsh globally (official package)
npm install -g @deepseek-ai/dsh

# or try instantly: npx @deepseek-ai/dsh web

설치 후 dsh --version이 작동하면 성공입니다. 처음 사용할 때 DeepSeek API 키를 설정하세요($DSH_HOME/.credentials.yaml에 저장).

설치 단계

dsh plugin --profile tunnelbox add @tunnelbox/dsh-tunnelbox
dsh --profile tunnelbox --dump-config   # verify the tunnelbox-dsh layer

실행 및 페어링

dsh --profile tunnelbox

선택 설정 및 팁

모두 선택 사항입니다. profile 설정 예시(cordis.patch.yml):

- id: tunnelbox-dsh
  config:
    relayUrl: 'wss://relay.tunnelbox.top'
    model: 'deepseek-flash'
    cwd: 'D:/workspace/project'

승인은 dsh의 approval / sandbox-policy를 따릅니다(기본 workspace-write + ask)——위험한 작업은 스마트폰으로 전송됩니다. 여러 인스턴스를 실행하려면 서로 다른 DSH_HOME을 설정하세요.

사전 요구 사항

• Node.js ≥ 22.19
• 로컬 OpenClaw Gateway ≥ 2026.6.11(protocol v4) 실행 가능——구 라인(< 2026.9.1)과 신 라인(≥ 2026.9.1) 모두 지원(런타임 기능 감지)

OpenClaw 설치(공식)

먼저 OpenClaw를 설치하고(공식 설치 프로그램) onboard 마법사를 완료하세요:

# macOS / Linux (official installer)
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

# finish the setup wizard after install
openclaw onboard

openclaw가 작동하고 Gateway가 실행 중이면 준비 완료입니다.

설치 단계

# no repo clone needed
npm install -g @tunnelbox/openclaw

openclaw devices list              # note the requestId
openclaw devices approve <requestId>

실행 및 페어링

tunnelbox-openclaw

선택 설정 및 팁

모두 선택 사항입니다. 일반적인 예:

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_OPENCLAW_GATEWAY_URL=ws://127.0.0.1:18789 \
tunnelbox-openclaw

세션 삭제는 Gateway를 통해 완전 삭제됩니다(sessions.delete, operator.admin 필요). 어댑터는 gateway.auth.token / password를 자동 검색합니다(설정, 환경 변수, 실행 중인 Gateway 프로세스 또는 2026.9.1 이후 자격 증명 파일). TUNNELBOX_OPENCLAW_TOKEN으로 재정의, --check-gateway-auth로 확인, --save-token으로 저장, TUNNELBOX_OPENCLAW_AUTOSTART=start|install로 Gateway 자동 시작이 가능합니다. 승인(exec/plugin)과 도구 카드(명령 인수 포함)는 스마트폰으로 전송됩니다. 대화형 선택 / 질문 카드는 Gateway ≥ 2026.7(question.*)이 필요하며, 구버전 Gateway는 이러한 프롬프트를 승인 또는 일반 텍스트로 표시합니다.

사전 요구 사항

• Node.js ≥ 22
• Hermes 계정 / 모델 API 키(hermes setup 시 설정)

Hermes Agent 설치(공식)

먼저 Hermes Agent를 설치하고(공식 설치 프로그램) 설정을 마치세요:

# official installer
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# finish setup after install
hermes setup

hermes chat -Q -q "hi"가 응답하면 준비 완료입니다.

설치 단계

# no repo clone needed
npm install -g @tunnelbox/hermes

실행 및 페어링

tunnelbox-hermes

선택 설정 및 팁

모두 선택 사항입니다. 일반적인 예:

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_HERMES_MODEL="anthropic/claude-sonnet-4" \
tunnelbox-hermes

참고: 이 헤드리스 어댑터는 스마트폰 승인을 제공하지 않습니다. 위험한 작업은 hermes 자체 보안 정책으로 제어됩니다(fail-closed). 세션은 실제 Hermes 세션으로 이어집니다(첫 턴 후 id 자동 검색). 대화형 세션의 승인 / 질문 흐름은 Hermes 공식 네이티브 플러그인(native-plugin/)에 있습니다.

사전 요구 사항

• Node.js ≥ 22
• Cursor 계정(헤드리스 사용은 Cursor 플랜으로 과금됨)

Cursor CLI 설치(공식)

먼저 Cursor CLI 본체를 설치하세요(공식 설치 프로그램):

# macOS / Linux (official installer)
curl https://cursor.com/install -fsS | bash

# Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex

agent -p "hello"가 정상 출력되면 준비 완료입니다(헤드리스 사용은 Cursor 과금 대상).

설치 단계

# no repo clone needed
npm install -g @tunnelbox/cursor

실행 및 페어링

tunnelbox-cursor

선택 설정 및 팁

모두 선택 사항입니다. 일반적인 예(plan 모드 + 파일 편집 허용):

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_CURSOR_MODE=plan \
TUNNELBOX_CURSOR_FORCE=1 \
tunnelbox-cursor

스마트폰 승인은 불가능합니다(Cursor hooks는 IDE / Cloud agent 전용이며, 헤드리스 agent -p에는 외부 승인 릴레이가 없음). 또한 print 모드는 사고 과정을 억제합니다(추론 카드 없음). 실제로 실행되는 내용은 permissions allow/deny + --force/--yolo + --sandbox로 결정됩니다. 기본은 읽기 전용(--force 없으면 에이전트는 제안만 하고 편집하지 않음). 실제로 편집하려면 TUNNELBOX_CURSOR_FORCE=1을 설정하세요. CLI가 아직 없다면 macOS / Linux는 curl https://cursor.com/install -fsS | bash, Windows는 irm 'https://cursor.com/install?win32=true' | iex.

사전 요구 사항

• Node.js ≥ 22
• CodeBuddy CLI 설치 및 로그인 완료(npm i -g @tencent-ai/codebuddy-code; codebuddy를 한 번 실행해 로그인하거나 CODEBUDDY_API_KEY 설정)

CodeBuddy CLI 설치(공식)

먼저 CodeBuddy CLI 본체를 설치하세요(npm 전역 설치):

# install the CodeBuddy CLI
npm install -g @tencent-ai/codebuddy-code

# first login (or use CODEBUDDY_API_KEY)
codebuddy

codebuddy --version이 버전을 출력하면 준비 완료입니다. 첫 실행에는 로그인이 필요합니다.

설치 단계

# no repo clone needed
npm install -g @tunnelbox/codebuddy

실행 및 페어링

tunnelbox-codebuddy

선택 설정 및 팁

모두 선택 사항입니다. 일반적인 예(plan 모드):

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_CODEBUDDY_MODE=plan \
tunnelbox-codebuddy

codebuddy --acp(ACP)를 구동합니다. 도구 승인은 스마트폰으로 전송됩니다(허용 / 거부 / 항상 허용). 오프라인이거나 120초 시간 초과 시 자동 거부(fail-closed). 선택 / 계획 / 질문은 네이티브 ACP입니다(AskUserQuestion / ExitPlanMode / elicitation). 로그인되어 있지 않으면 codebuddy를 한 번 실행해 로그인하세요(또는 CODEBUDDY_API_KEY 설정).

사전 요구 사항

• Node.js ≥ 22
• Kimi Code CLI 설치 및 로그인 완료(kimi를 한 번 실행하고 /login 전송)

Kimi Code CLI 설치(공식)

먼저 Kimi Code CLI 본체를 설치하고(공식 스크립트 또는 npm) 한 번 실행하여 /login을 전송하세요:

# macOS / Linux (official installer)
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

# Windows PowerShell
irm https://code.kimi.com/kimi-code/install.ps1 | iex

# first login
kimi   # then send /login

kimi --version이 버전을 출력하면 준비 완료입니다. 첫 실행에는 /login이 필요합니다.

설치 단계

# no repo clone needed
npm install -g @tunnelbox/kimi

실행 및 페어링

tunnelbox-kimi

선택 설정 및 팁

모두 선택 사항입니다. 일반적인 예(plan 모드):

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_KIMI_MODE=plan \
tunnelbox-kimi

kimi acp(ACP)를 구동합니다. 공식 기능 매트릭스에는 네이티브 session/list|resume|delete가 포함됩니다. 도구 승인과 질문 프롬프트는 session/request_permission을 공유하여 스마트폰으로 전송됩니다. 오프라인이거나 120초 시간 초과 시 자동 거부(fail-closed). 로그인되어 있지 않으면 kimi를 한 번 실행하고 /login을 전송하세요.

사전 요구 사항

• Node.js ≥ 22
• TraeCode CLI 설치 및 로그인 완료(traecli login). 참고: TraeCode CLI는 TRAE 엔터프라이즈 플래그십 플랜이 필요합니다

TraeCode CLI 설치(공식)

공식 문서에 따라 TraeCode CLI 본체를 설치한 뒤 로그인하세요:

# see https://docs.trae.cn/cli_what-is-trae-cli
traecli login

traecli --version이 작동하고 traecli login이 성공하면 준비 완료입니다.

설치 단계

# no repo clone needed
npm install -g @tunnelbox/trae

실행 및 페어링

tunnelbox-trae

선택 설정 및 팁

모두 선택 사항입니다. 일반적인 예(auto 권한 모드):

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_TRAE_PERMISSION_MODE=auto \
tunnelbox-trae

traecli acp serve(ACP)를 구동합니다. 공식 문서는 ACP 지원만 명시하고 기능 매트릭스를 공개하지 않아 이 어댑터는 실험적입니다——스트리밍 / 승인 / 선택 / 중단은 실제 CLI로 검증하세요(npm run probe). 승인은 기본적으로 fail-closed입니다. TraeCode CLI는 TRAE 엔터프라이즈 플래그십 플랜이 필요하며 기본은 Max 모드입니다(할당량 주의).

사전 요구 사항

• Node.js ≥ 22
• Qoder CLI 설치 및 로그인 완료(qoder login 또는 QODER_PERSONAL_ACCESS_TOKEN 설정)

Qoder CLI 설치(공식)

먼저 Qoder CLI 본체를 설치하고(npm) 로그인하세요:

# install Qoder CLI
npm install -g @qoder-ai/qodercli

# log in (or set QODER_PERSONAL_ACCESS_TOKEN)
qoder login

qoder --version이 버전을 출력하고 로그인되어 있으면 준비 완료입니다.

설치 단계

# no repo clone needed
npm install -g @tunnelbox/qoder

실행 및 페어링

tunnelbox-qoder

선택 설정 및 팁

모두 선택 사항입니다. 일반적인 예(auto 권한 모드):

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_QODER_PERMISSION_MODE=auto \
tunnelbox-qoder

qoder --acp(ACP)를 구동합니다. 도구 승인은 스마트폰으로 전송됩니다(허용 / 거부 / 항상 허용). 오프라인이거나 120초 시간 초과 시 자동 거부(fail-closed). 선택 / 계획 / 질문은 ACP 권한 채널을 통해 처리됩니다. 로그인되어 있지 않으면 qoder login을 실행하거나 QODER_PERSONAL_ACCESS_TOKEN을 설정하세요.