diff --git a/blog/asset-sources/route-cursor-through-token-station-cover.svg b/blog/asset-sources/route-cursor-through-token-station-cover.svg new file mode 100644 index 0000000..0587a11 --- /dev/null +++ b/blog/asset-sources/route-cursor-through-token-station-cover.svg @@ -0,0 +1,70 @@ + + route-cursor-through-token-station-cover + + + + + + + + + + + + + + + + + + + + + + CURSOR · TOKEN STATION · SETUP + + Cursor, + wired in. + Sol, Terra, Luna: custom models. + + + + + OVERRIDE OPENAI BASE URL + + https://models.bytefuture.ai/v1 + + CUSTOM MODELS ADDED + + + + + openai/gpt-5.6-sol + + + + + openai/gpt-5.6-terra + + + + + openai/gpt-5.6-luna + + + + Cursor + + + Token Station + + + + + + + + ByteFuture + diff --git a/blog/route-cursor-through-token-station-cover.png b/blog/route-cursor-through-token-station-cover.png new file mode 100644 index 0000000..e9ada15 Binary files /dev/null and b/blog/route-cursor-through-token-station-cover.png differ diff --git a/blog/route-cursor-through-token-station/add-models.mp4 b/blog/route-cursor-through-token-station/add-models.mp4 new file mode 100644 index 0000000..46f70e8 Binary files /dev/null and b/blog/route-cursor-through-token-station/add-models.mp4 differ diff --git a/blog/route-cursor-through-token-station/register-provider.mp4 b/blog/route-cursor-through-token-station/register-provider.mp4 new file mode 100644 index 0000000..ce7fbd5 Binary files /dev/null and b/blog/route-cursor-through-token-station/register-provider.mp4 differ diff --git a/blog/route-cursor-through-token-station/subagents.mp4 b/blog/route-cursor-through-token-station/subagents.mp4 new file mode 100644 index 0000000..e609a09 Binary files /dev/null and b/blog/route-cursor-through-token-station/subagents.mp4 differ diff --git a/sitemap.xml b/sitemap.xml index bb825e5..97b67a8 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -305,4 +305,24 @@ 2026-08-08 0.6 + + https://bytefuture.ai/blog/route-cursor-through-token-station.html + 2026-08-13 + 0.7 + + + https://bytefuture.ai/blog/route-cursor-through-token-station-zh.html + 2026-08-13 + 0.6 + + + https://bytefuture.ai/blog/route-cursor-through-token-station-ja.html + 2026-08-13 + 0.6 + + + https://bytefuture.ai/blog/route-cursor-through-token-station-ko.html + 2026-08-13 + 0.6 + diff --git a/src/content/writings/en/route-cursor-through-token-station.md b/src/content/writings/en/route-cursor-through-token-station.md new file mode 100644 index 0000000..e41f6ea --- /dev/null +++ b/src/content/writings/en/route-cursor-through-token-station.md @@ -0,0 +1,122 @@ +--- +slug: "route-cursor-through-token-station" +lang: "en" +title: "Route Cursor through Token Station: GPT-5.6 Sol, Terra, and Luna" +summary: "Cursor supports custom OpenAI-compatible providers through Settings, Models. Point it at Token Station and Sol, Terra, and Luna show up as selectable models, with two known gotchas: a Tab-focus workaround for a current input-field bug, and the openai/ prefix Token Station's routes actually need." +category: "tutorial" +date: "2026-08-13" +cta: "https://models.bytefuture.ai/intro.html" +cover: "blog/route-cursor-through-token-station-cover.png" +draft: false +--- + +Cursor supports custom OpenAI-compatible providers through Settings → Models. Point it at Token Station's endpoint and you can add GPT-5.6's three named routes, Sol, Terra, and Luna, as selectable models, each billed through your own Token Station key. This walks through the setup end to end, including two gotchas we hit doing it ourselves: a current Cursor input-field bug, and a model-naming detail that silently breaks requests if you skip it. + +## What you need before starting + +- Cursor installed ([cursor.com/download](https://cursor.com/download)). +- A Token Station account and API key. Sign up free at [models.bytefuture.ai](https://models.bytefuture.ai): $1 in credit on registration, no card required. +- Cursor Pro. Custom-model selection in Agent mode is gated on the Free plan, even with your own API key, so you'll need Pro ($20/month) for anything past Chat mode. + +## Step 1: Register Token Station as a custom provider + +Open **Settings → Cursor Settings → Models**, scroll to **API Keys**, and set two fields: + +- **OpenAI API Key**: your Token Station key. +- **Override OpenAI Base URL**: toggle it on, and replace the default with `https://models.bytefuture.ai/v1`. + +
+ +
Registering Token Station as a custom OpenAI-compatible provider in Cursor's Models settings.
+
+ +**Known bug worth knowing about**: in current Cursor builds (3.15.x), these two fields sometimes don't accept keyboard input on click. If typing does nothing, click elsewhere in the panel first, then press **Tab** repeatedly until focus lands on the field. Typing and **Ctrl+V** paste both work once it's Tab-focused. This is an acknowledged regression, not something specific to your setup. + +Don't rely on a "Verify" button to confirm the key and URL are correct. It isn't always present, and even when it is, it doesn't cover every path. The reliable check is Step 2: add a model and actually send it a message. + +## Step 2: Add the three GPT-5.6 routes as custom models + +Still in Models settings, click **+ Add Custom Model** three times and add: + +``` +openai/gpt-5.6-sol +openai/gpt-5.6-terra +openai/gpt-5.6-luna +``` + +
+ +
Adding openai/gpt-5.6-sol, openai/gpt-5.6-terra, and openai/gpt-5.6-luna as custom models.
+
+ +**The gotcha**: Cursor sends whatever name you register here verbatim as the `model` field in its request. Token Station's actual route names include the `openai/` prefix. Register the model as plain `gpt-5.6-sol` and every request fails with `Model 'gpt-5.6-sol' not found`, because that model genuinely doesn't exist without the prefix. Register it with the prefix and it works immediately. + +To confirm it's actually working end to end, not just accepted by Cursor: open a chat, select one of the new models, send a trivial message, and check the [Token Station dashboard](https://models.bytefuture.ai/dashboard). A real reply plus a matching line in Recent Activity means the key, base URL, and model name are all correct. + +| Model | Good for | +|---|---| +| `openai/gpt-5.6-sol` | Flagship route for hard planning, debugging, and architecture questions. | +| `openai/gpt-5.6-terra` | Middle tier for repeated implementation and debugging discussion. | +| `openai/gpt-5.6-luna` | Lower-cost route for exploration, triage, and quick questions. | + +## Step 3: Define Luna-backed subagents + +Cursor supports subagents: markdown files with YAML frontmatter, defined per-project in `.cursor/agents/` or globally in `~/.cursor/agents/`, each with its own `model` field. That lets you point specific, narrowly-scoped delegations at a cheaper model than whatever your main chat is using. + +Two useful roles for a coding session, both on Luna: + +**`.cursor/agents/explore.md`** +```markdown +--- +name: explore +description: Searches and reads the codebase to answer questions about existing code. Use proactively before implementing anything unfamiliar. +model: openai/gpt-5.6-luna +readonly: true +--- + +You are a fast, read-only research agent. Find and summarize relevant +files, functions, and patterns. Never edit files or run mutating commands. +``` + +**`.cursor/agents/test-runner.md`** +```markdown +--- +name: test-runner +description: Runs the test suite and reports pass/fail results with failure details. Use proactively after any code change. +model: openai/gpt-5.6-luna +--- + +You run the project's test command, capture output, and report which +tests passed or failed and why. Do not modify source files. +``` + +
+ +
Creating the explore and test-runner subagents, both backed by openai/gpt-5.6-luna.
+
+ +`readonly: true` on `explore` blocks file edits and state-changing shell commands, which fits a pure research role. `test-runner` needs to actually execute the test command, so it's left without that restriction, with its instructions telling it not to touch source files. + +Two ways to trigger a subagent in chat: automatic delegation, where the main agent reads the `description` field and decides on its own when to hand off, or explicit invocation with `/explore` or `/test-runner`. + +If you create these files by asking the agent in chat to write them rather than doing it from a terminal, and the sidebar still shows no subagents afterward, reload the window (**Ctrl+Shift+P → "Reload Window"**): Cursor doesn't always rescan `.cursor/agents/` live. + +## What works today, and what doesn't yet + +Chat and Ask mode with Sol, Terra, and Luna work as described above: real replies, correctly billed to your Token Station key, visible on the dashboard. + +Full Agent-mode autonomy, the model reading your codebase and writing changes directly, is a different story. In our testing, custom OpenAI-compatible models added through Override Base URL could read and discuss code in Agent mode, but consistently failed to apply any actual file edit, regardless of which Cursor mode we tried. That matches reports from other users hitting the same wall: Cursor's Agent tool-calling harness expects a specific request and response shape, and a standard OpenAI-compatible endpoint isn't guaranteed to round-trip it the way Cursor's own hosted models do. This isn't a Token Station-specific issue: the same `openai/gpt-5.6-*` routes already drive real agentic tool-calling in Codex, so the model and the endpoint aren't the limiting factor here. + +If your workflow needs an agent that actually edits files, Token Station's Codex, Claude Code, and OpenClaw integrations are the proven path today. Cursor is a solid way to chat with Sol, Terra, and Luna inside your editor, with cost-tiered subagents for chat-based delegation, while its BYOK Agent-mode support catches up. + +## Get started + +Sign up at [models.bytefuture.ai](https://models.bytefuture.ai/signup): $1 in free credit, no card required, with up to $50 in bonus credit on your first top-up. Export your key, wire it into Cursor's Models settings, and add the three routes. + +[Try Token Station](https://models.bytefuture.ai/intro.html) diff --git a/src/content/writings/ja/route-cursor-through-token-station.md b/src/content/writings/ja/route-cursor-through-token-station.md new file mode 100644 index 0000000..508c471 --- /dev/null +++ b/src/content/writings/ja/route-cursor-through-token-station.md @@ -0,0 +1,122 @@ +--- +slug: "route-cursor-through-token-station" +lang: "ja" +title: "Cursor を Token Station に接続する:GPT-5.6 の Sol、Terra、Luna" +summary: "Cursor は Settings の Models パネルからカスタム OpenAI 互換プロバイダーに対応している。Token Station を指定すれば Sol、Terra、Luna が選択可能なモデルとして現れるが、注意点が二つある。現行バージョンの入力欄のバグに対する Tab フォーカスの回避策と、Token Station のルートが実際に必要とする openai/ プレフィックスだ。" +category: "tutorial" +date: "2026-08-13" +cta: "https://models.bytefuture.ai/intro.html" +cover: "blog/route-cursor-through-token-station-cover.png" +draft: false +--- + +Cursor は Settings → Models からカスタム OpenAI 互換プロバイダーに対応している。Token Station のエンドポイントを指定すれば、GPT-5.6 の三つの名前付きルート、Sol、Terra、Luna を選択可能なモデルとして追加でき、すべて自分の Token Station キーで課金される。ここでは設定を最初から最後まで説明する。実際にやってみて遭遇した二つの落とし穴、現行 Cursor の入力欄バグと、省略すると静かにリクエストが壊れるモデル命名の細部も含めて。 + +## 始める前に必要なもの + +- Cursor がインストール済みであること([cursor.com/download](https://cursor.com/download))。 +- Token Station のアカウントと API キー。[models.bytefuture.ai](https://models.bytefuture.ai) から無料登録できる。登録時に 1 ドル分のクレジットが付与され、クレジットカードは不要。 +- Cursor Pro。Agent モードでのカスタムモデル選択は、自分の API キーを設定していても無料プランではロックされているため、Chat モード以外の用途にはすべて Pro(月額 20 ドル)が必要になる。 + +## ステップ 1:Token Station をカスタムプロバイダーとして登録する + +**Settings → Cursor Settings → Models** を開き、**API Keys** までスクロールして、二つのフィールドを設定する。 + +- **OpenAI API Key**:Token Station のキーを入力する。 +- **Override OpenAI Base URL**:トグルをオンにし、デフォルト値を `https://models.bytefuture.ai/v1` に置き換える。 + +
+ +
Cursor の Models 設定で、Token Station をカスタム OpenAI 互換プロバイダーとして登録する。
+
+ +**知っておくべき既知のバグ**:現行の Cursor(3.15.x 系)では、この二つのフィールドがクリックしてもキーボード入力を受け付けないことがある。入力しても何も起きない場合は、まずパネル内の別の場所をクリックし、その後 **Tab** キーを繰り返し押してフォーカスを対象フィールドに移す。Tab でフォーカスが当たった後は、入力も **Ctrl+V** による貼り付けも問題なく動作する。これは公式に認められているリグレッションであり、あなたの環境固有の問題ではない。 + +キーとURLが正しいことの確認を「Verify」ボタンに頼らないこと。常に表示されるわけではなく、表示されていてもすべての経路をカバーしているわけではない。信頼できる確認方法はステップ 2 だ。モデルを追加して、実際にメッセージを送ってみる。 + +## ステップ 2:三つの GPT-5.6 ルートをカスタムモデルとして追加する + +引き続き Models の設定で、**+ Add Custom Model** を三回クリックし、次を追加する。 + +``` +openai/gpt-5.6-sol +openai/gpt-5.6-terra +openai/gpt-5.6-luna +``` + +
+ +
openai/gpt-5.6-sol、openai/gpt-5.6-terra、openai/gpt-5.6-luna をカスタムモデルとして追加する。
+
+ +**ここが落とし穴**:ここで登録した名前を、Cursor はそのままリクエストの `model` フィールドとして送信する。Token Station の実際のルート名には `openai/` プレフィックスが含まれる。プレフィックスなしの `gpt-5.6-sol` として登録すると、すべてのリクエストが `Model 'gpt-5.6-sol' not found` というエラーで失敗する。プレフィックスなしのそのモデルは実際に存在しないからだ。プレフィックス付きで登録すればすぐに動作する。 + +Cursor に受け付けられただけでなく実際にエンドツーエンドで動作していることを確認するには、チャットを開いて新しく追加したモデルのどれかを選び、適当なメッセージを送り、[Token Station のダッシュボード](https://models.bytefuture.ai/dashboard)を確認する。実際の返信があり、Recent Activity に対応する行が現れていれば、キー、ベース URL、モデル名のすべてが正しいということだ。 + +| モデル | 向いている用途 | +|---|---| +| `openai/gpt-5.6-sol` | フラッグシップルート。難しいプランニング、デバッグ、アーキテクチャに関する質問に。 | +| `openai/gpt-5.6-terra` | 中間ティア。反復的な実装やデバッグの相談に。 | +| `openai/gpt-5.6-luna` | 低コストルート。探索、トリアージ、ちょっとした質問に。 | + +## ステップ 3:Luna を使うサブエージェントを定義する + +Cursor はサブエージェントに対応している。YAML フロントマター付きの markdown ファイルで、プロジェクトごとに `.cursor/agents/` に置くか、グローバルに `~/.cursor/agents/` に置くことができ、それぞれが独自の `model` フィールドを持つ。これにより、特定の範囲が明確なタスクの委任先を、メインのチャットより安いモデルに向けられる。 + +コーディングセッションで有用な二つの役割を、どちらも Luna で構成する。 + +**`.cursor/agents/explore.md`** +```markdown +--- +name: explore +description: Searches and reads the codebase to answer questions about existing code. Use proactively before implementing anything unfamiliar. +model: openai/gpt-5.6-luna +readonly: true +--- + +You are a fast, read-only research agent. Find and summarize relevant +files, functions, and patterns. Never edit files or run mutating commands. +``` + +**`.cursor/agents/test-runner.md`** +```markdown +--- +name: test-runner +description: Runs the test suite and reports pass/fail results with failure details. Use proactively after any code change. +model: openai/gpt-5.6-luna +--- + +You run the project's test command, capture output, and report which +tests passed or failed and why. Do not modify source files. +``` + +
+ +
explore と test-runner の二つのサブエージェントを作成する。どちらも openai/gpt-5.6-luna を使用。
+
+ +`explore` の `readonly: true` はファイル編集と状態を変更するシェルコマンドをブロックする。純粋な研究役にはこれが合っている。`test-runner` はテストコマンドを実際に実行する必要があるため、この制限は付けず、代わりに指示の中でソースファイルに触れないよう指定している。 + +チャットでサブエージェントを起動する方法は二つある。自動委任では、メインエージェントが `description` フィールドを読み、いつ委任するかを自分で判断する。もう一つは `/explore` や `/test-runner` による明示的な呼び出しだ。 + +これらのファイルを、自分でターミナルから書く代わりにチャットでエージェントに書かせた場合、サイドバーに依然としてサブエージェントが表示されないなら、ウィンドウをリロードする(**Ctrl+Shift+P → "Reload Window"**)。Cursor は常にライブで `.cursor/agents/` を再スキャンするわけではない。 + +## 今できること、まだできないこと + +Chat モードと Ask モードで Sol、Terra、Luna を使う分には、上に書いた通り動作する。実際の返信があり、正しく Token Station のキーに課金され、ダッシュボードにも表示される。 + +一方、完全な Agent モードの自律性、つまりモデルが自分でコードベースを読み、変更を直接書き込む部分は話が別だ。私たちのテストでは、Override Base URL 経由で追加したカスタム OpenAI 互換モデルは、Agent モードでコードを読み議論することはできたが、どの Cursor モードを試しても実際のファイル編集を適用することは一貫してできなかった。これは同じ壁にぶつかっている他のユーザーの報告とも一致する。Cursor の Agent ツール呼び出しの仕組みは特定のリクエストとレスポンスの形を期待しており、標準的な OpenAI 互換エンドポイントが Cursor 自身がホストするモデルと同じようにその形を正しくやり取りできる保証はない。これは Token Station 固有の問題ではない。同じ `openai/gpt-5.6-*` ルートは、Codex ではすでに実際の agentic なツール呼び出しを動かしており、モデルやエンドポイント自体がここでのボトルネックではないからだ。 + +実際にファイルを編集できるエージェントがワークフローに必要なら、Token Station の Codex、Claude Code、OpenClaw との連携が現時点で実証済みの選択肢だ。Cursor の BYOK による Agent モード対応が追いつくまでは、Cursor はエディタの中で Sol、Terra、Luna とチャットし、コスト階層の異なるサブエージェントでチャットベースの委任を行うための、堅実な手段だと言える。 + +## はじめよう + +[models.bytefuture.ai](https://models.bytefuture.ai/signup) で登録する。1 ドル分の無料クレジット、クレジットカード不要。初回チャージで最大 50 ドルのボーナスも付く。キーをエクスポートし、Cursor の Models 設定に接続し、三つのルートを追加しよう。 + +[Token Station を試す](https://models.bytefuture.ai/intro.html) diff --git a/src/content/writings/ko/route-cursor-through-token-station.md b/src/content/writings/ko/route-cursor-through-token-station.md new file mode 100644 index 0000000..ae22832 --- /dev/null +++ b/src/content/writings/ko/route-cursor-through-token-station.md @@ -0,0 +1,122 @@ +--- +slug: "route-cursor-through-token-station" +lang: "ko" +title: "Cursor를 Token Station에 연결하기: GPT-5.6의 Sol, Terra, Luna" +summary: "Cursor는 Settings의 Models 패널에서 커스텀 OpenAI 호환 프로바이더를 지원한다. Token Station을 지정하면 Sol, Terra, Luna가 선택 가능한 모델로 나타나지만, 알아둘 문제가 두 가지 있다. 현재 버전 입력창 버그에 대한 Tab 포커스 우회법과, Token Station 라우트가 실제로 필요로 하는 openai/ 접두사다." +category: "tutorial" +date: "2026-08-13" +cta: "https://models.bytefuture.ai/intro.html" +cover: "blog/route-cursor-through-token-station-cover.png" +draft: false +--- + +Cursor는 Settings → Models에서 커스텀 OpenAI 호환 프로바이더를 지원한다. Token Station의 엔드포인트를 지정하면 GPT-5.6의 세 가지 명명된 라우트인 Sol, Terra, Luna를 선택 가능한 모델로 추가할 수 있고, 모두 자신의 Token Station 키로 과금된다. 여기서는 설정 과정을 처음부터 끝까지 다룬다. 직접 해보면서 만난 두 가지 문제, 즉 현재 Cursor의 입력창 버그와 건너뛰면 조용히 요청을 실패시키는 모델 이름 규칙까지 포함해서다. + +## 시작하기 전에 필요한 것 + +- Cursor 설치([cursor.com/download](https://cursor.com/download)). +- Token Station 계정과 API 키. [models.bytefuture.ai](https://models.bytefuture.ai)에서 무료로 가입할 수 있다. 가입 시 1달러 크레딧이 지급되며 카드는 필요 없다. +- Cursor Pro. Agent 모드에서의 커스텀 모델 선택은 자신의 API 키가 있어도 무료 플랜에서는 막혀 있어서, Chat 모드를 넘어서는 모든 용도에 Pro(월 20달러)가 필요하다. + +## 1단계: Token Station을 커스텀 프로바이더로 등록하기 + +**Settings → Cursor Settings → Models**를 열고 **API Keys**까지 스크롤한 다음, 두 필드를 설정한다. + +- **OpenAI API Key**: Token Station 키를 입력한다. +- **Override OpenAI Base URL**: 토글을 켜고, 기본값을 `https://models.bytefuture.ai/v1`로 바꾼다. + +
+ +
Cursor의 Models 설정에서 Token Station을 커스텀 OpenAI 호환 프로바이더로 등록하는 과정.
+
+ +**알아두면 좋은 알려진 버그**: 현재 Cursor 빌드(3.15.x 계열)에서는 이 두 필드가 클릭해도 키보드 입력을 받지 않을 때가 있다. 입력해도 아무 반응이 없다면, 먼저 패널의 다른 부분을 클릭한 다음 **Tab** 키를 반복해서 눌러 포커스가 해당 필드로 오게 한다. Tab으로 포커스가 온 뒤에는 입력과 **Ctrl+V** 붙여넣기 모두 정상 작동한다. 이는 공식적으로 인정된 회귀 버그이며, 특정 사용자 환경의 문제가 아니다. + +키와 URL이 올바른지 확인할 때 "Verify" 버튼에 의존하지 말자. 항상 나타나는 것도 아니고, 나타나더라도 모든 경로를 커버하지는 않는다. 믿을 만한 확인 방법은 2단계다: 모델을 추가하고 실제로 메시지를 보내보는 것. + +## 2단계: 세 가지 GPT-5.6 라우트를 커스텀 모델로 추가하기 + +여전히 Models 설정에서, **+ Add Custom Model**을 세 번 클릭해 다음을 추가한다. + +``` +openai/gpt-5.6-sol +openai/gpt-5.6-terra +openai/gpt-5.6-luna +``` + +
+ +
openai/gpt-5.6-sol, openai/gpt-5.6-terra, openai/gpt-5.6-luna를 커스텀 모델로 추가하는 과정.
+
+ +**여기가 함정이다**: 여기서 등록한 이름을 Cursor는 그대로 요청의 `model` 필드로 보낸다. Token Station의 실제 라우트 이름에는 `openai/` 접두사가 붙어 있다. 접두사 없이 `gpt-5.6-sol`로 등록하면 모든 요청이 `Model 'gpt-5.6-sol' not found` 오류로 실패하는데, 접두사가 없는 그 모델은 실제로 존재하지 않기 때문이다. 접두사를 붙여 등록하면 바로 작동한다. + +Cursor에 받아들여진 것뿐 아니라 실제로 엔드투엔드로 작동하는지 확인하려면, 채팅을 열어 새로 추가한 모델 중 하나를 선택하고 아무 메시지나 보낸 다음 [Token Station 대시보드](https://models.bytefuture.ai/dashboard)를 확인한다. 실제 응답과 함께 Recent Activity에 해당하는 항목이 나타난다면, 키와 base URL, 모델 이름이 모두 올바르다는 뜻이다. + +| 모델 | 적합한 용도 | +|---|---| +| `openai/gpt-5.6-sol` | 플래그십 라우트. 어려운 플래닝, 디버깅, 아키텍처 관련 질문에. | +| `openai/gpt-5.6-terra` | 중간 등급. 반복적인 구현과 디버깅 논의에. | +| `openai/gpt-5.6-luna` | 저비용 라우트. 탐색, 우선순위 판단, 간단한 질문에. | + +## 3단계: Luna 기반 서브에이전트 정의하기 + +Cursor는 서브에이전트를 지원한다. YAML 프론트매터가 있는 마크다운 파일로, 프로젝트별로 `.cursor/agents/`에 두거나 전역으로 `~/.cursor/agents/`에 둘 수 있으며, 각각 자체 `model` 필드를 가진다. 이를 통해 범위가 명확한 특정 위임 작업을 메인 채팅보다 저렴한 모델로 향하게 할 수 있다. + +코딩 세션에 유용한 두 가지 역할을, 둘 다 Luna로 구성한다. + +**`.cursor/agents/explore.md`** +```markdown +--- +name: explore +description: Searches and reads the codebase to answer questions about existing code. Use proactively before implementing anything unfamiliar. +model: openai/gpt-5.6-luna +readonly: true +--- + +You are a fast, read-only research agent. Find and summarize relevant +files, functions, and patterns. Never edit files or run mutating commands. +``` + +**`.cursor/agents/test-runner.md`** +```markdown +--- +name: test-runner +description: Runs the test suite and reports pass/fail results with failure details. Use proactively after any code change. +model: openai/gpt-5.6-luna +--- + +You run the project's test command, capture output, and report which +tests passed or failed and why. Do not modify source files. +``` + +
+ +
explore와 test-runner 두 서브에이전트를 만드는 과정. 둘 다 openai/gpt-5.6-luna를 사용한다.
+
+ +`explore`의 `readonly: true`는 파일 편집과 상태를 변경하는 셸 명령을 막는데, 순수 조사 역할에 딱 맞는다. `test-runner`는 테스트 명령을 실제로 실행해야 하므로 이 제한을 두지 않았고, 대신 지시문에서 소스 파일을 건드리지 말라고 명시했다. + +채팅에서 서브에이전트를 실행하는 방법은 두 가지다. 자동 위임은 메인 에이전트가 `description` 필드를 읽고 언제 위임할지 스스로 판단하는 방식이고, `/explore`나 `/test-runner`로 명시적으로 호출하는 방법도 있다. + +이 파일들을 터미널에서 직접 만드는 대신 채팅에서 에이전트에게 작성해달라고 요청했는데도 사이드바에 여전히 서브에이전트가 표시되지 않는다면, 창을 새로고침한다(**Ctrl+Shift+P → "Reload Window"**). Cursor가 `.cursor/agents/`를 항상 실시간으로 다시 스캔하지는 않는다. + +## 지금 되는 것과 아직 안 되는 것 + +Chat 모드와 Ask 모드에서 Sol, Terra, Luna를 쓰는 것은 위에서 설명한 대로 작동한다. 실제 응답이 오고, Token Station 키에 정확히 과금되며, 대시보드에서도 확인된다. + +완전한 Agent 모드의 자율성, 즉 모델이 직접 코드베이스를 읽고 변경 사항을 써넣는 부분은 이야기가 다르다. 우리의 테스트에서는, Override Base URL을 통해 추가한 커스텀 OpenAI 호환 모델이 Agent 모드에서 코드를 읽고 논의할 수는 있었지만, 어떤 Cursor 모드를 시도하든 실제 파일 편집을 적용하는 데는 일관되게 실패했다. 이는 같은 벽에 부딪힌 다른 사용자들의 보고와도 일치한다. Cursor의 Agent 도구 호출 체계는 특정한 요청과 응답 형식을 기대하는데, 표준 OpenAI 호환 엔드포인트가 Cursor 자체 호스팅 모델과 똑같이 그 형식을 주고받는다는 보장은 없다. 이는 Token Station만의 문제가 아니다. 같은 `openai/gpt-5.6-*` 라우트가 Codex에서는 이미 실제 agentic 도구 호출을 구동하고 있으므로, 모델이나 엔드포인트 자체가 병목은 아니다. + +실제로 파일을 편집하는 에이전트가 워크플로에 필요하다면, Token Station의 Codex, Claude Code, OpenClaw 연동이 현재 검증된 방법이다. Cursor의 BYOK Agent 모드 지원이 따라잡을 때까지는, Cursor는 에디터 안에서 Sol, Terra, Luna와 대화하고 비용 등급이 다른 서브에이전트로 채팅 기반 위임을 하기에 좋은 방법이다. + +## 시작하기 + +[models.bytefuture.ai](https://models.bytefuture.ai/signup)에서 가입하자. 1달러 무료 크레딧, 카드 불필요, 첫 충전 시 최대 50달러 보너스도 받을 수 있다. 키를 export하고 Cursor의 Models 설정에 연결한 다음, 세 가지 라우트를 추가하자. + +[Token Station 사용해보기](https://models.bytefuture.ai/intro.html) diff --git a/src/content/writings/zh/route-cursor-through-token-station.md b/src/content/writings/zh/route-cursor-through-token-station.md new file mode 100644 index 0000000..b8e3ebc --- /dev/null +++ b/src/content/writings/zh/route-cursor-through-token-station.md @@ -0,0 +1,122 @@ +--- +slug: "route-cursor-through-token-station" +lang: "zh" +title: "在 Cursor 中接入 Token Station:GPT-5.6 的 Sol、Terra 和 Luna" +summary: "Cursor 在设置里的 Models 面板支持自定义 OpenAI 兼容 provider。把它指向 Token Station,Sol、Terra、Luna 就会作为可选模型出现,但有两个坑要注意:一个是当前版本输入框的 Tab 聚焦变通方法,另一个是 Token Station 路由实际需要的 openai/ 前缀。" +category: "tutorial" +date: "2026-08-13" +cta: "https://models.bytefuture.ai/intro.html" +cover: "blog/route-cursor-through-token-station-cover.png" +draft: false +--- + +Cursor 在 Settings → Models 里支持自定义 OpenAI 兼容 provider。把它指向 Token Station 的端点,就能把 GPT-5.6 的三个命名路由,Sol、Terra、Luna,添加为可选模型,全部通过你自己的 Token Station key 计费。下面是完整的配置流程,包括我们自己踩过的两个坑:一个是 Cursor 当前版本的输入框 bug,另一个是模型命名上一个不注意就会让请求全部失败的细节。 + +## 开始之前需要准备什么 + +- 已安装 Cursor([cursor.com/download](https://cursor.com/download))。 +- 一个 Token Station 账户和 API 密钥。免费注册:[models.bytefuture.ai](https://models.bytefuture.ai),注册即送 1 美元额度,无需信用卡。 +- Cursor Pro。免费版即使填了自己的 API key,Agent 模式下的自定义模型选择依然是锁死的,所以除了 Chat 模式之外的任何用法都需要 Pro(每月 20 美元)。 + +## 步骤 1:将 Token Station 注册为自定义 provider + +打开 **Settings → Cursor Settings → Models**,滚动到 **API Keys**,设置两个字段: + +- **OpenAI API Key**:填入你的 Token Station 密钥。 +- **Override OpenAI Base URL**:打开开关,把默认值替换成 `https://models.bytefuture.ai/v1`。 + +
+ +
在 Cursor 的 Models 设置里,把 Token Station 注册为自定义 OpenAI 兼容 provider。
+
+ +**值得了解的已知 bug**:在当前的 Cursor 版本(3.15.x)中,这两个字段有时点击后无法接受键盘输入。如果打字没反应,先点一下面板里的其他地方,然后连续按 **Tab** 键,直到焦点落在目标字段上。一旦通过 Tab 聚焦,打字和 **Ctrl+V** 粘贴都能正常工作。这是一个官方承认的回归问题,不是你的设置出了什么问题。 + +不要指望靠一个"Verify"按钮来确认密钥和地址是否正确。它不一定总会出现,即使出现了也不能覆盖所有路径。真正可靠的确认方式是步骤 2:添加一个模型,然后真的给它发一条消息。 + +## 步骤 2:将三个 GPT-5.6 路由添加为自定义模型 + +还是在 Models 设置里,点击 **+ Add Custom Model** 三次,依次添加: + +``` +openai/gpt-5.6-sol +openai/gpt-5.6-terra +openai/gpt-5.6-luna +``` + +
+ +
添加 openai/gpt-5.6-sol、openai/gpt-5.6-terra、openai/gpt-5.6-luna 三个自定义模型。
+
+ +**这里的坑**:你在这里注册的名字,Cursor 会原样作为请求里的 `model` 字段发出去。Token Station 真实的路由名称里包含 `openai/` 前缀。如果你把模型注册成不带前缀的 `gpt-5.6-sol`,每个请求都会失败,报错 `Model 'gpt-5.6-sol' not found`,因为不带前缀的这个模型确实不存在。带上前缀注册,立刻就能用。 + +要确认这套流程真的端到端跑通了,而不只是被 Cursor 接受了:打开一个对话,选中新添加的某个模型,发一条无关紧要的消息,然后去 [Token Station 控制台](https://models.bytefuture.ai/dashboard) 查看。真实的回复加上 Recent Activity 里对应的一条记录,说明密钥、base URL 和模型名都是对的。 + +| 模型 | 适用场景 | +|---|---| +| `openai/gpt-5.6-sol` | 旗舰路由,适合高难度规划、调试和架构相关问题。 | +| `openai/gpt-5.6-terra` | 中间档位,适合反复的实现和调试讨论。 | +| `openai/gpt-5.6-luna` | 低成本路由,适合探索、初步排查和快速提问。 | + +## 步骤 3:定义基于 Luna 的 subagent + +Cursor 支持 subagent:带 YAML frontmatter 的 markdown 文件,可以按项目放在 `.cursor/agents/` 下,也可以全局放在 `~/.cursor/agents/` 下,每个都有自己的 `model` 字段。这让你可以把特定的、范围明确的委派任务指向比主对话更便宜的模型。 + +对编码场景来说,有两个角色很实用,都用 Luna: + +**`.cursor/agents/explore.md`** +```markdown +--- +name: explore +description: Searches and reads the codebase to answer questions about existing code. Use proactively before implementing anything unfamiliar. +model: openai/gpt-5.6-luna +readonly: true +--- + +You are a fast, read-only research agent. Find and summarize relevant +files, functions, and patterns. Never edit files or run mutating commands. +``` + +**`.cursor/agents/test-runner.md`** +```markdown +--- +name: test-runner +description: Runs the test suite and reports pass/fail results with failure details. Use proactively after any code change. +model: openai/gpt-5.6-luna +--- + +You run the project's test command, capture output, and report which +tests passed or failed and why. Do not modify source files. +``` + +
+ +
创建 explore 和 test-runner 两个 subagent,都使用 openai/gpt-5.6-luna。
+
+ +`explore` 上的 `readonly: true` 会阻止文件编辑和会改变状态的 shell 命令,这正好符合纯研究角色的定位。`test-runner` 需要真正执行测试命令,所以没有加这个限制,而是在指令里告诉它不要碰源代码文件。 + +在对话里触发 subagent 有两种方式:自动委派,即主 agent 读取 `description` 字段自行判断何时该交给它;或者用 `/explore`、`/test-runner` 显式调用。 + +如果你是在对话里让 agent 帮你写这两个文件,而不是自己在终端里写,写完后侧边栏依然显示没有 subagent,重新加载一下窗口(**Ctrl+Shift+P → "Reload Window"**):Cursor 不会总是实时重新扫描 `.cursor/agents/`。 + +## 目前能用的,和目前还不能用的 + +Chat 和 Ask 模式下用 Sol、Terra、Luna,效果和上面描述的一致:真实的回复,正确计入你的 Token Station 密钥,并显示在控制台里。 + +完整的 Agent 模式自主性,也就是模型直接读取你的代码库并写入改动,则是另一回事。在我们的测试中,通过 Override Base URL 添加的自定义 OpenAI 兼容模型,在 Agent 模式下可以读取和讨论代码,但无论我们试过哪种 Cursor 模式,都始终无法真正应用任何文件编辑。这和其他用户遇到同一堵墙的反馈是一致的:Cursor 的 Agent 工具调用机制需要特定的请求和响应格式,而标准的 OpenAI 兼容端点不一定能像 Cursor 自家托管的模型那样完整地往返这套格式。这不是 Token Station 特有的问题:同样的 `openai/gpt-5.6-*` 路由已经在 Codex 里驱动真实的 agentic 工具调用,模型和端点本身都不是这里的瓶颈。 + +如果你的工作流需要一个真正能编辑文件的 agent,Token Station 在 Codex、Claude Code 和 OpenClaw 上的集成是目前已验证可行的路径。在 Cursor 的 BYOK Agent 模式支持跟上之前,Cursor 是一个在编辑器里和 Sol、Terra、Luna 对话、并用分成本档位的 subagent 做对话式委派的可靠方式。 + +## 开始使用 + +前往 [models.bytefuture.ai](https://models.bytefuture.ai/signup) 注册:1 美元免费额度,无需信用卡,首次充值最高可再获得 50 美元奖励。导出你的密钥,接入 Cursor 的 Models 设置,添加这三个路由。 + +[试用 Token Station](https://models.bytefuture.ai/intro.html)