promptbox

OpenCode 2 — alternative harness setup OpenCode 2 — 대안 하네스 구성

A step-by-step beginner tutorial: receive a Z.ai key, install OpenCode 2, select GLM-5.3-Flash, and run text-and-image tasks. Z.ai 키를 받고 OpenCode 2를 설치한 뒤 GLM-5.3-Flash를 선택해 텍스트와 이미지 작업을 실행하는 단계별 튜토리얼이다.

promptbox defaults to pi. This page is the OpenCode 2 alternative using the same GLM-5.3-Flash model. promptbox 기본 하네스는 pi다. 이 페이지는 같은 GLM-5.3-Flash를 OpenCode 2에서 쓰는 대안 안내다.

STEP 0

Prepare a Z.ai API key준비물 — Z.ai API 키

You need one Z.ai GLM key. Two ways to get it: 필요한 것은 딱 하나, Z.ai GLM 키다. 받는 방법은 두 가지다:

  • Shared key from this console (recommended): log in to the ZAI Plan Console → 「API 키 금고」 → tap 「관리자에게 키 열람 요청」. Once the admin approves, the key appears in the vault — press 열람 to copy it. 이 콘솔에서 공유받기(권장): ZAI Plan Console에 Google 로그인 → 「API 키 금고」 화면 → 「관리자에게 키 열람 요청」 버튼 누르기. 관리자가 승인하면 금고에 공유 키가 나타나고, 「열람」 버튼으로 복사할 수 있다.
  • Your own subscription: subscribe to the GLM Coding Plan at z.ai and issue an API key from your dashboard. 직접 구독: z.ai에서 GLM Coding Plan을 구독하고, 대시보드에서 API 키를 발급받는다.

⚠ Treat the key like a password. Never paste it in chats or screenshots. If it leaks, ask for rotation immediately. ⚠ 키는 비밀번호다. 채팅·스크린샷에 절대 붙여넣지 말고, 유출되면 즉시 관리자에게 회전(교체)을 요청하라.

STEP 1

Open the terminal터미널 열기

macOS: press ⌘+Space, type 터미널 (or Terminal), Enter. Windows: press the Start key, type PowerShell, Enter. macOS: ⌘+스페이스를 누르고 터미널(또는 Terminal) 입력 후 엔터. Windows: 시작 버튼 → PowerShell 검색 → 엔터. 이후 모든 명령은 이 창에 입력한다.

STEP 2

Check Node.js (v22+)Node.js 확인 (v22 이상)

OpenCode installs through npm. Check Node first: OpenCode는 npm으로 설치한다. 먼저 Node를 확인한다:

node -v # v22 이상이면 OK. 아무 출력이 없으면 아래로

If the version is older or the command is not found, install Node 22: 버전이 더 낮거나 명령이 없다고 나오면 Node 22을 설치한다:

# macOS (nvm 권장): curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 터미널 재시작 후: nvm install 22 && nvm use 22 # Windows: https://nodejs.org 에서 LTS 인스톨러 설치
STEP 3

Install OpenCode 2OpenCode 2 설치

Install the v2 preview CLI. The npm package is @opencode-ai/cli on the beta tag, and the command it installs is opencode2 — this is the build this guide was verified on: v2 프리뷰 CLI를 설치한다. npm 패키지는 @opencode-ai/cli의 beta 태그이고, 설치되는 명령 이름은 opencode2다. 이 문서는 이 빌드에서 검증했다:

npm install -g @opencode-ai/cli@beta # 설치되는 명령 이름은 opencode2
opencode2 --version

v2 is a preview build. If you want the stable v1 line instead, the package is opencode-ai and the command is opencode — every step below then drops the 2: v2는 프리뷰 빌드다. 안정판 v1 계열을 원하면 패키지는 opencode-ai, 명령은 opencode다. 그 경우 아래 모든 단계에서 2만 빼면 된다:

# 예전 안정판(v1)을 쓰려면 — 명령 이름은 opencode curl -fsSL https://opencode.ai/install | bash npm install -g opencode-ai@latest # 같은 것, Windows는 이쪽
STEP 4

Connect your Z.ai keyZ.ai 키 연결

Run the login command, pick zai-coding-plan from the provider list, and paste the key. It is stored locally in ~/.local/share/opencode/auth.json and reused automatically — you only do this once. 로그인 명령을 실행하고 공급자 목록에서 zai-coding-plan을 고른 뒤 키를 붙여넣는다. 키는 내 컴퓨터의 ~/.local/share/opencode/auth.json에만 저장되고 다음부터 자동으로 쓰인다. 한 번만 하면 된다.

opencode2 auth login # 목록에서 zai-coding-plan 선택 → 키 붙여넣기

Then confirm the subscription actually unlocked the models — glm-5.3-flash must appear in this list: 그다음 구독으로 모델이 실제로 열렸는지 확인한다 — 목록에 glm-5.3-flash이 보여야 한다:

opencode2 models | grep zai-coding-plan # 내 구독으로 열리는 모델 확인
STEP 5

Set GLM-5.3-Flash as the default기본 모델을 GLM-5.3-Flash로 설정

GLM-5.3-Flash has a 1,000,000-token context and native text-and-image input. The snippet merges the model and maximum reasoning level into the existing OpenCode config: GLM-5.3-Flash는 컨텍스트 100만 토큰과 네이티브 텍스트·이미지 입력을 제공한다. 아래 스크립트는 기존 OpenCode 설정에 모델과 최대 사고 수준을 합친다:

python3 - <<'EOF' import json, os p = os.path.expanduser("~/.config/opencode/opencode.json") cfg = json.load(open(p)) if os.path.exists(p) else {} # 이미 있으면 보존하고 합친다 cfg["model"] = "zai-coding-plan/glm-5.3-flash" # 기본 모델 cfg.setdefault("provider", {}).setdefault("zai-coding-plan", {}) .setdefault("models", {})["glm-5.3-flash"] = {"options": {"reasoningEffort": "max"}} os.makedirs(os.path.dirname(p), exist_ok=True) json.dump(cfg, open(p, "w"), indent=2, ensure_ascii=False) print("model ->", p) EOF
opencode2 run "probe.png 안의 글자와 도형을 그대로 알려줘"

⚠ The OpenCode provider catalog must expose image input for this model. Update OpenCode if the image probe is rejected. ⚠ OpenCode 공급자 카탈로그가 이 모델의 이미지 입력을 노출해야 한다. 이미지 입력이 거부되면 OpenCode를 업데이트한다.

STEP 6

One-time setup — skip the approval spam한 번만 하는 설정 — 승인 요청 없이 바로 쓰기

OpenCode asks before shell commands by default. This block allows ordinary work while keeping destructive commands such as rm, hard reset, and force push behind approval. It merges into ~/.config/opencode/opencode.json. OpenCode는 셸 명령마다 기본적으로 승인을 묻는다. 아래 설정은 일반 작업은 허용하고 rm·hard reset·force push 같은 파괴적 명령만 승인 대상으로 남긴다. ~/.config/opencode/opencode.json에 병합한다.

python3 - <<'EOF' import json, os p = os.path.expanduser("~/.config/opencode/opencode.json") cfg = json.load(open(p)) if os.path.exists(p) else {} # 이미 있으면 보존하고 합친다 cfg["permissions"] = [ # ① 기본: 읽기·검색·셸 명령 전부 즉시 허용 {"action": "read", "resource": "*", "effect": "allow"}, {"action": "glob", "resource": "*", "effect": "allow"}, {"action": "grep", "resource": "*", "effect": "allow"}, {"action": "lsp", "resource": "*", "effect": "allow"}, {"action": "external_directory", "resource": "*", "effect": "allow"}, {"action": "shell", "resource": "*", "effect": "allow"}, # ② 파괴적인 명령만 승인을 요구한다 (뒤에 오는 규칙이 앞을 이긴다) {"action": "shell", "resource": "rm *", "effect": "ask"}, {"action": "shell", "resource": "rmdir *", "effect": "ask"}, {"action": "shell", "resource": "chmod *", "effect": "ask"}, {"action": "shell", "resource": "chown *", "effect": "ask"}, {"action": "shell", "resource": "chgrp *", "effect": "ask"}, {"action": "shell", "resource": "sudo *", "effect": "ask"}, {"action": "shell", "resource": "dd *", "effect": "ask"}, {"action": "shell", "resource": "mkfs *", "effect": "ask"}, {"action": "shell", "resource": "kill *", "effect": "ask"}, {"action": "shell", "resource": "pkill *", "effect": "ask"}, {"action": "shell", "resource": "killall *", "effect": "ask"}, {"action": "shell", "resource": "shutdown *", "effect": "ask"}, {"action": "shell", "resource": "reboot *", "effect": "ask"}, {"action": "shell", "resource": "git reset --hard *", "effect": "ask"}, {"action": "shell", "resource": "git clean *", "effect": "ask"}, {"action": "shell", "resource": "git checkout -- *", "effect": "ask"}, {"action": "shell", "resource": "git restore *", "effect": "ask"}, {"action": "shell", "resource": "git branch -D *", "effect": "ask"}, {"action": "shell", "resource": "git tag -d *", "effect": "ask"}, {"action": "shell", "resource": "git remote remove *", "effect": "ask"}, {"action": "shell", "resource": "git remote set-url *", "effect": "ask"}, {"action": "shell", "resource": "git push --force*", "effect": "ask"}, {"action": "shell", "resource": "git push -f*", "effect": "ask"}, {"action": "shell", "resource": "gh repo delete *", "effect": "ask"}, {"action": "shell", "resource": "docker system prune *", "effect": "ask"}, {"action": "shell", "resource": "docker volume rm *", "effect": "ask"}, {"action": "shell", "resource": "kubectl delete *", "effect": "ask"}, {"action": "shell", "resource": "terraform destroy *", "effect": "ask"}, {"action": "shell", "resource": "aws s3 rm *", "effect": "ask"} ] os.makedirs(os.path.dirname(p), exist_ok=True) with open(p, "w") as f: json.dump(cfg, f, indent=2, ensure_ascii=False) print("permissions ->", p) EOF

Verified on a real machine (2026-08-20, opencode2 0.0.0-beta-17728): after this config, ordinary commands run without interruption and the snippet round-trips existing JSON safely. If opencode2 is already running, opencode2 service restart applies it immediately. Want the prompts back? Delete the permissions key and restart. 실제 머신에서 검증했다(2026-08-20, opencode2 0.0.0-beta-17728). 이 설정 후 일반 명령은 끊김 없이 실행됐고, 스크립트는 이미 있는 JSON을 안전하게 보존·병합했다. 이미 opencode2가 돌고 있다면 opencode2 service restart 한 번으로 즉시 반영된다. 다시 물어보게 하고 싶으면 permissions 키를 지우고 재시작하면 된다.

STEP 7

Run it and talk실행하고 첫 대화

cd ~/my-project # 작업할 폴더로 이동 opencode2 # 실행

You are talking to the agent directly. Just write what you want, in Korean: 대화 상대는 에이전트 본인이다. 하고 싶은 일을 한국어로 그대로 쓰면 된다:

이 폴더의 코드를 읽고 프로젝트 구조를 요약해줘
  • /models — switch model mid-session. The default from STEP 5 is glm-5.3-flash; drop to glm-5-turbo for cheap bulk work. /models — 세션 도중 모델 변경. STEP 5에서 고정한 기본값은 glm-5.3-flash이고, 양이 많고 단순한 작업은 값싼 glm-5-turbo로 내리면 된다.
  • probe.png 안의 오류 메시지를 읽어줘 — GLM-5.3-Flash reads the image directly. probe.png 안의 오류 메시지를 읽어줘 — GLM-5.3-Flash가 이미지를 직접 읽는다.
  • Put an AGENTS.md in the project root and OpenCode loads it at startup as your standing project instructions. 프로젝트 루트에 AGENTS.md를 두면 시작할 때 자동으로 읽어 프로젝트 상시 지시사항으로 삼는다.
STEP 8

(Optional) Sync pi-setup(선택) pi-setup 동기화

promptbox defaults to pi. The one-shot setup prompt restores that environment from cskwork/pi-setup-public. promptbox의 기본 하네스는 pi다. 온보딩 한 방 설치 프롬프트가 cskwork/pi-setup-public 정본에서 환경을 복원한다.

Why this setup? 왜 이 구성인가?

OpenCode is provider-agnostic. GLM-5.3-Flash gives this setup a 1,000,000-token context and native image input while keeping one model and one config file. OpenCode는 공급자에 묶이지 않는다. GLM-5.3-Flash를 연결하면 모델 하나와 설정 파일 하나로 컨텍스트 100만 토큰과 네이티브 이미지 입력을 쓴다.

OpenCode 상세 →

Alternative — Prime Agent (persistent-kernel harness) 다른 선택지 — Prime Agent (IPython 커널 하네스) ▸

If you want a different single-agent harness, Prime Agent is another option: one agent whose only tool is a persistent IPython kernel, so Python variables and loaded data survive across turns. It reads the same ~/.agents/skills/ directory this site installs into, and it takes the same Z.ai key. It sits best on macOS — the official one-line installer targets macOS/Linux, and Windows needs a bash shell (Git Bash or WSL) before it will run at all. 단일 에이전트 하네스를 다른 것으로 써보고 싶다면, Prime Agent는 또 다른 선택지다. 도구가 영구 IPython 커널(살아 있는 파이썬 환경) 하나뿐인 단일 에이전트라, 변수와 읽어둔 데이터가 턴이 바뀌어도 남아 있다. 이 사이트가 설치하는 ~/.agents/skills/를 그대로 읽고, Z.ai 키도 같은 것을 쓴다. 특히 macOS와 궁합이 좋다 — 공식 한 줄 인스톨러가 macOS·Linux를 대상으로 하고, Windows는 bash 셸(Git Bash 또는 WSL)을 먼저 갖춰야 실행조차 된다.

curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh # 또는: npm install -g prime-agent (Node 22.8 이상) cd ~/my-project && prime-agent # 에이전트 안에서: /login → ZAI 선택 → 키 붙여넣기

Needs Node.js 22.8+. Key storage is ~/.prime/agent/auth.json; the environment-variable route is export ZAI_API_KEY=…. GLM-5.3-Flash accepts pasted screenshots through Ctrl+V. Node.js 22.8 이상이 필요하다. 키는 ~/.prime/agent/auth.json에 저장되고, 환경변수는 export ZAI_API_KEY=…로 넣는다. GLM-5.3-Flash는 Ctrl+V로 붙인 스크린샷을 읽는다.