OpenCode 실전 입문: 터미널·편집기·팀 개발에서 AI 에이전트 활용하기
OpenCode는 터미널과 편집기에서 코드를 읽고 수정하며 검증 작업을 이어 가는 오픈 소스 AI 코딩 에이전트입니다. 모델을 연결하는 법부터 프로젝트 규칙과 권한 설정, 실제 개발 환경에 맞는 작업 흐름까지 알아두면 작은 수정에서 팀 단위 협업으로 활용 범위를 넓힐 수 있습니다.
OpenCode는 무엇인가
이 글에서 말하는 Open Code의 공식 표기는 OpenCode입니다. 공식 웹사이트와 소스 저장소를 기준으로 설명합니다. 코드를 작성하는 언어 모델 자체가 아니라, 선택한 모델이 저장소를 탐색하고 파일과 도구를 다루도록 연결하는 프로그램입니다.
개발자는 요청을 주고, 에이전트는 필요한 파일을 읽고 변경을 만들거나 명령을 실행하며 결과를 돌려줍니다. 따라서 답변이 그럴듯한지만 보는 대신 변경된 코드와 테스트 결과를 검토해야 합니다. 오픈 소스라는 말도 모델 호출까지 모두 무료이거나 모든 코드가 로컬에서만 처리된다는 뜻은 아닙니다.
이 글의 설치와 설정은 2026년 10월 22일 확인한 OpenCode 2 문서를 기준으로 합니다. V1 이전 안내에 따르면 두 버전은 같은 opencode 명령을 사용합니다. 기존 설치가 있다면 설정을 복사해 보관하고 설치 방식부터 확인하세요. V1 플러그인과 서버 API 연동은 별도 이전이 필요하며, V2는 LSP 진단을 실행하지 않으므로 프로젝트의 타입 검사·린트·컴파일 명령으로 확인해야 합니다.
개발자가 선택할 수 있는 환경
| 환경 | 활용 방식 | 잘 맞는 작업 |
|---|---|---|
| 로컬 터미널 | 프로젝트 디렉터리에서 TUI 실행 | 저장소 파악, 오류 수정, 리팩터링 |
| 편집기 통합 터미널 | 코드를 보며 같은 폴더에서 CLI 실행 | 컴포넌트 수정과 diff 검토 |
| ACP 지원 편집기 | 편집기를 클라이언트로 연결 | 편집기 안에서 에이전트와 대화 |
| 데스크톱·웹 | 공식 앱 또는 로컬 서비스의 웹 화면 사용 | 시각적인 작업 관리 선호 시 |
| 원격 개발 환경·CI | 실행 호스트에 저장소·도구·인증 준비 | 반복 검토와 결과 보고 |
OpenCode 2 시작 문서는 터미널·데스크톱·웹 접근을 안내합니다. 웹 연결에는 opencode pair를 사용합니다. UI가 브라우저에 보인다고 해서 코드 실행까지 자동으로 클라우드로 옮겨지는 것은 아닙니다. CLI 구조상 기본 로컬 클라이언트는 사용자 계정의 공용 백그라운드 서비스에 연결합니다.
예를 들어 VS Code 사용자라면 통합 터미널을 열고 해당 저장소에서 시작하면 됩니다. 확장 기능의 자동 설치나 단축키는 버전에 따라 다르므로, 먼저 CLI가 같은 프로젝트에서 동작하는지 확인하는 편이 좋습니다. SSH 환경에서는 원격 호스트의 파일, 도구와 자격 증명이 사용된다는 점도 구별합니다.
설치하고 모델을 연결하는 첫 순서
macOS·Linux에서 Node.js와 npm이 준비된 경우, V2 공식 패키지는 다음과 같습니다. /path/to/project는 실제 저장소 경로로 바꿉니다.
npm install -g @opencode/cli
cd /path/to/project
opencode이 명령은 독자가 실행할 예제이며, 이 글 작성 과정에서 제품 설치나 모델 호출을 수행한 것은 아닙니다. Windows에서는 V2 문서가 패키지 관리자 설치를 지원하지 않는다고 명시하므로, 공식 페이지의 독립 실행형 CLI 바이너리나 데스크톱 다운로드를 선택합니다.
TUI 안에서는 다음 명령을 하나씩 실행합니다.
/connect
/models
/agents연결 안내에 따라 /connect에서 제공자와 인증 방식을 고르고, /models에서 실제 사용 가능한 모델을 선택합니다. API 키는 연결 화면에서 입력하고 프로젝트 파일이나 대화 예제에 넣지 않습니다. /agents에서는 먼저 Plan을 고릅니다.
모델 문서에서 모델 선택과 추론 강도 variant는 별개입니다. 모델마다 지원 옵션이 달라 임의로 max 같은 이름을 붙이면 안 됩니다. 처음에는 기본값으로 작은 작업을 수행하고, 복잡한 설계나 반복 실패를 분석할 때 지원되는 높은 추론 옵션을 검토합니다. 속도보다 최종 수정 품질과 재작업 비용을 비교하세요.
출처: OpenCode 2 TUI 공식 문서, 2026년 10월 22일 공개 페이지 캡처. 실제 작업 세션이 아닌 사용법 안내입니다. 이미지 크게 보기.
Plan과 Build를 나누고 권한을 정한다
에이전트 문서에서 Plan은 일반 프로젝트 파일을 수정하지 않고 탐색과 계획을 진행합니다. 계획 파일을 만들 수 있으며 셸 실행은 권한 설정의 영향을 받습니다. 완전한 읽기 전용 샌드박스로 생각하면 안 됩니다. Build는 구현 작업용 기본 에이전트입니다.
V2는 프로젝트 밖 접근도 기본 허용이므로 처음에는 opencode.jsonc에 다음과 같이 명시할 수 있습니다. 기존 파일이 있다면 전체를 덮어쓰지 말고 규칙을 병합합니다.
{
"$schema": "https://opencode.ai/config.json",
"permissions": [
{ "action": "edit", "resource": "*", "effect": "ask" },
{ "action": "shell", "resource": "*", "effect": "ask" },
{ "action": "external_directory", "resource": "*", "effect": "ask" },
{ "action": "shell", "resource": "git status *", "effect": "allow" },
{ "action": "shell", "resource": "git diff *", "effect": "allow" },
{ "action": "shell", "resource": "git push *", "effect": "deny" }
]
}권한 문서에 따르면 마지막으로 일치한 규칙이 적용됩니다. 이 예제는 편집과 셸 실행을 확인하고, 일반적인 Git 조회는 허용하며 git push는 막습니다. 셸은 호스트 사용자의 권한으로 실행되므로 이것이 OS 격리를 제공하거나 모든 우회 경로를 차단하는 설정은 아닙니다. 승인 전에 실제 명령과 대상 경로를 확인합니다.
실습: 검색 결과가 없을 때의 화면 고치기
아래는 프런트엔드 저장소에 적용할 수 있는 예시입니다. 먼저 기존 변경을 확인하고 별도 브랜치를 만듭니다. 같은 이름이 이미 있다면 다른 이름을 사용합니다.
git status --short
git switch -c feat/search-empty-statePlan에서 목표와 탐색 범위를 지정합니다. 실제 검색 화면의 파일을 @로 찾아 첨부하면 모호함을 줄일 수 있습니다.
검색 결과가 0개일 때 로딩 표시가 계속 남는 문제를 조사해 줘. 검색 화면, 요청 처리, 상태 전환, 관련 테스트를 찾아 현재 흐름을 설명하고 원인 후보와 최소 수정 계획을 제시해. 아직 파일을 수정하거나 명령을 실행하지 마.
계획을 읽고 원인이 확인되면 /agents에서 Build로 전환해 다음처럼 요청합니다.
확인한 원인에 한해 수정해. 로딩·결과 있음·결과 없음·요청 실패를 서로 구분하고, 기존 컴포넌트와 문구 규칙을 따라. 이 버그를 재현하는 회귀 테스트와 프로젝트에 이미 정의된 관련 검증 명령을 실행해. 변경 파일, 실행한 명령, 통과 여부, 남은 불확실성을 보고해. 커밋과 푸시는 하지 마.
완료 판단은 개발자가 합니다. diff에서 무관한 파일 변경이 없는지 확인하고, 0건 응답·오류 응답·연속 검색을 실제 화면에서도 점검합니다. 테스트가 실패하면 에러 전문과 기대 동작을 전달해 원인을 좁힙니다. 반복해서 고치지 못하면 변경 범위를 더 줄이거나 상태 설계를 다시 검토합니다.
TUI 안내의 /undo와 /redo는 작업을 되돌리는 데 유용합니다. 다만 Git 기록과 백업을 대체하는 수단으로 삼지 말고, 수용한 변경만 작은 단위로 커밋하는 습관을 유지합니다.
편집기와 팀 환경에서는 무엇이 달라지나
ACP는 편집기와 에이전트를 연결하는 프로토콜입니다. Zed를 쓴다면 OpenCode의 ACP 안내처럼 먼저 터미널에서 opencode auth login으로 인증하고, ~/.config/zed/settings.json의 기존 설정에 다음 항목을 병합합니다.
{
"agent_servers": {
"OpenCode": {
"command": "opencode",
"args": ["acp"]
}
}
}그다음 Zed의 에이전트 기능에서 OpenCode를 선택해 프로젝트를 엽니다. 실행 파일을 찾지 못하면 command에 실제 바이너리의 절대 경로를 지정합니다. opencode acp는 프로토콜 메시지를 기다리는 명령이므로 터미널에서 직접 실행해 화면이 조용하다고 실패로 판단하지 않습니다.
출처: OpenCode 2 ACP 공식 문서, 2026년 10월 22일 공개 페이지 캡처. 이미지 크게 보기.
팀에서는 사람마다 긴 초기 프롬프트를 복사하기보다 프로젝트 지침인 AGENTS.md에 실제 빌드·테스트 명령, 수정하지 않을 생성 파일, 리뷰 기준을 적어 버전 관리합니다. 여러 작업을 동시에 맡기면 별도 브랜치와 worktree로 파일 충돌도 줄입니다. 이것은 작업 폴더 분리이며 모델 비용이나 권한까지 자동으로 분리하지는 않습니다.
반복 절차는 Skills의 .opencode/skills/<skill-id>/SKILL.md에, 외부 도구 연결은 MCP 서버에 맡길 수 있습니다. Skill은 방법을 설명하고 MCP는 도구·자료 접근을 연결합니다. 필요한 것부터 하나씩 추가하고 호출 결과와 비용을 확인하세요.
자동 실행과 로컬 모델은 어디에 적합한가
CLI 명령 안내의 opencode run은 대화형 화면 없이 요청을 실행합니다. 모델 연결을 마친 저장소에서 검토 연습은 다음처럼 시작할 수 있습니다.
opencode run --standalone --agent plan \
"Review this repository. Explain the test strategy and list gaps. Do not edit files or run shell commands."이 요청 문장만으로 읽기 전용이 강제되지는 않습니다. 무인 CI에서는 별도의 검토 에이전트에 편집과 불필요한 셸 권한을 Deny로 설정하고, 승인 대기를 처리할 방법도 정해야 합니다. 실행 시간 제한, 실패 상태, 결과 보관 위치를 함께 정합니다. CI 비밀 변수로 제공자 키를 주입할 때는 --standalone의 전용 서버가 그 환경을 받도록 구성합니다. 외부 PR의 신뢰되지 않은 코드에 비밀 키를 제공하지 않으며, 모델의 리뷰는 기존 테스트를 대체하지 않습니다.
로컬 추론을 원하면 Ollama 같은 실행 환경도 선택할 수 있습니다. 제공자 문서는 로컬 Ollama 서버의 모델 자동 탐색을 설명합니다. 서버를 실행하고 모델을 준비한 뒤 /models에서 확인합니다. 사용할 모델의 도구 호출 지원, 메모리 요구량과 응답 시간을 작은 수정으로 먼저 평가하세요. 로컬 모델을 골라도 웹 검색·MCP 등 별도 기능이 네트워크를 사용할 수 있으므로 전체 작업이 오프라인이라고 단정하지 않습니다.
실제 사례에서 가져올 것은 검증 순서다
Cloudflare의 2026년 2월 개발 회고는 OpenCode에서 모델과 설계를 논의하고, 작업을 나누어 구현과 테스트를 반복한 과정을 소개합니다. 저자는 잘못된 구현을 사람이 바로잡았다고도 설명합니다. 특정 팀의 사례이지 누구나 같은 속도로 만들 수 있다는 보장은 아닙니다.
자기 프로젝트에 옮길 때는 규모보다 순서를 가져오세요. 재현할 수 있는 문제 하나를 고르고, 현재 동작과 기대 동작을 적고, 계획을 검토한 뒤 수정과 검증을 연결합니다. 새 기능이라면 성공 조건을 먼저 정합니다. 리뷰할 수 없는 큰 diff가 나왔다면 요청을 더 작은 작업으로 나누는 편이 낫습니다.
비용과 Console을 구분해 도입하기
OpenCode Console은 모델 접근, 팀 워크스페이스, 사용량·예산 관리를 제공하는 선택 서비스입니다. 로컬 CLI에서 제공자에 직접 연결하는 방식과 Console 게이트웨이를 거치는 방식을 구분하세요. 앱의 오픈 소스 라이선스와 API 사용료·구독료는 서로 다른 항목입니다.
도입 시점의 공지도 확인할 필요가 있습니다. OpenCode의 2026년 10월 17일 공식 공지는 외부 제공자를 연결한 Console 사용자 일부에 영향을 준 침해를 알렸습니다. 공지 당시 영향 비율은 Console 사용자의 1.4%로 제시됐습니다. 해당 연결을 사용했다면 받은 안내와 최신 후속 공지를 확인하고 관련 키와 사용 내역을 점검해야 합니다. 이를 모든 로컬 설치의 동일한 사고로 확대 해석하거나, 현재 복구 완료로 단정하지 않습니다.
첫 도입은 테스트가 있는 작은 저장소에서 시작하는 것이 좋습니다. 한 개의 수정이 검토 가능한 diff와 재현 가능한 검증 결과로 돌아오는지 평가하세요. 그 다음에 모델을 바꾸고 팀 규칙, 편집기 연동, 자동 실행을 차례로 추가하면 각 설정이 무엇을 개선했는지 판단하기 쉽습니다.
공식 문서를 확인해 구성한 안내와 실습 예제입니다. 설치, 유료 모델 호출, 원격 환경 및 CI 실행을 직접 검증한 사용기는 아닙니다.
OpenCode is an open source AI coding agent that reads and changes code and carries out verification in familiar terminals and editors. Understanding model connections, project rules, permissions, and practical workflows helps you move from small changes to team development.
What OpenCode is
The official spelling of “Open Code” in this article is OpenCode. This guide uses its official website and source repository. It is a program that connects a selected model to repository exploration, files, and tools, rather than a language model itself.
You provide a request; the agent reads relevant files, makes changes or runs commands, and reports results. Review the changed code and test outcomes, not just whether its answer sounds convincing. Open source also does not mean every model call is free or that all code is processed locally.
Installation and configuration here follow OpenCode 2 documentation checked on October 22, 2026. The V1 migration guide explains that both versions use the opencode command. If you already have an installation, preserve a copy of its configuration and check how it was installed. V1 plugins and server API integrations require migration. V2 does not run LSP diagnostics, so use your project's type checking, linting, and compiler commands.
Environments developers can use
| Environment | Approach | Suitable work |
|---|---|---|
| Local terminal | Start the TUI from a project directory | Understanding code, fixing bugs, refactoring |
| Editor's integrated terminal | Run the CLI in the same folder while viewing code | Component changes and diff review |
| ACP-compatible editor | Connect the editor as a client | Agent conversations inside the editor |
| Desktop or web | Use the official app or the local service's web interface | Visual task management |
| Remote development or CI | Prepare the repository, tools, and credentials on the execution host | Repeated reviews and reports |
The OpenCode 2 introduction covers terminal, desktop, and web access. Use opencode pair to connect the web interface. A browser interface does not automatically move code execution to the cloud. In the CLI architecture, local clients normally connect to a shared background service for your user account.
For example, a VS Code user can open its integrated terminal and start in the repository. Automatic extension installation and shortcuts can vary by version, so first verify that the CLI works in the same project. Over SSH, distinguish the remote host's files, tools, and credentials from those on your laptop.
Install and connect a model
On macOS or Linux with Node.js and npm available, the official V2 package is installed as follows. Replace /path/to/project with your repository's path.
npm install -g @opencode/cli
cd /path/to/project
opencode
These are commands for readers to run; we did not install the product or invoke a model while writing this article. V2 documentation says Windows package managers are unsupported, so Windows users should choose the standalone CLI binary or desktop download on the official page.
Inside the TUI, run these commands individually.
/connect
/models
/agents
Follow the connection guide to select a provider and authentication method through /connect, then choose an available model through /models. Enter API keys in the connection interface, not project files or example prompts. Start with Plan in /agents.
The model documentation distinguishes model selection from reasoning variants. Supported options differ, so do not invent names such as max. Begin with defaults on a small task, then consider a supported higher reasoning option for difficult design or repeated failures. Compare final quality and rework cost alongside speed.
Source: public OpenCode 2 TUI documentation, captured October 22, 2026. This shows instructions, not an actual work session. View full size.
Separate Plan from Build and configure permissions
The agent documentation describes Plan as exploration and planning without editing normal project files. It can write plan files, and shell execution remains permission-controlled. It is not a fully read-only sandbox. Build is the default implementation agent.
V2 allows access outside the project by default. You can make an initial configuration explicit in opencode.jsonc as below. Merge these rules into an existing file rather than replacing it wholesale.
{
"$schema": "https://opencode.ai/config.json",
"permissions": [
{ "action": "edit", "resource": "*", "effect": "ask" },
{ "action": "shell", "resource": "*", "effect": "ask" },
{ "action": "external_directory", "resource": "*", "effect": "ask" },
{ "action": "shell", "resource": "git status *", "effect": "allow" },
{ "action": "shell", "resource": "git diff *", "effect": "allow" },
{ "action": "shell", "resource": "git push *", "effect": "deny" }
]
}
The permission documentation says the last matching rule wins. This example asks before edits and shell commands, allows routine Git inspection, and denies git push. The shell runs with the host user's authority; these rules do not provide OS isolation or block every alternate route. Review the actual command and target paths before approving.
Exercise: Fix a search results screen with no matches
This example can be adapted to a frontend repository. Inspect existing changes and create a separate branch. Choose another name if this one already exists.
git status --short
git switch -c feat/search-empty-state
In Plan, specify the goal and investigation scope. Attach the actual search screen file using @ to reduce ambiguity.
Investigate why the loading indicator remains visible when search returns zero results. Locate the search screen, request handling, state transitions, and relevant tests. Explain the current flow, possible causes, and a minimal change plan. Do not edit files or run commands yet.
Read the plan. Once the cause is established, switch to Build through /agents and continue:
Fix only the confirmed cause. Distinguish loading, results available, no results, and request failure, following existing component and copy conventions. Add and run a regression test reproducing this bug, and run the relevant verification commands already defined in the project. Report changed files, commands run, pass or fail status, and remaining uncertainty. Do not commit or push.
The developer decides whether it is complete. Inspect the diff for unrelated changes and check zero-result responses, errors, and consecutive searches in the actual interface. If tests fail, provide the full error and expected behavior to narrow the cause. Repeated unsuccessful attempts call for a smaller change or a review of the state design.
The TUI guide documents /undo and /redo. They help reverse work but should not replace Git history or backups. Commit accepted changes in small units.
What changes in editor and team workflows
ACP connects editors and agents. For Zed, follow OpenCode's ACP guide: authenticate in a terminal with opencode auth login, then merge this entry into the existing ~/.config/zed/settings.json.
{
"agent_servers": {
"OpenCode": {
"command": "opencode",
"args": ["acp"]
}
}
}
Select OpenCode in Zed's agent interface and open the project. If the executable cannot be found, set command to its absolute path. opencode acp waits for protocol messages, so a quiet terminal after starting it directly does not imply failure.
Source: public OpenCode 2 ACP documentation, captured October 22, 2026. View full size.
For a team, record real build and test commands, generated files to leave alone, and review requirements in version-controlled AGENTS.md project instructions. This avoids everyone copying a lengthy starting prompt. Separate branches and worktrees reduce file conflicts between concurrent tasks, but do not automatically isolate model costs or permissions.
Put repeatable procedures in .opencode/skills/<skill-id>/SKILL.md using Skills, and connect external tools through MCP servers. Skills describe methods; MCP connects tool and resource access. Add what you need one at a time and inspect results and cost.
Where automation and local models fit
The CLI command guide documents opencode run for requests without an interactive interface. In a repository with model access configured, start a review exercise like this:
opencode run --standalone --agent plan \
"Review this repository. Explain the test strategy and list gaps. Do not edit files or run shell commands."
The prompt alone does not enforce read-only behavior. In unattended CI, give a separate review agent Deny rules for edits and unnecessary shell access, and define how approval requests will be handled. Set a timeout, failure handling, and an output destination. When injecting a provider key through CI secrets, use --standalone so the private server receives that environment. Do not expose secrets to untrusted code from external PRs. Model reviews supplement existing tests.
For local inference, consider a runtime such as Ollama. The provider documentation describes discovery of models on a local Ollama server. Start the server, prepare a model, and check /models. Evaluate tool calling, memory needs, and response time with a small change first. Web search, MCP, and other features may still use the network even with a local model.
Take the verification sequence from real usage
Cloudflare's February 2026 development retrospective describes planning in OpenCode and iterating through implementation and tests, with human corrections for wrong implementations. This is one team's experience, not a universal speed guarantee.
Bring the sequence to your own project: pick a reproducible problem, describe current and expected behavior, review a plan, and connect implementation to verification. For a new feature, define success first. If the diff is too large to review, split the request into smaller tasks.
Distinguish costs and Console before adoption
OpenCode Console is an optional service for model access, team workspaces, usage tracking, and budgets. Distinguish connecting directly to a provider from a local CLI and routing through the Console gateway. The application's open source license and model API or subscription charges are separate matters.
Check current notices too. OpenCode's official October 17, 2026 announcement reported a breach affecting some Console users with external providers linked. It stated that 1.4% of Console users were affected. If you used that connection, review the notice you received and subsequent updates, and check relevant keys and usage. Do not generalize this to an identical incident in every local installation or assume remediation is complete.
Start in a small repository with tests. Evaluate whether one change produces a reviewable diff and reproducible verification. Then add model choices, team rules, editor integration, and automation in stages so you can identify what each setting improves.
This guide and its exercises were prepared from official documentation. It is not a hands-on report verifying installation, paid model calls, remote environments, or CI execution.
OpenCode 是一款开源 AI 编程智能体，能够在熟悉的终端和编辑器中读取、修改代码并推进验证工作。掌握模型连接、项目规范、权限设置及实际工作流程，就能从小型修改逐步扩展到团队开发。
OpenCode 是什么
本文所说的 Open Code，官方写法为 OpenCode。介绍以官方网站和源码仓库为准。它并非语言模型本身，而是把所选模型与仓库探索、文件和工具连接起来的程序。
开发者提出请求，智能体读取相关文件、生成修改或执行命令，再返回结果。因此，应该审查改动后的代码与测试结果，而不能只看回答是否可信。开源也不意味着所有模型调用免费，或所有代码都只在本地处理。
本文安装和配置以 2026 年 10 月 22 日核对的 OpenCode 2 文档为准。V1 迁移指南说明，两代版本都使用 opencode 命令。已有安装时，先备份配置并确认安装方式。V1 插件和服务器 API 集成需要另行迁移；V2 不执行 LSP 诊断，应使用项目的类型检查、代码检查和编译命令。
开发者可以选择的环境
| 环境 | 使用方式 | 适合的任务 |
|---|---|---|
| 本地终端 | 在项目目录启动 TUI | 理解仓库、修复错误、重构 |
| 编辑器集成终端 | 查看代码时在同一目录运行 CLI | 组件修改与差异审查 |
| 支持 ACP 的编辑器 | 将编辑器连接为客户端 | 在编辑器内与智能体对话 |
| 桌面或网页 | 使用官方应用或本地服务的网页界面 | 偏好可视化任务管理 |
| 远程开发或 CI | 在执行主机准备仓库、工具与凭据 | 重复审查与报告 |
OpenCode 2 入门文档介绍终端、桌面和网页入口。网页连接使用 opencode pair。界面显示在浏览器中，并不意味着代码执行自动转到云端。CLI 架构说明，本地客户端默认连接当前用户账号的共享后台服务。
例如，VS Code 用户可以打开集成终端，在对应仓库启动。扩展自动安装和快捷键可能随版本变化，因此应先确认 CLI 在相同项目内运行。SSH 环境中则要区分远程主机上的文件、工具与凭据和本机资源。
安装并连接模型的第一步
在已准备 Node.js 和 npm 的 macOS、Linux 环境中，V2 官方包可按以下方式安装。将 /path/to/project 替换为实际仓库路径。
npm install -g @opencode/cli
cd /path/to/project
opencode
这是供读者运行的示例；撰写本文时没有安装该产品或调用模型。V2 文档明确表示不支持 Windows 包管理器安装，因此 Windows 用户应选择官方页面的独立 CLI 二进制文件或桌面版下载。
在 TUI 中逐个执行以下命令。
/connect
/models
/agents
按照连接指南，通过 /connect 选择供应商和认证方式，再在 /models 中选择实际可用的模型。API 密钥应输入连接界面，不要放进项目文件或示例提示词。在 /agents 中先选 Plan。
模型文档区分模型选择和推理强度 variant。支持选项因模型而异，不要自行添加 max 之类的名称。先以默认设置完成小任务，遇到复杂设计或反复失败时，再考虑支持的高推理选项。除了速度，还要比较最终质量和返工成本。
来源：OpenCode 2 TUI 官方文档，2026 年 10 月 22 日截取公开页面。这是使用说明，并非实际工作会话。查看大图。
区分 Plan、Build 并设置权限
智能体文档说明，Plan 用于探索和规划，不编辑普通项目文件。它可以写入计划文件，Shell 执行仍受权限控制，因此不能视作完全只读的沙箱。Build 是默认的实现智能体。
V2 默认允许项目外访问，初次使用可以在 opencode.jsonc 中明确以下规则。如果文件已存在，应合并规则而非整体覆盖。
{
"$schema": "https://opencode.ai/config.json",
"permissions": [
{ "action": "edit", "resource": "*", "effect": "ask" },
{ "action": "shell", "resource": "*", "effect": "ask" },
{ "action": "external_directory", "resource": "*", "effect": "ask" },
{ "action": "shell", "resource": "git status *", "effect": "allow" },
{ "action": "shell", "resource": "git diff *", "effect": "allow" },
{ "action": "shell", "resource": "git push *", "effect": "deny" }
]
}
权限文档规定最后匹配的规则生效。此示例要求编辑和 Shell 命令先确认，允许常见 Git 查询，并拒绝 git push。Shell 以主机用户权限运行，这些规则不提供操作系统隔离，也不能阻断所有替代路径。批准前应检查实际命令与目标路径。
练习：修复没有搜索结果时的界面
以下示例可用于前端仓库。先检查现有改动并创建独立分支；如同名分支已存在，应使用其他名称。
git status --short
git switch -c feat/search-empty-state
在 Plan 中指定目标与调查范围。通过 @ 找到并附加实际搜索页面文件，可以减少歧义。
调查搜索结果为零时加载指示仍然显示的问题。找到搜索页面、请求处理、状态转换及相关测试，解释当前流程、可能原因和最小修改计划。暂时不要编辑文件或执行命令。
读完计划、确认原因后，通过 /agents 切换到 Build，再提出请求：
只修复已确认的原因。区分加载中、有结果、无结果和请求失败，遵循现有组件与文案规范。添加并运行能重现此错误的回归测试，以及项目已经定义的相关验证命令。报告修改文件、执行命令、通过与否和剩余不确定性。不要提交或推送。
是否完成由开发者判断。检查 diff 是否包含无关修改，并在真实界面验证零结果、错误响应和连续搜索。测试失败时，提供完整错误和期望行为以缩小原因范围。反复无法修复时，应进一步缩小修改范围或重新检查状态设计。
TUI 指南中的 /undo 和 /redo 有助于撤销工作，但不能替代 Git 历史或备份。对接受的修改保持小批次提交。
编辑器与团队工作流有什么不同
ACP是连接编辑器和智能体的协议。使用 Zed 时，可按 OpenCode ACP 指南先在终端运行 opencode auth login 完成认证，再把以下内容合并到已有的 ~/.config/zed/settings.json。
{
"agent_servers": {
"OpenCode": {
"command": "opencode",
"args": ["acp"]
}
}
}
随后在 Zed 的智能体界面选择 OpenCode 并打开项目。找不到可执行文件时，将 command 改为实际二进制文件的绝对路径。opencode acp 会等待协议消息，因此直接在终端启动后没有输出，并不代表失败。
来源：OpenCode 2 ACP 官方文档，2026 年 10 月 22 日截取公开页面。查看大图。
团队应把实际构建与测试命令、不应编辑的生成文件、审查标准写入受版本管理的 AGENTS.md 项目指令，避免每个人复制冗长的初始提示词。并行任务使用独立分支和 worktree 可减少文件冲突，但不会自动隔离模型费用或权限。
重复流程可通过 Skills放入 .opencode/skills/<skill-id>/SKILL.md，外部工具通过 MCP 服务器连接。Skill 说明做事方法，MCP 提供工具与资料入口。按需逐一添加，并检查调用结果和费用。
自动执行与本地模型适合什么场景
CLI 命令指南中的 opencode run 可在没有交互界面时执行请求。完成模型连接后，可在仓库中尝试：
opencode run --standalone --agent plan \
"Review this repository. Explain the test strategy and list gaps. Do not edit files or run shell commands."
仅靠提示词不会强制只读。在无人值守的 CI 中，应为独立审查智能体设置禁止编辑及不必要 Shell 操作的 Deny 规则，并确定如何处理批准请求。同时设置超时、失败处理和输出存放位置。通过 CI 密钥变量注入供应商密钥时，使用 --standalone 让专用服务器接收该环境。不要把密钥交给外部 PR 的不可信代码；模型审查不能替代既有测试。
希望使用本地推理时，可以选择 Ollama 等运行环境。供应商文档说明了本地 Ollama 模型的自动发现。启动服务器并准备模型后，在 /models 中确认。先用小型修改评估工具调用支持、内存需求和响应时间。即使选择本地模型，网页搜索、MCP 等功能仍可能联网，因此不能认定整个工作流离线。
从真实案例借鉴验证顺序
Cloudflare 2026 年 2 月的开发回顾介绍了在 OpenCode 中讨论设计、拆分任务并反复实现和测试的过程，错误实现仍由人纠正。这是特定团队的经验，不代表所有人都能达到相同速度。
把顺序应用到自己的项目：选择可重现的问题，写清当前行为与期望行为，审查计划后连接修改与验证。新功能则先定义成功条件。如果 diff 大到无法审查，应把请求拆成更小的任务。
引入前区分费用与 Console
OpenCode Console是可选服务，提供模型访问、团队工作区、用量与预算管理。应区分本地 CLI 直连供应商和通过 Console 网关的方式。应用的开源许可与模型 API 或订阅费用是不同事项。
也要核对当前公告。OpenCode 2026 年 10 月 17 日官方公告通报了影响部分连接外部供应商的 Console 用户的入侵，公布的比例为 Console 用户的 1.4%。使用过这种连接时，应阅读收到的通知与后续公告，检查相关密钥和用量。不要把它扩大解释为每个本地安装都发生相同事故，也不要认定恢复已完成。
首次引入适合从带测试的小仓库开始。评估一次修改是否产生可审查的 diff 和可重现的验证结果，再逐步添加模型选择、团队规则、编辑器集成和自动执行，才能判断每项设置改善了什么。
本文依据官方文档编写指南与练习，并非亲自验证安装、付费模型调用、远程环境或 CI 执行的使用报告。
OpenCodeは、使い慣れたターミナルやエディターでコードを読み、修正し、検証を進めるオープンソースのAIコーディングエージェントです。モデル接続、プロジェクト規則、権限、実用的な手順を理解すると、小さな修正からチーム開発へ利用を広げられます。
OpenCodeとは何か
この記事でいうOpen Codeの正式表記は OpenCode です。公式サイトとソースリポジトリを基に説明します。言語モデルそのものではなく、選んだモデルをリポジトリ探索、ファイル、ツールにつなぐプログラムです。
開発者が依頼すると、エージェントは関連ファイルを読み、変更やコマンド実行を行い、結果を返します。回答の説得力だけでなく、変更されたコードとテスト結果を確認します。オープンソースでもモデル呼び出しがすべて無料とは限らず、すべてのコードがローカルだけで処理されるわけでもありません。
インストールと設定は 2026年10月22日に確認したOpenCode 2の文書 に基づきます。V1移行ガイドによると両バージョンは同じ opencode コマンドを使います。既存環境がある場合は設定を保存し、インストール方法を確認してください。V1プラグインとサーバーAPI連携は移行が必要です。V2はLSP診断を実行しないため、プロジェクトの型検査、リント、コンパイルで検証します。
開発者が選べる環境
| 環境 | 使い方 | 適した作業 |
|---|---|---|
| ローカルターミナル | プロジェクト内でTUIを起動 | コード理解、バグ修正、リファクタリング |
| エディター内ターミナル | コードを見ながら同じフォルダーでCLIを起動 | コンポーネント修正と差分確認 |
| ACP対応エディター | エディターをクライアントとして接続 | エディター内でのエージェントとの対話 |
| デスクトップ・Web | 公式アプリやローカルサービスのWeb画面を使用 | 視覚的な作業管理 |
| リモート開発・CI | 実行ホストにリポジトリ、ツール、認証を準備 | 定期的なレビューと報告 |
OpenCode 2開始文書は、ターミナル、デスクトップ、Webからの利用を案内しています。Web接続には opencode pair を使います。ブラウザーにUIが表示されても、コードの実行が自動でクラウドに移るわけではありません。CLIの構造では、通常のローカルクライアントはユーザーアカウントの共有バックグラウンドサービスにつながります。
例えば VS Code なら統合ターミナルを開き、対象リポジトリで開始できます。拡張の自動インストールやショートカットはバージョンによって異なるため、まずCLIが同じプロジェクトで動くことを確認します。SSHではリモートホストのファイル、ツール、認証情報と手元の環境を区別します。
インストールしてモデルを接続する
Node.jsとnpmがあるmacOS・Linuxでは、V2公式パッケージを次のように導入します。/path/to/project は実際のリポジトリのパスに置き換えます。
npm install -g @opencode/cli
cd /path/to/project
opencode
これは読者が実行するための例であり、執筆時に製品のインストールやモデル呼び出しを行ったものではありません。V2文書はWindowsのパッケージマネージャーを非対応としているため、Windowsでは公式ページの単体CLIバイナリかデスクトップ版を選びます。
TUI内では次を一つずつ実行します。
/connect
/models
/agents
接続ガイドに従い、/connect で提供者と認証方法を選び、/models で利用可能なモデルを選択します。APIキーは接続画面に入力し、プロジェクトファイルや依頼例には含めません。/agents ではまずPlanを選びます。
モデル文書では、モデル選択と推論強度のvariantは別です。対応する選択肢はモデルごとに異なるため、max などの名前を勝手に指定しません。最初は既定値で小さな作業を行い、複雑な設計や繰り返す失敗の分析時に対応する高い推論設定を検討します。速度とともに最終品質や手戻りの費用を比較してください。
出典：OpenCode 2 TUI公式文書。2026年10月22日に公開ページを撮影。実際の作業セッションではなく操作案内です。拡大表示。
PlanとBuildを分け、権限を決める
エージェント文書では、Planは通常のプロジェクトファイルを編集せずに探索と計画を行います。計画ファイルを作成でき、シェル実行は権限に従います。完全な読み取り専用サンドボックスとは考えないでください。Buildは実装用の既定エージェントです。
V2はプロジェクト外へのアクセスも既定で許可します。初回は opencode.jsonc に次のような規則を設定できます。既存ファイルは丸ごと置換せず、規則をマージします。
{
"$schema": "https://opencode.ai/config.json",
"permissions": [
{ "action": "edit", "resource": "*", "effect": "ask" },
{ "action": "shell", "resource": "*", "effect": "ask" },
{ "action": "external_directory", "resource": "*", "effect": "ask" },
{ "action": "shell", "resource": "git status *", "effect": "allow" },
{ "action": "shell", "resource": "git diff *", "effect": "allow" },
{ "action": "shell", "resource": "git push *", "effect": "deny" }
]
}
権限文書によると、最後に一致した規則が適用されます。この例は編集とシェル実行を確認し、通常のGit参照を許可して git push を拒否します。シェルはホストユーザーの権限で動くため、OSの分離やあらゆる別経路の遮断を提供する設定ではありません。承認前に実際のコマンドと対象パスを確認します。
演習：検索結果がない画面を修正する
フロントエンドのリポジトリに適用できる例です。既存変更を確認して別ブランチを作成します。同名が存在する場合は別名にします。
git status --short
git switch -c feat/search-empty-state
Planで目的と調査範囲を指定します。実際の検索画面ファイルを @ で探して添付すると曖昧さを減らせます。
検索結果が0件でも読み込み表示が残る問題を調べて。検索画面、リクエスト処理、状態遷移、関連テストを探し、現在の流れ、原因候補、最小の修正計画を説明して。まだファイル編集やコマンド実行はしないで。
計画を読み、原因が確認できたら /agents からBuildに切り替えて依頼します。
確認できた原因だけを修正して。読み込み中、結果あり、結果なし、リクエスト失敗を区別し、既存のコンポーネントと文言規則に従って。このバグを再現する回帰テストを追加・実行し、プロジェクトに定義済みの関連検証コマンドも実行して。変更ファイル、実行コマンド、合否、残る不確実性を報告して。コミットとプッシュはしないで。
完了を判断するのは開発者です。差分に無関係な変更がないかを見て、0件応答、エラー、連続検索を実画面でも確認します。テスト失敗時はエラー全文と期待動作を伝え、原因を絞ります。修正できない状態が続くなら、範囲をさらに狭めるか状態設計を見直します。
TUIガイドの /undo と /redo は変更の取り消しに役立ちます。ただしGit履歴やバックアップの代わりにせず、採用した変更を小さくコミットします。
エディターとチームでは何が変わるか
ACPはエディターとエージェントを結ぶプロトコルです。Zedでは OpenCodeのACP案内に従い、先にターミナルで opencode auth login を実行して認証し、既存の ~/.config/zed/settings.json に次をマージします。
{
"agent_servers": {
"OpenCode": {
"command": "opencode",
"args": ["acp"]
}
}
}
Zedのエージェント機能からOpenCodeを選び、プロジェクトを開きます。実行ファイルが見つからない場合は command にバイナリの絶対パスを指定します。opencode acp はプロトコルのメッセージを待つため、ターミナルで直接起動して無出力でも失敗とは限りません。
出典：OpenCode 2 ACP公式文書。2026年10月22日に公開ページを撮影。拡大表示。
チームでは長い開始プロンプトを各自でコピーする代わりに、プロジェクト指示の AGENTS.md に実際のビルド・テストコマンド、編集しない生成ファイル、レビュー基準を記し、バージョン管理します。並行作業は別ブランチとworktreeで衝突を減らせますが、モデル費用や権限まで自動的に分離されるわけではありません。
繰り返す手順は Skills の .opencode/skills/<skill-id>/SKILL.md に、外部ツールとの接続は MCPサーバーに任せられます。Skillは方法を説明し、MCPはツールや資料へのアクセスをつなぎます。必要なものから一つずつ追加し、結果と費用を確認します。
自動実行とローカルモデルの使いどころ
CLIコマンド案内の opencode run は対話画面を開かずに依頼を実行します。モデル接続済みのリポジトリで、次のレビュー演習から始められます。
opencode run --standalone --agent plan \
"Review this repository. Explain the test strategy and list gaps. Do not edit files or run shell commands."
依頼文だけでは読み取り専用を強制できません。無人のCIでは、専用レビューエージェントに編集と不要なシェル操作をDenyする規則を設定し、承認要求の処理方法も決めます。時間制限、失敗時の処理、出力保存先も用意します。CIのシークレット変数で提供者のキーを渡す場合、--standalone の専用サーバーに環境が渡るようにします。外部PRの信頼できないコードに秘密情報を渡さず、モデルのレビューで既存テストを置き換えないでください。
ローカル推論には Ollama などを選べます。提供者文書はローカルOllamaのモデル自動検出を説明しています。サーバーを起動しモデルを準備して、/models で確認します。ツール呼び出し対応、メモリー要件、応答時間を小さな修正で試してください。ローカルモデルでもWeb検索やMCPは通信する場合があり、作業全体がオフラインとは限りません。
実例から取り入れるのは検証の順序
Cloudflareの2026年2月の開発回顧は、OpenCodeで設計を議論し、実装とテストを繰り返した過程を紹介しています。誤った実装は人が修正しています。一つのチームの経験であり、同じ速度を誰にでも保証するものではありません。
自分のプロジェクトには順序を取り入れます。再現可能な問題を選び、現在と期待する動作を書き、計画を確認して修正と検証をつなぎます。新機能なら成功条件を先に決めます。レビューしきれない差分なら、依頼を小さく分割します。
費用とConsoleを区別して導入する
OpenCode Consoleは、モデルへのアクセス、チームのワークスペース、使用量と予算管理を提供する任意のサービスです。ローカルCLIから提供者へ直接接続する方式と、Consoleゲートウェイを経由する方式を区別します。アプリのオープンソースライセンスと、モデルのAPI料金や購読料は別です。
導入時点の告知も確認します。OpenCodeの2026年10月17日の公式告知は、外部提供者を接続したConsoleユーザーの一部に影響する侵害を報告し、Consoleユーザーの1.4%としています。該当する接続を使っていた場合は受信した案内と続報を確認し、関連キーと使用履歴を点検します。すべてのローカル環境で同じ事故が起きたと一般化したり、復旧済みと断定したりしないでください。
テストのある小さなリポジトリから始め、一つの修正がレビュー可能な差分と再現可能な検証結果になるかを評価します。その後、モデル選択、チーム規則、エディター連携、自動実行を順に加えると、各設定の効果を判断しやすくなります。
公式文書を基に作成したガイドと演習です。インストール、有料モデル呼び出し、リモート環境、CI実行を実測した利用記ではありません。
OpenCode es un agente de programación con IA de código abierto que lee y modifica código y realiza verificaciones desde terminales y editores habituales. Entender las conexiones de modelos, las reglas del proyecto, los permisos y los flujos prácticos permite pasar de pequeños cambios al desarrollo en equipo.
Qué es OpenCode
La escritura oficial de «Open Code» en este artículo es OpenCode. La explicación se basa en su sitio oficial y su repositorio. Es un programa que conecta el modelo elegido con la exploración del repositorio, los archivos y las herramientas; no es el propio modelo de lenguaje.
Tú planteas una solicitud y el agente lee archivos pertinentes, modifica código o ejecuta comandos y comunica resultados. Hay que revisar los cambios y las pruebas, no solo si la respuesta parece convincente. Código abierto tampoco significa que todas las llamadas sean gratuitas o que todo el código se procese localmente.
La instalación y configuración siguen la documentación de OpenCode 2 comprobada el 22 de octubre de 2026. La guía de migración desde V1 explica que ambas versiones usan opencode. Si ya lo tienes instalado, conserva una copia de la configuración y comprueba el método de instalación. Los complementos y las integraciones con la API del servidor de V1 requieren migración. V2 no ejecuta diagnósticos LSP: utiliza los comandos del proyecto para tipos, análisis estático y compilación.
Entornos que pueden usar los desarrolladores
| Entorno | Uso | Trabajo adecuado |
|---|---|---|
| Terminal local | Iniciar la TUI desde el proyecto | Comprender código, corregir errores y refactorizar |
| Terminal del editor | Ejecutar la CLI en la misma carpeta mientras ves el código | Cambios de componentes y revisión de diferencias |
| Editor compatible con ACP | Conectar el editor como cliente | Conversar con el agente dentro del editor |
| Escritorio o web | Aplicación oficial o interfaz web del servicio local | Gestión visual del trabajo |
| Desarrollo remoto o CI | Preparar repositorio, herramientas y credenciales en el host de ejecución | Revisiones repetidas e informes |
La introducción a OpenCode 2 describe el acceso desde terminal, escritorio y web. Usa opencode pair para conectar la interfaz web. Que la interfaz aparezca en un navegador no traslada automáticamente la ejecución a la nube. Según la arquitectura de la CLI, los clientes locales se conectan normalmente a un servicio compartido en segundo plano de la cuenta del usuario.
Por ejemplo, puedes abrir la terminal integrada de VS Code y comenzar en el repositorio. La instalación automática de extensiones y los atajos pueden variar entre versiones; verifica primero que la CLI funcione en el mismo proyecto. Con SSH, distingue los archivos, herramientas y credenciales del host remoto de los de tu ordenador.
Instalar y conectar un modelo
En macOS o Linux con Node.js y npm disponibles, instala el paquete oficial de V2 así. Sustituye /path/to/project por la ruta real del repositorio.
npm install -g @opencode/cli
cd /path/to/project
opencode
Son comandos para que los ejecute el lector: al preparar este artículo no instalamos el producto ni realizamos llamadas a modelos. La documentación de V2 indica que los gestores de paquetes de Windows no están admitidos; en Windows elige el binario independiente de la CLI o la descarga de escritorio oficial.
Dentro de la TUI, ejecuta estos comandos de uno en uno.
/connect
/models
/agents
Sigue la guía de conexión: selecciona proveedor y autenticación mediante /connect, y un modelo disponible con /models. Introduce las claves API en la interfaz de conexión, no en archivos del proyecto ni en ejemplos de instrucciones. Empieza por Plan en /agents.
La documentación de modelos distingue la selección del modelo de sus variantes de razonamiento. Las opciones cambian según el modelo, por lo que no debes inventar nombres como max. Empieza con valores predeterminados y una tarea pequeña; considera un razonamiento mayor, si está admitido, para diseños complejos o fallos repetidos. Compara calidad final y coste de rehacer trabajo, además de velocidad.
Fuente: página pública de la documentación TUI de OpenCode 2, capturada el 22 de octubre de 2026. Son instrucciones, no una sesión real. Ver a tamaño completo.
Separar Plan y Build y definir permisos
La documentación de agentes presenta Plan como exploración y planificación sin editar archivos normales del proyecto. Puede escribir archivos de planificación, y el shell sigue sujeto a permisos. No es un entorno completamente aislado de solo lectura. Build es el agente predeterminado para implementar.
V2 permite por defecto acceder fuera del proyecto. Puedes configurar explícitamente estas reglas iniciales en opencode.jsonc. Si el archivo existe, integra las reglas sin reemplazarlo por completo.
{
"$schema": "https://opencode.ai/config.json",
"permissions": [
{ "action": "edit", "resource": "*", "effect": "ask" },
{ "action": "shell", "resource": "*", "effect": "ask" },
{ "action": "external_directory", "resource": "*", "effect": "ask" },
{ "action": "shell", "resource": "git status *", "effect": "allow" },
{ "action": "shell", "resource": "git diff *", "effect": "allow" },
{ "action": "shell", "resource": "git push *", "effect": "deny" }
]
}
La documentación de permisos establece que gana la última regla coincidente. Este ejemplo consulta antes de editar o ejecutar comandos, permite consultas habituales de Git y deniega git push. El shell actúa con los permisos del usuario del host; estas reglas no aíslan el sistema operativo ni bloquean todas las rutas alternativas. Comprueba el comando y las rutas antes de aprobar.
Ejercicio: Corregir una búsqueda sin resultados
Este ejemplo se puede adaptar a un repositorio frontend. Inspecciona los cambios existentes y crea una rama independiente. Si el nombre ya existe, usa otro.
git status --short
git switch -c feat/search-empty-state
En Plan, define objetivo y alcance. Adjuntar el archivo real de la pantalla mediante @ reduce ambigüedades.
Investiga por qué sigue apareciendo el indicador de carga cuando la búsqueda devuelve cero resultados. Localiza la pantalla, el procesamiento de solicitudes, las transiciones de estado y las pruebas relacionadas. Explica el flujo actual, las causas posibles y un plan mínimo de cambios. Todavía no edites archivos ni ejecutes comandos.
Lee el plan y, cuando se confirme la causa, cambia a Build mediante /agents:
Corrige solo la causa confirmada. Distingue carga, resultados disponibles, ausencia de resultados y fallo de solicitud, siguiendo las convenciones existentes de componentes y textos. Añade y ejecuta una prueba de regresión que reproduzca el error y los comandos de verificación pertinentes ya definidos en el proyecto. Informa de archivos cambiados, comandos ejecutados, resultados y dudas restantes. No hagas commits ni pushes.
El desarrollador decide si ha terminado. Revisa que el diff no incluya cambios ajenos y comprueba respuestas vacías, errores y búsquedas consecutivas en la interfaz real. Ante un fallo de pruebas, aporta el error completo y el comportamiento esperado. Si los intentos siguen fallando, reduce el cambio o revisa el diseño de estados.
La guía de la TUI documenta /undo y /redo. Ayudan a revertir trabajo, pero no sustituyen el historial Git ni las copias de seguridad. Guarda los cambios aceptados en commits pequeños.
Qué cambia en editores y equipos
ACP conecta editores y agentes. Para Zed, sigue la guía ACP de OpenCode: autentícate primero con opencode auth login en una terminal e integra esta entrada en el archivo existente ~/.config/zed/settings.json.
{
"agent_servers": {
"OpenCode": {
"command": "opencode",
"args": ["acp"]
}
}
}
Selecciona OpenCode en la interfaz de agentes de Zed y abre el proyecto. Si no encuentra el ejecutable, asigna su ruta absoluta a command. opencode acp espera mensajes del protocolo, así que una terminal silenciosa al ejecutarlo directamente no implica un fallo.
Fuente: página pública de la documentación ACP de OpenCode 2, capturada el 22 de octubre de 2026. Ver a tamaño completo.
En equipo, registra comandos reales de compilación y pruebas, archivos generados que no deben editarse y criterios de revisión en AGENTS.md, las instrucciones del proyecto, y versiónalo. Así se evita copiar una instrucción inicial extensa. Las ramas y worktrees separados reducen conflictos entre tareas simultáneas, pero no aíslan automáticamente permisos ni costes de modelos.
Guarda procedimientos repetibles en .opencode/skills/<skill-id>/SKILL.md mediante Skills y conecta herramientas externas con servidores MCP. Skills describen métodos; MCP conecta herramientas y recursos. Añade lo necesario de uno en uno y comprueba resultados y costes.
Dónde encajan la automatización y los modelos locales
La guía de comandos CLI documenta opencode run para solicitudes sin interfaz interactiva. En un repositorio con acceso al modelo configurado, puedes iniciar esta práctica:
opencode run --standalone --agent plan \
"Review this repository. Explain the test strategy and list gaps. Do not edit files or run shell commands."
La instrucción por sí sola no impone solo lectura. En CI desatendida, configura un agente de revisión separado con reglas Deny para edición y shell innecesario, y decide cómo gestionar solicitudes de aprobación. Define tiempo límite, tratamiento de fallos y destino de resultados. Al inyectar una clave mediante secretos de CI, usa --standalone para que el servidor privado reciba ese entorno. No expongas secretos a código no confiable de PR externos. Las revisiones del modelo complementan las pruebas existentes.
Para inferencia local, puedes considerar Ollama. La documentación de proveedores describe la detección de modelos en un servidor local de Ollama. Inicia el servidor, prepara un modelo y compruébalo en /models. Evalúa llamadas a herramientas, memoria y tiempo de respuesta con un cambio pequeño. Aunque el modelo sea local, búsqueda web, MCP y otras funciones pueden usar la red.
Aprender la secuencia de verificación de un caso real
La retrospectiva de Cloudflare de febrero de 2026 describe planificación en OpenCode e iteraciones de implementación y pruebas, con correcciones humanas de implementaciones equivocadas. Es la experiencia de un equipo, no una garantía universal de velocidad.
Aplica la secuencia a tu proyecto: elige un problema reproducible, describe comportamiento actual y esperado, revisa un plan y conecta implementación y verificación. Para una función nueva, define primero el éxito. Si el diff resulta imposible de revisar, divide la solicitud en tareas menores.
Distinguir costes y Console antes de adoptarlo
OpenCode Console es un servicio opcional de acceso a modelos, espacios de equipo, seguimiento del uso y presupuestos. Distingue la conexión directa de la CLI local al proveedor del paso por la pasarela de Console. La licencia abierta de la aplicación y los costes de API o suscripción son asuntos diferentes.
Consulta también los avisos actuales. El comunicado oficial de OpenCode del 17 de octubre de 2026 informó de una intrusión que afectó a parte de los usuarios de Console con proveedores externos vinculados; indicó un 1,4 % de usuarios de Console. Si utilizaste esa conexión, revisa el aviso recibido y las actualizaciones posteriores, y comprueba claves y consumo relacionados. No lo generalices como un incidente idéntico en todas las instalaciones locales ni presupongas que la recuperación ha terminado.
Empieza en un repositorio pequeño con pruebas. Evalúa si un cambio produce un diff revisable y verificaciones reproducibles. Después añade modelos, reglas de equipo, integración con el editor y automatización por etapas, para saber qué mejora cada configuración.
Guía y ejercicios preparados a partir de documentación oficial. No es un informe de pruebas prácticas de instalación, llamadas de pago, entornos remotos ni ejecución en CI.