OpenCodeと
ハーネスをゼロから学ぶ。

「AIモデル」「エージェント」「ハーネス」。知らない言葉が重なると、それだけで難しく見えてしまいます。でも、一つずつ役割を分けると、身近な仕事の進め方とつながります。

この教材は、ITやAIの知識がほとんどない方を想定しています。最初にファイルやターミナルを説明し、次にAIが道具を使う仕組みへ進みます。そのうえで、OpenCodeは何をするソフトウェアか、その中と外にどんな仕組みがあるかを考えます。

この一文がまだ曖昧でも大丈夫です。「材料」「道具」「作業を進める」の意味を、これから具体的に説明します。最後には、同じAIモデルでも、周りの仕組みで仕事の進み方が変わる理由がわかるはずです。

今日は導入せず、仕組みだけ学べます

教材内の命令文は説明用です。読むだけであなたのMacにOpenCodeが入ったり、課金が始まったり、ファイルが変更されたりはしません。アカウント登録やAPIキーの取得も、読み進める条件ではありません。実際に使う準備は、仕組みと注意点を理解してから、別の作業として行えます。

長いので、三つの区切りで休憩してください

最初の区切りは第6章のエージェントまでです。「AIが答えること」と「コンピューターが動くこと」の間に、プログラムがあるとわかれば十分です。二つ目は第11章まで。OpenCodeを基準に内側と外側の役割を整理します。三つ目は第12章以降。版の見分け方、安全な始め方、復習を必要に応じて読み返します。

各章の緑色の枠は要点、ベージュ色の枠はたとえ話です。折り畳みの「もう一歩」は、気になったときだけ開いてください。たとえ話には限界があるので、実際の仕組みとの違いも説明します。言葉を忘れたら、用語集へ戻れます。

写真、文章、表、Webページ。コンピューターでは、こうした情報を名前の付いたまとまりとして保存します。これがファイルです。文章なら 案内文.txt、写真なら photo.jpg、Webページの記述なら index.html といった名前が考えられます。末尾の .txt や .html は「拡張子」といい、種類を見分ける手がかりです。

ファイルを整理する入れ物がフォルダーです。フォルダーの中にはファイルだけでなく、別のフォルダーも入れられます。「ディレクトリ」という言葉が出てきたら、この教材ではフォルダーとほぼ同じ意味で読んでください。

場所を文字で表したものが「パス」です

家の住所や道順を伝えるように、ファイルの場所も文字で表せます。この表し方をパスと呼びます。図の例で images/photo.jpg は、「今いる場所からimagesへ入り、その中のphoto.jpgを見る」という道順です。斜線の / が場所の区切りになります。

今いる場所を起点にした道順が「相対パス」、コンピューター上の基準点からたどる住所が「絶対パス」です。Macの /Users/名前/Desktop/練習用サイト/index.html は絶対パスの形の例です。この中の「名前」は説明用なので、そのまま入力するものではありません。~ は自分のホームフォルダーを表す記法としてよく使われます。

「プロジェクト」は、ひと仕事の材料一式

Webサイトやアプリを作るとき、材料は一つのファイルに収まらないことがあります。ページの文章、見た目の指定、写真、設定、確認の仕組みなどをまとめたひと仕事の単位をプロジェクトと呼びます。その材料が入っているフォルダーが「プロジェクトフォルダー」です。

AIに「見出しを直して」と頼んだとき、どのプロジェクトの、どのファイルを直すかが曖昧だと、別の材料を探してしまうかもしれません。「この練習用サイトのindex.htmlで、最初の見出しだけを直す」と伝えると、対象と範囲がわかりやすくなります。

書き換えた場所を見比べるのが「差分」

元の案内文が「おしらせ」、修正後が「お知らせ」なら、変わったのは一文字です。このように変更前後を比べ、どこが変わったかを示すものを差分、英語でdiffといいます。AIが長い説明を返したとしても、変更したファイルを見比べれば、頼んだ範囲に収まっているかを確認できます。

Gitは、ファイルの変更履歴を管理する道具です。「コミット」は、意味のある区切りで履歴に記録する操作を指します。Gitが難しく感じられる段階では、まず大切なファイルの別コピーを取るという考え方からで十分です。Gitを使っているだけで、あらゆる情報が自動で保護・復元されるわけではありません。

Macでフォルダーを開くとき、Finderでアイコンをダブルクリックできます。同じように、文字で場所を指定したり、プログラムを起動したりする方法もあります。その窓がターミナルです。ターミナルに入力した文字を解釈し、プログラムの実行などにつなぐものをシェルと呼びます。

「ターミナル」は見える窓、「シェル」は命令を読み取る担当、と分けると整理できます。厳密には別のものですが、日常会話では「ターミナルでこれを実行する」のようにまとめて言うことが多くあります。

pwd
ls
cd 練習用サイト

この枠を読むだけでは、あなたのMacで処理は動きません。通常はターミナルへ入力し、Returnキーなどで実行を指示したときに処理が始まります。コピーした、入力した、実行した、結果を確認した。この四つを区別しましょう。

CLIとTUIは、文字の窓で使う二つの形

CLIはCommand Line Interfaceの略で、コマンドを渡して操作するための入口です。たとえば一行の命令でプログラムを起動したり、条件を指定して処理させたりします。TUIはTerminal User Interfaceの略で、ターミナルの中にメニューや入力欄などを表示する画面です。文字中心でも、単に一行を打って終わる形だけではありません。

OpenCodeのTUIでは、ターミナルの中で依頼を入力し、作業の様子を読み取ります。マウス操作の多いデスクトップアプリやWeb画面と、仕事の入口が違うと考えれば十分です。同じ製品でも複数の入口が用意されることがあります。

コマンドは、短くても影響が大きいことがあります

場所を表示する命令もあれば、ファイルを書き換える命令、外からプログラムを取得して動かす命令もあります。見た目が同じ数行でも、結果は大きく違います。読めない命令をそのまま貼り付けず、「対象は何か」「何が変わるか」「外と通信するか」を先に確かめます。

AIが道具としてshellを使う場合も同じです。モデルが「このコマンドを実行したい」と出力し、OpenCodeと道具側が実行へつなぎます。モデルの文章が、そのまま魔法のようにファイルを書き換えるわけではありません。この間の仕組みが、後で学ぶハーネスにつながります。

ここで扱うAIモデルは、文章やコードなどの入力を受け取り、次の文章や行動案を生成する仕組みです。多くの文章やコードなどから学んだパターンを使います。人間のように現場を直接見ているわけでも、正しい答えだけを入れた辞書を引いているわけでもありません。

ChatGPTのような画面を使った経験があれば、入力した質問に返答が続く様子を思い出してください。その画面という製品と、裏で応答を生成するモデルは分けて考えられます。同じように、OpenCodeという製品と、OpenCodeが接続するモデルも別の役割です。

プロンプトは依頼文、コンテキストは今回の材料全体

プロンプトは、モデルへ渡す依頼や指示です。「この案内文を読みやすくして。日時は変えないで」のような文章を思い浮かべてください。コンテキストは、それを含む、今回の応答のためにモデルへ渡される情報全体です。会話、対象ファイル、道具の説明、検索や実行の結果なども材料に入ります。

つまり、プロンプトはコンテキストの一部です。とても長い依頼文を書いても、対象のファイルが渡されていなければ、必要な事実が足りないままかもしれません。逆に、無関係な資料を大量に渡すと、重要な条件を探しにくくなります。必要な資料を、わかる形でそろえることが役立ちます。

学習済みの知識と、その場で渡した資料は違います

モデルを作る段階で行う学習と、会話の途中で資料を渡すことは同じではありません。手順書を今回読ませたからといって、そのモデル自体が恒久的に書き換わると考えるのは早計です。後に出てくるスキルも、通常は必要な手順書を読み込ませる仕組みとして捉えます。

また、今回の会話をモデル提供元が保存したり、改善へ使ったりするかどうかは、サービスや契約、接続先の方針の問題です。「その場の資料として渡す」という技術上の説明と、「提供元が後でどう扱うか」は別の問いです。秘密情報を渡す前には両方を確認します。

もっともらしい返答も、事実と一致するとは限りません

AIは、存在しない設定項目、古い手順、実行していない確認結果を、自信のありそうな文章で返すことがあります。「読みやすい文章で言われたこと」と「確かめられた事実」を分ける必要があります。OpenCodeのV1とV2の手順が混ざる問題も、その一例です。

モデルを強いものへ変えると、できることが増える場合があります。それでも、必要なファイルがない、道具がない、権限がない、費用の上限がない、といった周辺の問題が自動で解決するわけではありません。能力、材料、道具、権限、検証をそろえて初めて仕事になります。

トークンは、扱う情報量の単位

AIサービスでは、入力や出力の量をトークンという単位で数えることがあります。文章を処理しやすいかたまりへ分けた単位で、日本語の一文字と常に一対一ではありません。長い資料や長い返答は、多くのトークンを使うことがあります。

モデルには一度に扱える情報量の限りがあります。保存された会話が全部残っていても、毎回それを全部渡すとは限りません。古い会話を要約する工夫や、必要な資料だけ選ぶ工夫が必要です。この「材料を管理する仕事」もハーネスの大事な部分です。

人がレストランで注文するときは、店員へ料理名を伝えます。プログラム同士でも、決められた形式で依頼を送り、結果を受け取ります。そのための窓口や取り決めがAPIです。Application Programming Interfaceの略ですが、まずは「プログラムから使える注文窓口」で十分です。

モデルとプロバイダーは別の言葉です

プロバイダーは、モデルを利用するサービスや接続先です。同じモデル名でも、直接その提供会社へ接続する方法と、別の窓口を経由する方法があり得ます。どこへ送るかによって、認証、料金、使える機能、データの扱いが変わることがあります。

たとえばClaudeはモデルの系列名として使われますが、Claude Codeは別のソフトウェア製品です。OpenCodeからClaudeのモデルを使うことと、Claude Codeという製品を起動することは同じではありません。「同じモデルが使えるから、中身も同じ製品」とは言えないのです。

APIキーは「使う権利」を示す秘密の情報です

APIキーは、その窓口を使うアカウントなどを示す秘密の文字列です。ほかの人に渡すと、自分の利用枠や料金で使われるなどの問題が起きる可能性があります。教材やSNSの画面、公開するコード、質問のログへ貼らないようにします。

認証には、APIキーを使う方法のほか、ブラウザでアカウントへログインし、接続を許可する方式などもあります。すべての接続先が同じ認証方法ではありません。この教材ではキーを取得したり、認証したりせず、役割を説明するところまでにします。

無料のソフトウェアと、無料のAI利用は別です

OpenCode本体がオープンソースで提供されていることと、モデルを何回でも無料で呼べることは別です。レストランへ行くための地図を無料でもらえても、料理がすべて無料になるとは限らないのと同じです。

モデルの利用料は、接続先、プラン、入力・出力量などで変わります。一つの依頼の途中でモデルへ何度も問い合わせることもあります。利用者が一回送信したから、内部でも一回だけの利用になるとは限りません。開始前に、どこの契約で使い、どこで残高や上限を確認するかを決めます。

「ローカル」は、どの部分の話かを確かめます

OpenCodeが自分のMacで動く。モデルも自分のMacで動く。ファイルが自分のMacにある。道具が外部サーバーで動く。これらは別々に組み合わせられます。「ローカルで使う」という一言だけでは、全体の通信先はわかりません。

秘密のない練習用の文章なら、仕組みの学習に使いやすくなります。顧客情報などを扱うときは、モデルの名前に加えて、接続先、仲介サービス、道具の送信先、契約上の扱いも確認します。詳しい確認項目は第14章へつなぎます。

普通の質問応答なら、「この文章の直し方を教えて」に対して、修正案が返れば一区切りです。エージェントでは、その先の「対象を探す」「ファイルを読む」「修正する」「確認する」へ進めます。もちろん、道具や権限、環境がそろっている範囲での話です。

エージェントという言葉は幅広く使われます。この教材では、AIモデルが次の行動を選ぶ出力を行い、周辺のプログラムが道具を実行し、結果を再びモデルへ渡す仕組みを中心に考えます。自分の意思で何でも動く人間の代理人、と覚える必要はありません。

道具を使いたいという出力と、実行成功は別です

モデルは「検索ツールに、この語句を渡したい」のように、ツールの名前と引数を出力できます。これを受け取ったプログラムが、呼出しを解釈し、必要なら許可を確認して実行し、結果を返します。こうした使い方は、ツール呼出しやfunction callingと呼ばれます。

「修正ツールを呼んだ」は、修正が成立したという意味ではありません。ファイルが見つからない、書き込めない、変更対象の文が一致しないなどで失敗することもあります。結果を受け取り、必要なら調べ直す循環が欠かせません。

止め方と、成功の条件を人が決めます

「いい感じに全部直して」だけでは、対象も終わりも曖昧です。「最初の見出しの誤字だけ直す。日時・リンクは変えない。変更箇所と確認結果を報告する」とすると、行動範囲と成功条件が明確になります。

エージェントが途中で質問したり、承認を求めたり、エラーで止まったりするのも、仕事の一部です。止まらず走り続けることだけが優秀さではありません。材料が足りない、外部の支払いが必要、判断が利用者に属するといった場面では、人へ戻せることが役立ちます。

ここまでで、「モデル」「道具」「結果」「反復」がそろいました。次は、それらを製品としてつなぐOpenCodeを見ていきます。

OpenCodeは、ソフトウェアを作ったり直したりする仕事を支援する製品です。公式リポジトリは anomalyco/opencode。リポジトリとは、ここではGitHubで公開されているソースコードや開発情報のまとまりです。ふだん利用するだけなら、このソースコード一式を自分で改造する必要はありません。公式配布のアプリやCLIという入口があります。

「コーディング」は、プログラムやWebページの材料となるコードを書くことです。OpenCodeはコードについて説明するだけでなく、利用できる道具と権限に応じて、ファイルを探す、読む、変更する、コマンドで確認するといった作業へ進めます。

何を頼めるかを、成果物から考えます

たとえば、既存のプログラムを読んで仕組みを説明してもらう、簡単なWebページを作る、小さな不具合の原因を調べる、修正案を出す、確認用のテストを整える、といった使い方があります。ファイルに入った文章や説明書の修正も、作業の一部になり得ます。

初めての方なら、「架空の読書会を紹介するページを一枚作る」「この見出しの誤字だけ直す」のように、対象と完成条件を小さくするのが学びやすい入口です。「アプリを全部いい感じにして」と広く任せるより、何が行われたかを理解しやすくなります。

同じ製品に、いくつかの操作窓口があります

OpenCodeには、ターミナルのTUI、デスクトップアプリ、Web画面などの入口があります。どの窓口を使うかは、操作の慣れや目的に応じて選びます。文字の窓口を使うから高性能、デスクトップだからAIの種類が固定、という分け方ではありません。

V2ではクライアントとサーバーの役割が分かれています。クライアントは人が触る窓口、サーバーは依頼を受け、会話や道具の実行などを扱う裏方です。通常、同じMacユーザーのローカルクライアントは、共有のバックグラウンドサーバーへ接続します。サーバーという言葉が出ても、必ず遠くのクラウドを指すわけではありません。

BuildとPlanは、仕事の役割設定です

OpenCodeの「エージェント」は、製品全体の仕組みを指す場合に加え、指示、使うモデルの指定、権限などをまとめた役割設定も指します。Buildは実装を進める役割、Planは調査や説明、計画を先に進める役割です。モデルを替えることと、役割を替えることは別です。同じモデルでも役割を切り替えられます。

V2のTUIでは /agents や Shift+Tab が切り替えの入口として案内されています。入力先は起動後のOpenCodeの画面です。Macのターミナルに /agents と直接入力する、という意味ではありません。

OpenCodeが引き受けない判断もあります

利用者の目的が正しいか、公開してよい情報か、費用を払ってよいか、業務上の責任を誰が持つか。これらをソフトウェアの「完了しました」という返事だけに預けることはできません。特に実際の顧客や本番サービスを扱う仕事は、練習用ページより重い確認が必要です。

OpenCode本体のライセンスはMITですが、モデルの利用契約や外部サービスの規約まで一緒に決まるわけではありません。作る道具、本体の配布、モデルの利用、完成品の公開を分けて考えます。

ここでは、架空の読書会ページのタイトルにある「読書かい」を「読書会」へ直す場面を追います。実際に動かした記録ではなく、仕組みを理解するための学習例です。すべての依頼が必ず同じ順序、同じ回数で進むわけではありません。

場面1：OpenCodeが今回の材料をそろえます

OpenCodeは依頼文だけでなく、会話の履歴、プロジェクトの指示、使える道具の説明などを、今回モデルへ渡す材料にします。モデルが、Macのフォルダーすべてを最初から見通しているわけではありません。

モデルは「対象の語句がどこにあるか調べたい」と出力します。名前や場所から探す glob、ファイル内の文字を探す grep などが道具の例です。モデルは道具の名前と条件を出し、OpenCode側が実行へつなぎます。

場面2：道具が調べ、実際の結果を返します

検索結果に index.html が出たら、次に read のような道具で内容を読みます。同じ語が本文にもあるかもしれないので、単に全部置換すればよいとは限りません。「タイトルだけ」という条件と実際の構造を照らし合わせます。

道具を呼ぶ前の許可判定でaskになれば、利用者の確認を待つことがあります。allowなら自動で進む場合があります。操作のたびに必ず確認が出ると思い込まず、どんな設定で動いているかを先に確かめることが大切です。

場面3：対象を絞って編集します

モデルが変更案を出し、編集系の道具がファイルへ反映します。たとえば edit は一部の変更、write は新規作成や全体の書き込みに使われます。利用できる道具はモデルや設定によって変わります。

場面4：確認を実施し、その限界も報告します

変更後のファイルを読み直し、差分を見れば、意図した文字が変わったかを確認できます。既存のテストがあれば、必要に応じてshell経由などで実行できます。一方、ファイルの文字を確認しただけでは、ブラウザでレイアウトが崩れないことまで確かめたとは言えません。

確認の方法にはそれぞれ役割があります。lintはよくあるミスや書き方を調べるもの、型チェックはデータの種類の整合性を調べるもの、テストは期待した動作を確かめるものです。ビルドは材料から動かせる形を作る工程です。どれか一つが通ったから、見た目もすべて正しいとは限りません。

この報告なら、できたことと未確認のことを分けて受け取れます。「完成です。テスト済みです」だけだと、何をどう確かめたのかがわかりません。必要な証拠を見てから、利用者が完成条件に合うかを判断します。

失敗したら、結果を材料にして次へ進みます

検索で見つからない、編集が一致しない、テストが失敗する。このような結果も、次の判断に使う情報です。エージェントは必要なら調べ直します。無意味に同じ操作を繰り返すのでなく、前の結果を読んで方法を変えられるかが大切です。

途中で通信が切れた場合、外部サービス側で操作が成立したかどうかが、すぐにはわからないこともあります。単なる読み取りと、メール送信や支払いのような外部作用では、再試行の意味が違います。結果不明の重要操作を、確かめず繰り返してよいわけではありません。

ハーネスという英語は、馬具や身体を支える装具などにも使われます。AIの文脈では、モデルが受け取る入力を整え、道具の呼出しを調整し、結果を戻し、作業の進行を支えるシステムを指すことがあります。

言葉の範囲は文脈で変わります。画面まで含めた製品全体をハーネスと呼ぶ人もいれば、モデルを動かす実行部分を中心に呼ぶ人もいます。この教材では、「モデルを、道具と情報を使って働ける仕組みにつなぐ部分」を中心に説明します。

「OpenCode自体がハーネスですか」への答え

機能に注目すれば、おおむね「はい」と言えます。OpenCodeは入力欄を用意するだけでなく、材料を整え、モデルを呼び、ツールを動かし、結果を戻して作業を続ける仕組みを持つからです。これはハーネスの機能的な説明と対応します。

ただし「ハーネス」がOpenCode公式の製品名になった、という話ではありません。公式の紹介はcoding agentです。「コーディングエージェントという製品が、ハーネスの役割を持っている」と考えると、言い方の違いに振り回されずに済みます。

長い依頼文と、よいハーネスは同じではありません

「丁寧に」「絶対に間違えず」「最後まで」と指示することは、役立つ場合があります。でも、文章だけでファイルが読めるようになったり、テスト環境が準備されたり、費用の上限ができたりはしません。資料、道具、記録、確認、停止の仕組みを整える必要があります。

長時間作業の設計では、初めに環境を整える役割と、小さな進捗を積み上げて引継ぎを残す役割を分ける工夫が研究されています。大きな指示書を一度に詰めるより、短い入口から必要な資料へたどれるようにする考え方もあります。モデルの能力と、仕事の進め方の設計は、両方とも必要なのです。

たとえの限界も覚えておきます

馬具のイメージから「ハーネスがあればAIは絶対に暴走しない」と考えるのは誤りです。ハーネスには便利さのための処理も、確認のための処理もあります。セキュリティ上の隔離があるかは、実際の実装と環境で確かめる必要があります。OpenCodeのpermissionsだけをOSの隔離の壁とは扱いません。

ここから、工房の中の担当を見ていきます。内部ハーネスという小さな一個の部品がある、と考える必要はありません。実装上は複数のプログラムに分かれる働きを、理解のためにまとめて呼んでいます。

1．依頼を受け、セッションを持つ

セッションは、一つの仕事について続く会話や状態のまとまりです。依頼、道具の結果、選んだモデルや役割などを管理します。受付に依頼が届いたことと、モデルがすでにそれを読んで処理したことは別です。

V2の公開ソースでは、入力を記録し、実行側へ進行を促す構成を確認できます。作業中の追加指示などを扱うときにも、この区別が必要です。利用者から見える一つの画面の裏で、受付、状態、実行が連携しています。

2．今回モデルへ渡す材料を組み立てる

プロジェクトの指示、使える道具、会話、必要な資料をまとめる役割です。全部を無差別に渡すのでなく、モデルが使える量や形式を意識して組み立てます。AGENTS.md のような常設の指示も、この材料に関わります。

手順書に「外へ送信しないで」と書くことと、通信を技術的に止めることは別です。指示文はモデルの判断を導く材料であり、OSのアクセス制御を自動で書き換える仕組みではありません。

3．モデルやプロバイダーへ接続する

利用可能な接続先とモデルを選び、要求を送って応答を受け取ります。モデルによって使える機能や出力の性質が異なります。OpenCodeがClaudeモデルを使う場合も、それだけでClaude CodeやClaude Agent SDKを中で起動しているという意味にはなりません。

4．道具を見せ、呼出しと結果を扱う

「何の道具があるか」「どういう条件で呼ぶか」をモデルへ知らせることと、実際にその道具を動かすことは両方必要です。OpenCodeにはread、glob、grep、編集系、shellなどの道具があり、拡張やMCP経由の道具が加わることもあります。

ツールの失敗も隠さず結果として返すことが大切です。成功したふりをして先へ進むと、モデルは誤った前提で次の作業を組み立ててしまいます。プロバイダー側で実行される道具もあるため、すべての処理が自分のMacで動くとは限りません。

5．実行の許可を判定する

V2のpermissionsは、操作の種類であるaction、対象であるresource、判定であるeffectを使う仕組みです。effectはallow、ask、denyです。順番にも意味があり、複数に一致すると最後に一致したルールが使われます。保存された許可や役割ごとの設定も関わるため、実際の設定を確認します。

6．続けるか、止めるかを調整する

結果をモデルへ戻し、次の手へ進みます。ただし、追加指示、停止要求、失敗、ステップ数の上限なども関わります。V2のagentsのsteps設定では、最後のステップで道具を外し、文章でまとめるよう求めます。これは「指定回数で必ず成功する」という保証ではありません。

作業は、完了、質問待ち、承認待ち、中断、エラーなどで区切られます。成果がまだないのに、時間切れのまとめが返ってきた場合もあるので、最終文と実際の成果物を分けて見ます。

7．長い会話の材料を整理する

会話が長くなると、モデルへ一度に渡せる量の上限に近づきます。V2のcompactionは、古い会話を要約し、最近の会話などと合わせて続きを進める仕組みです。自動整理は標準で有効ですが、要約には細部の抜けがあり得ます。

重要な条件を会話の最初に一度書いただけでは、長い作業の最後まで同じ精度で保てるとは限りません。目標、変更しないもの、確認方法を短いファイルへ残し、最後に照合する工夫が役立ちます。履歴が残ることと、モデルが今見ていることは別です。

8．記録を残し、再開や調査へつなげる

状態や結果を保存すれば、進行の表示、作業再開、問題の調査に使えます。ただし、再開できることは外部操作を必ず一度だけ実行できることと同じではありません。切断直前に外部で成立した操作がわからないときは、その相手側でも結果を確認します。

OpenCodeの内側で仕事を進める仕組みがあっても、仕事全体の流れを誰かが決める必要があります。たとえば「問い合わせを受け取る→対象プロジェクトを選ぶ→修正を依頼する→差分とテストを検査する→人のレビューへ回す」という会社独自の流れです。

この流れを別のプログラムで管理し、OpenCodeへ依頼する設計が考えられます。外部ハーネス、あるいはより限定して外部のオーケストレーション層と呼べます。オーケストレーションとは、複数の作業の順序、分担、終了判定などを調整することです。

一枚の画面を付ければ、必ずハーネスになる？

入力と出力を受け渡すだけなら、クライアントやラッパーと呼べば十分な場合があります。画面をかぶせたこと自体より、何を担当するかが大切です。状態管理、検証、再試行、承認、引継ぎまで担うほど、外側の制御層としての意味が強くなります。

たとえば「テストが通るまで何度でも直す」という外側の仕組みを作ったとします。費用や時間の上限がなければ、同じ失敗を繰り返すかもしれません。テストが目的とずれていれば、テストに通っても良い成果とは限りません。回数、予算、停止条件、人へ戻す条件を設計する必要があります。

人の運用にも、同じ考え方を使えます

すべてをプログラム化する必要はありません。利用者が練習用フォルダーを用意し、バックアップを取り、依頼を小さくし、差分を見て検品する。これも、モデルの外側の作業環境を整える考え方です。ただし、人の確認手順そのものを製品上の公式機能として「外部ハーネス」と名付けるわけではありません。

自動化する場合も、最初はこの人の手順を言葉にしてみると役割が見えます。「何を入力にするか」「何を成果と呼ぶか」「どこで止めるか」「どんな証拠を残すか」を説明できることが、複雑な仕組みを作る前の土台になります。

内側と外側は、基準の線で変わります

モデルだけを囲めば、OpenCodeはモデルの外側です。OpenCodeを囲めば、そのセッション処理は内側です。会社の業務アプリ全体を囲めば、OpenCodeも業務アプリの内部の部品になります。本教材ではOpenCodeを基準にしているので、図にもその名前を記しました。

「内部ハーネスはモデルの頭の中」「外部ハーネスはクラウド上」と覚えると誤ります。同じMacの中でも役割は分かれますし、別のマシンにあっても一つの仕事を支える部品になれます。

ここは発展編です。最初からすべてを使う必要はありません。似た言葉が出てきたときに、「これはどの役割を増やすのか」と確認するための見取り図として読んでください。

まず、いつもの依頼を使いやすくする部品

opencode.json や opencode.jsonc は、モデルや権限などを機械が読む形式で書く設定票です。JSONCではコメントも書けます。プロジェクト用と広い範囲に適用する設定、管理者の設定などがあるため、一か所だけ見れば全体が決まるとは限りません。既存設定を丸ごと置き換える前に、適用範囲と優先順位を確認します。

AGENTS.md は、その仕事場の心得を文章で渡す指示ファイルです。「このプロジェクトは架空の読書会の練習ページです。外部サービスを追加せず、変更箇所と確認方法を日本語で報告してください」といった内容が考えられます。これは独自の教材例であり、OSの保護機能ではありません。V2ではAGENTS.mdを認識し、CLAUDE.mdへの自動フォールバックはありません。

Skillsは必要な場面で開く再利用可能な手順書です。たとえば .opencode/skills/説明用ID/SKILL.md のような場所に手順をまとめ、必要な参考資料やスクリプトへつなげます。スキルを読ませることは、モデルの学習済みの重みを書き換えることではありません。スキルの説明があるだけで、接続されていない外部サービスの権限まで増えるわけでもありません。

Commandsは、よく使う依頼のひな形を呼び出す仕組みです。「変更を確認し、問題を説明して」といった定型文を繰り返し使いたいときに役立ちます。自分で追加したコマンドと、製品標準の /models などのスラッシュコマンドは分けて考えます。

外の道具をつなぐMCP、動作を拡張するプラグイン

MCPは、外部の道具や情報源へ接続するための共通の取り決めです。資料の検索や別サービスの操作などを、使える道具としてつなぐ場面があります。ローカル型はMac上で別のプログラムを起動し、リモート型はネットワーク上の接続先と通信します。認証時に外部アカウントの権限を渡す場合もあります。

MCPは接続の形式なので、「MCP対応だから信頼できる」という保証にはなりません。何を読めるか、何を変更できるか、どこへ情報を送るかを、接続先ごとに確認します。V2の設定では mcp.servers の下で定義しますが、初心者の最初の練習に追加は不要です。道具を増やすと、その説明に使うコンテキストも増えます。

プラグインはOpenCodeの動作へコードで機能を足す部品です。道具、エージェント、処理の途中に参加する機能などを追加・調整できます。設定したnpmパッケージやローカルのコードを読み込み、実行することがあります。.opencode/plugins 以下も自動検出されるため、見知らぬプロジェクトの内容を確認せず開くことにも注意が必要です。

OpenCodeを使うアプリを作る、三つの方法

ここでSDKという言葉が出てきます。SDKは、ソフトウェアを開発するときに使う部品や入口のまとまりです。SDKという名前だけでは、単にAPIを呼ぶものか、エージェントの実行まで持つものかはわかりません。公式資料で担当範囲を確認します。

外からAPIで呼ぶアプリが、内部の道具の循環を全部自作する必要はありません。OpenCodeの実行を利用しながら、外側に独自の受付や成果検査を置けます。逆に、プラグインで内側の動作を調整することと、外側で仕事全体を管理することは、異なる役割です。

子エージェントは、OpenCode内の別セッション

V2のsubagentは、子のセッションへ調査などを分担する仕組みです。GeneralやExploreのような役割があります。新しい子セッションは新しいコンテキストで始まるので、親の会話を全部知っているとは考えません。必要な目的、対象、条件、返してほしい結果を渡す必要があります。

子には子の設定された権限があり、親にはどの子を呼べるかの許可があります。子の権限が必ず親より弱いと断言はできません。モデルの種類が親と違っても、OpenCode内のセッションである点は変わりません。

担当を増やすと、背景の受渡し、同じファイルの編集競合、重複作業、費用、待ち時間も増え得ます。V2の標準Generalは、さらに子を起動する用途を許されていません。読んだdevソースにも深さの制限があり、無制限に孫が増える仕組みとして説明するのは不適切です。

LSPは、V2では実行されません

LSPはプログラミング言語の診断などを、エディターと別のプログラムでやり取りする仕組みです。V1の記事で説明があっても、その機能をそのままV2へ当てはめないでください。V2はLSP設定を受け取りますが、LSPサーバーを実行せず、LSPの道具や診断を提供しないと移行資料にあります。

したがってV2の確認は、必要に応じたlint、型チェック、コンパイラー、既存テストなどの実行結果へつなげて考えます。「コードを書いたから自動で言語診断も済んだ」とは扱いません。

ソフトウェアは更新され、名前が同じでも仕組みが変わります。OpenCodeも、V1とV2で導入、設定、APIなどに違いがあります。本教材は2026年10月15日に読んだV2公式文書と、v2.0.29の公開ソースを基準にします。利用者のMacへすでに入っている版は確認していません。

公式Changelogでは2026年10月14日のv2.0.29を確認した一方、GitHub ReleasesのLatest表示にはv1.19.0が残っていました。したがってLatestというラベルだけで、V2が存在しない、これが製品全体の最新だ、と判断しません。以下の表を、資料を読むときの取り違え防止に使ってください。

この表のV1列は、違いを見分けるための参照です。V1の操作を今から実行する手順として並べたものではありません。両方とも opencode というコマンド名を使うため、何も考えずに両方を並行導入する前提にもしません。既存利用者は設定の控えを取り、公式の移行資料を確認します。

Macで使う入口を、一つ選びます

以下は公式資料に基づく導入の説明であり、この教材制作では実行していません。初めてなら、まず公式DownloadでMacのデスクトップ版を確認する流れがわかりやすいでしょう。Apple SiliconとIntelで配布が分かれるので、Macの種類を確認します。更新で画面が変わるため、未検証のボタン位置やクリック順は固定しません。

すでにHomebrewやnpmを使っている方は、CLIという入口もあります。HomebrewはMacでソフトウェアを管理する道具、npmはNode.js系のパッケージを管理する道具です。どちらも、まだ使えるか不明な人へ前提なく貼り付けを求めるものではありません。

brew install anomalyco/tap/opencode-v2

npm install -g @opencode/cli

Homebrew利用者向けには、デスクトップ版を導入する brew install --cask opencode-desktop の公式案内もあります。これはCLI版を選ぶこととは別です。公式スクリプトを取得して実行する方法もありますが、何が取得・実行されるかを理解する必要があるため、ここでは本筋の手順として載せません。

opencode ~/code/my-project

接続、モデル、役割はOpenCodeの中で選びます

起動後のTUIでは、/connect でプロバイダーと認証方法を選び、画面の案内に従います。その後、/models で実際に表示されたモデルを選びます。モデルIDを想像して入力するより、表示された選択肢と接続条件を確かめます。選択したモデルが会話へ適用されることと、設定ファイルを編集することは別です。

本物のAPIキーや認証トークンを教材、公開チャット、スクリーンショットへ貼らないでください。V2の認証情報はサーバー側のSQLiteへ保存され、通常のローカルDBは ~/.local/share/opencode/opencode.db です。旧V1のauth.jsonをV2の通常の保存先と説明しません。

Web画面と、遠隔アクセスを分けます

V2のWeb接続の入口は opencode pair です。通常はローカルのサーバーへ接続するためのリンクを表示し、リンクは一度だけ使え、5分で失効します。Web画面は同じ裏方につながる窓口であり、独立した無料のクラウド実行サービスだとは説明しません。

--remote を付ける場合や、DesktopのPair deviceから遠隔アクセスを有効にする場合は、話が変わります。インターネットから接続できるようにする機能が関わります。初めの練習では有効にせず、詳しい違いを安全の章で確認します。

ここまで読めたら、AIがどのように行動へつながるかが見えてきたと思います。安全の考え方も、特別な呪文ではありません。「何を読めるか」「何を変えられるか」「どこへ送るか」「どこで止めるか」を具体的に決めることから始まります。

確認はブレーキ。隔離は作業場所を分ける壁

OpenCodeの公式SECURITY.mdは、エージェントをsandbox化しておらず、権限の仕組みが安全な隔離を保証するものではないと明記しています。サンドボックスは、プログラムが触れる資源を技術的に制限する環境のことです。確認画面があることと、その環境があることは別です。

shellの操作は、実行するホストのユーザー権限で、ファイル、プロセス、ネットワークへ影響します。コマンドの文字から操作先を推測するチェックにも限界があります。必要に応じてDockerや仮想マシンなどで分離する考え方がありますが、そこへホームフォルダーや秘密情報を丸ごと渡せば意味は薄くなります。初心者はまず秘密を持ち込まない小さな環境から始めます。

既定値より、自分の版と設定を確認します

固定版v2.0.29のAgent基本設定は全操作allowです。*.env と *.env.* のreadはask、*.env.example はallowとなっています。これは秘密の自動検出を保証するものではありません。名前が違う秘密ファイルはあり得ますし、別の道具やコマンドから内容へ触れる場合もあります。

動的なV2文書には異なる既定値の説明もあるため、「インストールしたままなら必ずこうなる」と断定せず、使う版と適用設定、エージェント固有の上書きを確かめます。Planもshellまで一律に止める保証にはせず、必要な確認を明示します。

Allow onceとAllow alwaysは、効果の広がりが違います

確認画面で一度だけ許可することと、今後も許可することは同じではありません。v2.0.29の保存済み権限は、ツールが提案したパターンをプロジェクト単位でDBに記録します。Alwaysを「今の会話だけ」と覚えないでください。広い * のパターンなら、想像より広く適用される可能性があります。

意味がわからない間は、コマンド、対象、送信先を確認してから一度だけ許可する方が判断しやすくなります。わからなければ拒否し、「何のために、何が変わるかを説明して」と戻します。なお、保存したallowが設定済みのdenyを覆すわけではありません。

{
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" }
  ]
}

情報の行き先は、ローカルと外部の両方にあります

クラウドモデルを使う場合、質問、必要なコード、道具の実行結果などが、会話のコンテキストとして接続先で処理されます。OpenCodeがオープンソースであること、Macで起動したこと、モデル提供元が何を保存・学習利用するかは別の話です。

モデル提供元、仲介する窓口、MCPサーバーそれぞれで、送信する情報と扱いを確かめます。Consoleのモデル別説明には、一部の無料モデルで入出力を改善や学習へ使う例外や、機密情報を送らないよう求める注意があります。安さとプライバシーは別の軸です。

ローカルにも、会話、スナップショット、認証情報などが残ります。v2.0.29では認証値をSQLiteのcredentialテーブルに保存し、確認した経路にはアプリ独自の暗号化は見当たりませんでした。POSIXではDBと関連ファイルの権限を所有者のみに制限しますが、それだけでOSの暗号化状態やすべての保管条件までわかるわけではありません。

データフォルダーやDBを丸ごと共有したり、Gitへ登録したり、公開の不具合報告へ添付したりしないようにします。ログや画面も、キー、個人情報、パスを見直してから渡します。Undoなどで「会話を戻した」ことも、DBなどに残った情報を安全に消去した証明にはなりません。

共有リンクとPair deviceは、別の機能です

調査時点のV2は、会話の共有リンクにまだ対応していません。V1の /share の説明をそのまま使いません。一方Pair deviceは、別の端末をOpenCodeのサーバーへ接続する機能です。共有が未対応だから遠隔接続も一切ない、という意味ではありません。

DesktopのPair deviceは、v2.0.29ではOpenTunnelを使うremote accessを有効にし、インターネット経由の接続準備を始めます。同じLANの中だけに限る機能とは説明できません。通常の opencode pair と --remote 付きの動作も区別します。

V2のWebは既定でlocalhostを使い、パスワードで保護されます。ペアリングコードは一回限りで5分有効、接続後のセッションは30日とされています。サーバーパスワードの変更で既存セッションは失効します。QRや接続リンクも認証情報同様に扱い、公開画面へ載せません。初めての練習では遠隔接続は有効にしません。

Undoは、パソコン全体のタイムマシンではありません

V2には /undo と /redo がありますが、ファイル復元には条件があります。スナップショットは、Gitリポジトリ内のactive directory、つまり現在の作業対象の範囲を中心とした補助です。Gitがないフォルダーでは、会話を戻せてもファイルを戻せません。

固定版ではGitの無視対象、対象ディレクトリ外、2MiBを超える未追跡ファイルなどは対象外です。取得もbest effortで、すべてを必ず記録する保証ではありません。データベースへの変更、外部へ送った通信、別サービスの更新、起動したプロセス、Gitのコミットやブランチなども戻せません。

Undo対象に、自分が後から追記した内容があれば、戻す操作で上書きされる場合もあります。まず実行を止め、差分と保存状態を見て、大切な追記を別に控えます。作業前のバックアップやGitの区切りを用意しておく理由がここにあります。

費用を、三つの財布に分けて考えます

チャットサービスの月額契約、APIの従量契約、OpenCodeのプランは同一ではありません。手元の契約を利用できるかは、接続方法と提供元の条件で確認します。一回の依頼で、モデルとの往復、再試行、長い文脈、子エージェントが発生することがあるので、「質問一回＝課金一回」とも限りません。

ConsoleとGoは、任意の選択肢です

旧資料のZenという名前は、OpenCode側が用意するモデルへの窓口の説明で出てきます。調査時には旧ZenページがV2のConsole Modelsへ転送されていました。現行教材ではConsoleの従量課金モデルとして捉えます。Consoleを使わず、別のプロバイダーへ直接つなぐ選択肢もあります。

調査時のConsoleは席数による料金なしで、前払いクレジットを利用します。クレジット追加の処理手数料は4.6%＋$0.31で、公式例では$50の残高追加に$52.61を支払います。直接つないだ別プロバイダーの利用は、そちら側の請求を確認します。

開始前には残高、月次予算、自動追加のauto-recharge、Goのextra usageを見ます。予算を設定しなければ、予算による制限はありません。予算到達後は新規リクエストが止まっても実行中の分は完了するため、少し超える場合があります。自動追加の既定値は公式ページ間で表現が異なるため、本教材では固定値を断定せず、実際のBilling画面で確認する方針にします。

固定版の公開ソースでは、画面に出す親セッションの費用に子セッションの分も合算する実装になっています（Desktopの実際の表示は未確認です）。それでも画面表示は請求明細や予算上限そのものではありません。途中で無料モデルへ替えても、それ以前の有料利用が消えるわけではありません。

初回にそろえる、小さな確認リスト

• 作業は練習用の一フォルダー。APIキー、本番DB、顧客・社員の情報を入れない。
• 大切な既存ファイルは別に保存。Gitを使うなら変更前の区切りを残す。
• モデル名、接続先、料金、保持・学習利用の条件を確認する。
• shellや外部フォルダーへのアクセスの設定を見る。広いAlwaysを意味が不明なまま選ばない。
• Planで内容を理解してから、小さな一変更ずつ進める。役割名を隔離の代わりにしない。
• 導入、削除、送信、権限追加が提案されたら、対象と影響を読む。
• 変更後は差分と確認結果を見る。返事だけで完成としない。
• MCP、プラグイン、遠隔アクセスは、必要になったときに一つずつ検討する。

このリストは、学び始めの範囲を小さくするためのものです。どんな攻撃にも耐える構成を保証するセキュリティ監査ではありません。重要なシステムへ進むときは、その環境に合う権限設計と検証を別に行います。

ここでは、実際に起動することを前提にせず、依頼の組立て方を練習します。将来自分で試すときは、導入、接続、費用、権限を先に確認してください。このワークフローは教材独自の案で、公式の成功保証つき手順ではありません。

準備：秘密のない、小さな題材を選びます

新しい練習用フォルダーを一つ用意し、架空の読書会やカフェを題材にします。実在する人の連絡先、会社の資料、APIキー、写真ライブラリーを持ち込まないようにします。完成物はローカルで開く index.html 一つ。登録、公開、データベース、外部APIは不要という範囲にします。

HTMLはページの構造、CSSは文字の大きさや色などの見た目、JavaScriptはボタンを押したときの動きなどを記述する言語です。最初に全部の文法を覚えなくても、どの部分を頼んでいるかを知っていると、確認しやすくなります。

手順1：まずは計画を、自分が理解できる言葉で

V2の /agents でPlanを選ぶ入口があります。通常のプロジェクト編集を抑える役割ですが、shellまで完全に止まる保証ではありません。将来試すときは、shellをaskまたはdenyにするなど実際の権限も確かめます。文章で「実行しないで」と書くことと、権限で止めることを分けます。

返ってきた計画を読んで、「何を一つ作るのか」「何を追加するのか」「費用や外部接続が増えないか」を確かめます。知らない言葉があれば、その言葉の意味と必要な理由を説明してもらいます。わからないまま次へ進む必要はありません。

手順2：Buildへ替え、ファイル一つだけ頼みます

計画が理解できたら、実装を担当するBuildへ切り替える場面です。「何でも追加して」とせず、一つのファイルと一つの動きに絞って頼みます。必要以上に大きなライブラリーや外部サービスを増やさない条件も役立ちます。

この依頼は、単に「素敵なページを」と言うより、完成の判断がしやすくなります。ファイルが一つ、内容が三つ、動きが一つ、外部読み込みなし。利用者自身も確認できます。

手順3：「できた」の後で、実物を見ます

指定したフォルダーにファイルがあるかを確認し、許可されたブラウザやプレビューで開きます。文字が読めるか、ボタンを押すと期待した文が出るか、画面を狭めたとき文章が切れないかを見ます。変更されたファイルの一覧と差分も確認します。

AIが「テスト済み」と言ったら、何をどう確かめたかを読みます。構文だけを調べたのか、実際に画面を開いたのか、ボタンを操作したのかで、確かめた範囲は違います。ブラウザのセキュリティ上の拒否や警告が出た場合は、解除して進めず、確認できた範囲とできなかった範囲を残します。

手順4：一つだけ変更し、前後を比べます

色だけの依頼なのに文章まで変わっていれば、範囲を超えた変更です。差分と画面で見分け、必要なら戻してもらいます。この小さな往復で、「依頼した範囲」「実際の変更」「確認結果」の関係を学べます。

気に入った版は別名のコピーなどで控えます。Gitに慣れたら、コミットで節目を保存する方法へ進めます。GitなしのフォルダーではOpenCodeのUndoでファイルが戻らないことを思い出してください。先に戻る場所を用意します。

次の学びは、一段ずつ増やします

一枚のページを理解できたら、次は指示をAGENTS.mdへ残す、変更履歴をGitで管理する、既存の確認方法を調べる、と進められます。MCP、プラグイン、複数エージェント、遠隔接続は、最初のページを作る条件ではありません。必要になった理由を説明できてから検討します。

仕事で使う場合は、練習と本番を分けます。本番の権限や秘密を追加する前に、データの扱い、レビュー、テスト、公開の判断、費用上限を組織の運用へ合わせる必要があります。小さな演習の成功だけで、大きな仕事を無確認で任せられるとは考えません。

似た言葉を一緒に覚えてしまうと、意図しない操作や費用につながります。気になる問いを開き、何と何を区別するかを確かめてください。

答えを先に開かず、一言で説明してみてください。用語のつづりより、どの役割を区別できるかを大切にします。間違えたときは、その章へ戻れば十分です。

ここでは、本文で出てきた言葉と、関連して目にする言葉を引けるようにまとめました。説明を丸暗記せず、困った言葉から該当する章へ戻ってください。

ファイル

名前を付けて保存した情報のまとまり。文章、写真、コードなどがあります。 本文へ →

フォルダー／ディレクトリ

ファイルや別のフォルダーをまとめる入れ物。 本文へ →

拡張子

ファイル名の末尾の.txtや.htmlなど、種類を見分ける手がかり。 本文へ →

パス

ファイルやフォルダーの場所を文字で表したもの。 本文へ →

相対パス／絶対パス

今の場所からの道順か、基準点からの住所かという違い。 本文へ →

プロジェクト

ひと仕事の材料と設定などのまとまり。 本文へ →

作業フォルダー／active directory

今回の操作の中心にする場所。指定だけで隔離されるわけではありません。 本文へ →

Git

ファイルの変更履歴を管理する道具。 本文へ →

GitHub／リポジトリ

GitHubはコードなどを置き共同作業するサービス。Gitのリポジトリは履歴を持つまとまりです。 本文へ →

コミット

意味のある変更の区切りをGitの履歴へ記録すること。 本文へ →

差分／diff

変更前と変更後の違い。 本文へ →

ターミナル

文字でコンピューターへ操作を伝えるための窓。 本文へ →

シェル／shell

命令を解釈して実行するプログラム。V2のツール・権限名にもshellを使います。 本文へ →

コマンド／引数

実行する命令と、その対象や条件として添える情報。 本文へ →

CLI／TUI

コマンドで操作する入口と、ターミナル内の一覧・入力欄などを持つ画面。 本文へ →

GUI／IDE

GUIはボタンやメニューなどの画面。IDEは編集・実行・診断などをまとめた開発用の作業場。 本文へ →

プロセス

動いているプログラムの単位。 本文へ →

クライアント／サーバー

依頼する窓口側と、それを受けて処理する裏方の役割。サーバーは手元にも置けます。 本文へ →

localhost

自分のコンピューター自身へ接続するための名前。 本文へ →

ローカル／リモート

手元側か、ネットワーク越しの別環境かという違い。どの部品を指すかも確認します。 本文へ →

AIモデル

渡された材料を処理し、返答や次の行動案を生成する部分。 本文へ →

プロバイダー

モデルへアクセスするサービスや接続先。 本文へ →

プロンプト

モデルへ渡す依頼や指示。コンテキストの一部。 本文へ →

コンテキスト

今回の判断のために渡す情報全体。会話、指示、資料、道具の説明や結果など。 本文へ →

コンテキストウィンドウ

モデルが一度に扱える文脈の大きさ。 本文へ →

トークン

AIが情報を処理・計量するときの単位。日本語の一文字や一語に固定対応しません。 本文へ →

API

ソフトウェア同士が機能を利用する入口や取り決め。 本文へ →

APIキー

API利用のアカウントなどを示す秘密の文字列。公開しません。 本文へ →

OAuth

サービス側の画面でログインし、接続を許可する方式。 本文へ →

ツール／function calling

ツールは読む・編集する等の道具。function callingはモデルの出力を機能の呼出しへつなぐ方式。 本文へ →

エージェント

道具と結果を使い、手順を進める仕組み。OpenCodeでは役割設定も指します。 本文へ →

セッション

一つの仕事について続く会話や状態のまとまり。 本文へ →

Build／Plan

実装を進める役割と、説明・調査・計画を先にする役割。Planは完全な隔離ではありません。 本文へ →

permissions

V2の権限設定。操作、対象、判定を順序付きのルールで扱います。 本文へ →

allow／ask／deny

自動続行、確認待ち、拒否という判定。 本文へ →

AGENTS.md

プロジェクトの心得や確認方法などを文章で渡す常設の指示。 本文へ →

Skills

必要なときに読む再利用可能な作業手順書。 本文へ →

Commands

よく使う依頼を呼び出すひな形。シェルを含む場合は実行内容にも注意します。 本文へ →

MCP

外部の道具や情報源と接続する共通の取り決め。安全性の保証書ではありません。 本文へ →

プラグイン

OpenCodeの動作へコードで機能を追加・調整する部品。 本文へ →

SDK／フレームワーク

開発に使う部品や入口、構造を提供する仕組み。実行ループを含むかは製品によります。 本文へ →

HTTPクライアント

HTTPという通信方式で、相手のAPIを使う側のプログラム。V2では@opencode/client。 本文へ →

埋め込みSDK

自分のアプリ内に実行部分を組み込む入口。V2では@opencode/sdk。 本文へ →

ACP

エージェントと対応クライアントを接続するための取り決め。初回演習には必須ではありません。 本文へ →

サブエージェント／subagent

子セッションで調査などを分担する仕組み。必要な背景を渡します。 本文へ →

オーケストレーション

作業の順序、分担、状態、終了判定などを調整すること。 本文へ →

ハーネス

モデルを仕事へつなぐ、入力・道具・結果・進行などの周辺の仕組み。用語の範囲は文脈で変わります。 本文へ →

内部／外部ハーネス

本教材の整理。OpenCodeの内側のセッション実行と、外側の仕事全体の制御を区別します。 本文へ →

Compaction

長い会話の古い部分を要約し、文脈の量を整理する仕組み。 本文へ →

LSP

言語の診断等をやり取りする仕組み。V2では設定を受け取っても実行しません。 本文へ →

lint／型チェック／テスト

よくあるミスの検査、データ種類の整合性、期待動作の確認。それぞれ確かめる範囲が違います。 本文へ →

ビルド／デプロイ

材料から動かせる形を作る工程と、利用環境へ配置する工程。 本文へ →

スナップショット

ある時点の対象ファイルの状態の記録。復元には条件があります。 本文へ →

サンドボックス／仮想マシン

操作できる範囲を制限する環境や、別のコンピューターのような実行環境。渡す資源も重要です。 本文へ →

Pair device

別端末をOpenCodeへ接続する機能。Desktopでは外部接続の有効化が関わります。 本文へ →

Console／Go

OpenCode側の任意のモデル利用・管理の入口とプラン。料金と条件は利用前に再確認します。 本文へ →

確認日は2026年10月15日です。公式文書と公開ソースを読んで整理しました。本文の工房の比喩、架空の読書会、図、演習の依頼文、内部／外部の境界は、本教材のための説明です。OpenCodeの公式分類名や、実機検証済みの成功手順ではありません。

何を根拠に、どこまで説明したか

不一致をどう扱ったか

権限の基本値とExploreのshell、Planの説明、旧Server modeの記述、GitHubのLatest表示などに、資料間の差が見られました。該当箇所は版を付けて説明し、既定値だけへ安全を預けない方針にしています。自動課金の既定値も断定せず、実際の設定確認へつなげました。

特にV1とV2で、npm名、権限名、SDK、Web接続、共有、LSP、認証保存が異なります。読み直す際は第13章の比較表と公式移行資料を確認してください。時間がたった後に使う場合、価格や機能をこのファイルだけで判断せず、公式情報へ戻ります。

実施していないこと

教材制作ではOpenCodeのインストール、起動、認証、APIキー取得、モデルの有料利用、権限追加、MCP・プラグイン導入、Pair deviceの有効化は行っていません。コードは読んだだけです。侵入試験や包括的な安全性監査でもありません。

一次資料の一覧

各章末にも関連する資料を折り畳んで付けています。以下は参照した入口と補足の一覧です。リンクを開くとインターネット接続が必要ですが、このページを保存すれば、本文、図、目次、回答はオフラインでも読めます。ソースのdevは将来内容が変わり得るため、固定版の確認と混同しないでください。

• OpenCode V2公式https://opencode.ai/v2/docs/
• ハーネスの機能的な定義https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents
• OpenCode V2 CLIhttps://opencode.ai/v2/docs/cli/
• V2 TUIhttps://opencode.ai/v2/docs/cli/tui/
• コンテキスト設計https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
• OpenCode V2 Modelshttps://opencode.ai/v2/docs/models/
• V2 Compactionhttps://opencode.ai/v2/docs/compaction/
• OpenCode V2 Providershttps://opencode.ai/v2/docs/providers/
• Consoleのモデルとプライバシーhttps://opencode.ai/v2/docs/console/models/#privacy
• ツール呼出しの仕組みhttps://developers.openai.com/api/docs/guides/function-calling
• 公式リポジトリhttps://github.com/anomalyco/opencode
• Agentshttps://opencode.ai/v2/docs/agents/
• 固定版Plan実装https://github.com/anomalyco/opencode/blob/v2.0.29/packages/core/src/plugin/plan.ts
• MITライセンスhttps://github.com/anomalyco/opencode/blob/v2.0.29/LICENSE
• V2 Toolshttps://opencode.ai/v2/docs/tools/
• 実行ステップの公開ソース・devhttps://github.com/anomalyco/opencode/blob/dev/packages/core/src/session/runner/step.ts
• セッション設計・devhttps://github.com/anomalyco/opencode/blob/dev/specs/v2/session.md
• OpenCodeの開発向け構成https://opencode.ai/v2/docs/build/
• 長時間作業のハーネスhttps://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
• ハーネスの設計事例https://openai.com/index/harness-engineering/
• OpenCodeの安全境界https://github.com/anomalyco/opencode/blob/v2.0.29/SECURITY.md
• Permissionshttps://opencode.ai/v2/docs/permissions/
• 受付実装・devhttps://github.com/anomalyco/opencode/blob/dev/packages/core/src/session/session.ts
• 要求組立て・devhttps://github.com/anomalyco/opencode/blob/dev/packages/core/src/session/model-request.ts
• 実行制御・devhttps://github.com/anomalyco/opencode/blob/dev/packages/core/src/session/execution.ts
• V2 Confighttps://opencode.ai/v2/docs/config/
• Instructionshttps://opencode.ai/v2/docs/instructions/
• Skillshttps://opencode.ai/v2/docs/skills/
• Commandsのshell警告https://opencode.ai/v2/docs/commands/#shell
• MCPhttps://opencode.ai/v2/docs/mcp-servers/
• Pluginshttps://opencode.ai/v2/docs/plugins/
• HTTP Clienthttps://opencode.ai/v2/docs/build/client/
• 埋め込みSDKhttps://opencode.ai/v2/docs/build/sdk/
• 拡張APIhttps://opencode.ai/v2/docs/build/plugins/
• 子の実装・devhttps://github.com/anomalyco/opencode/blob/dev/packages/core/src/tool/plugin/subagent.ts
• 固定版のAgent基本設定https://github.com/anomalyco/opencode/blob/v2.0.29/packages/schema/src/agent.ts
• Claude Agent SDKhttps://code.claude.com/docs/en/agent-sdk/overview
• V1からの移行https://opencode.ai/v2/docs/migrate-v1/
• V1公式・比較用https://opencode.ai/docs/
• 変更履歴https://opencode.ai/changelog
• GitHub Releaseshttps://github.com/anomalyco/opencode/releases
• Mac Downloadhttps://opencode.ai/download
• TUIの接続https://opencode.ai/v2/docs/cli/providers/
• V2 Webhttps://opencode.ai/v2/docs/cli/web/
• ACPhttps://opencode.ai/v2/docs/cli/acp/
• 権限とディレクトリhttps://opencode.ai/v2/docs/permissions/#directories
• 権限判定https://github.com/anomalyco/opencode/blob/v2.0.29/packages/core/src/permission.ts
• 保存済み許可https://github.com/anomalyco/opencode/blob/v2.0.29/packages/core/src/permission/saved.ts
• 認証値https://github.com/anomalyco/opencode/blob/v2.0.29/packages/core/src/credential.ts
• 認証保存https://github.com/anomalyco/opencode/blob/v2.0.29/packages/core/src/credential/sql.ts
• DB実装https://github.com/anomalyco/opencode/blob/v2.0.29/packages/core/src/database/database.ts
• Pair device実装https://github.com/anomalyco/opencode/blob/v2.0.29/packages/gui-extensions/src/pairing/page.tsx
• 認証の実装https://github.com/anomalyco/opencode/blob/v2.0.29/packages/server/src/auth.ts
• ペアリング実装https://github.com/anomalyco/opencode/blob/v2.0.29/packages/server/src/pairing.ts
• Sharinghttps://opencode.ai/v2/docs/sharing/
• Snapshotshttps://opencode.ai/v2/docs/snapshots/
• Snapshot実装https://github.com/anomalyco/opencode/blob/v2.0.29/packages/core/src/snapshot.ts
• 戻す処理https://github.com/anomalyco/opencode/blob/v2.0.29/packages/core/src/session/revert.ts
• Console Billinghttps://opencode.ai/v2/docs/console/billing/
• Budgetshttps://opencode.ai/v2/docs/console/budgets/
• Gohttps://opencode.ai/v2/docs/console/go/
• 自動継続実装https://github.com/anomalyco/opencode/blob/v2.0.29/packages/core/src/session/runner/llm.ts
• 費用集計実装https://github.com/anomalyco/opencode/blob/v2.0.29/packages/client/src/solid/data.ts
• Troubleshootinghttps://opencode.ai/v2/docs/troubleshooting/

わからないことが残ったとき

操作や接続で困ったときは、使っている版、起きたこと、期待したこと、実施した確認をまとめ、公式のTroubleshootingへ進みます。公開の相談にログや画面を添付する前に、認証情報と個人情報を取り除きます。いきなりDBや設定を削除して原因を失わないようにします。

学習の途中なら、「今、モデル・道具・権限・環境・確認のどこで迷っているか」を言葉にすると、質問が具体的になります。全部を一度に覚えず、自分が扱える小さな仕事を一つずつ増やしてください。

関連する教材

• ハーネスとは何か：ハーネスという考え方そのものを、AIの職場づくりのたとえで説明した入門です。
• OpenCode完全理解マニュアル：MacでOpenCodeを導入し、権限や料金を設定して実際に使う手順を全36章でたどります。
• はじめてのAI開発室：OpenCodeをOpenRouter経由で低価格のモデルにつなぎ、最初の作品を作るまでの超入門です。