diff --git a/blog/asset-sources/route-cursor-through-token-station-cover.svg b/blog/asset-sources/route-cursor-through-token-station-cover.svg index 0587a11..a8eab98 100644 --- a/blog/asset-sources/route-cursor-through-token-station-cover.svg +++ b/blog/asset-sources/route-cursor-through-token-station-cover.svg @@ -27,10 +27,10 @@ Cursor, wired in. - Sol, Terra, Luna: custom models. + Sonnet 5, Haiku: custom models. - + OVERRIDE OPENAI BASE URL @@ -41,17 +41,12 @@ - openai/gpt-5.6-sol + anthropic/claude-sonnet-5 - openai/gpt-5.6-terra - - - - - openai/gpt-5.6-luna + anthropic/claude-haiku-4-5 diff --git a/blog/route-cursor-through-token-station-cover.png b/blog/route-cursor-through-token-station-cover.png index e9ada15..2a09c9c 100644 Binary files a/blog/route-cursor-through-token-station-cover.png 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 index 46f70e8..488dd1e 100644 Binary files a/blog/route-cursor-through-token-station/add-models.mp4 and b/blog/route-cursor-through-token-station/add-models.mp4 differ diff --git a/blog/route-cursor-through-token-station/demo-httpie.mp4 b/blog/route-cursor-through-token-station/demo-httpie.mp4 new file mode 100644 index 0000000..0027708 Binary files /dev/null and b/blog/route-cursor-through-token-station/demo-httpie.mp4 differ diff --git a/blog/route-cursor-through-token-station/register-provider.mp4 b/blog/route-cursor-through-token-station/register-provider.mp4 index ce7fbd5..78992c1 100644 Binary files a/blog/route-cursor-through-token-station/register-provider.mp4 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 index e609a09..0b8a170 100644 Binary files a/blog/route-cursor-through-token-station/subagents.mp4 and b/blog/route-cursor-through-token-station/subagents.mp4 differ diff --git a/sitemap.xml b/sitemap.xml index 33ec0f3..2bcb1fd 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -307,22 +307,22 @@ https://bytefuture.ai/blog/route-cursor-through-token-station.html - 2026-08-13 + 2026-08-18 0.7 https://bytefuture.ai/blog/route-cursor-through-token-station-zh.html - 2026-08-13 + 2026-08-18 0.6 https://bytefuture.ai/blog/route-cursor-through-token-station-ja.html - 2026-08-13 + 2026-08-18 0.6 https://bytefuture.ai/blog/route-cursor-through-token-station-ko.html - 2026-08-13 + 2026-08-18 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 index e41f6ea..f0887dc 100644 --- a/src/content/writings/en/route-cursor-through-token-station.md +++ b/src/content/writings/en/route-cursor-through-token-station.md @@ -1,16 +1,16 @@ --- 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." +title: "Route Cursor through Token Station: Claude Sonnet 5 and Haiku" +summary: "Cursor supports custom OpenAI-compatible providers through Settings, Models. Point it at Token Station and Claude Sonnet 5 and Haiku show up as selectable models with full Agent-mode support: real file edits, not just chat, plus scoped subagents for delegated research and verification." category: "tutorial" -date: "2026-08-13" +date: "2026-08-21" 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. +Cursor supports custom OpenAI-compatible providers through Settings → Models. Point it at Token Station's endpoint and you can add Claude Sonnet 5 and Haiku as selectable models, each billed through your own Token Station key. Unlike some other model families available through Token Station, these two fully support Cursor's Agent mode: real file edits, not just chat. This walks through the setup end to end, including a naming gotcha we hit doing it ourselves, and finishes with an actual coding session: Sonnet 5 implementing a real feature in an open-source project, delegating research and verification to two purpose-built subagents. ## What you need before starting @@ -32,49 +32,43 @@ Open **Settings → Cursor Settings → Models**, scroll to **API Keys**, and se
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 +## Step 2: Add Claude Sonnet 5 and Haiku as custom models -Still in Models settings, click **+ Add Custom Model** three times and add: +Still in Models settings, click **+ Add Custom Model** twice and add: ``` -openai/gpt-5.6-sol -openai/gpt-5.6-terra -openai/gpt-5.6-luna +anthropic/claude-sonnet-5 +anthropic/claude-haiku-4-5 ```
-
Adding openai/gpt-5.6-sol, openai/gpt-5.6-terra, and openai/gpt-5.6-luna as custom models.
+
Adding anthropic/claude-sonnet-5 and anthropic/claude-haiku-4-5 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. +**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 `anthropic/` prefix. Register the model as plain `claude-sonnet-5` and every request fails with `Model 'claude-sonnet-5' 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 +| `anthropic/claude-sonnet-5` | Main coding model: planning, implementation, and Agent-mode file edits. | +| `anthropic/claude-haiku-4-5` | A cheaper model to switch the main chat to directly for lighter, single-turn questions. See Step 3 for why it isn't a cost-tier for subagents yet. | -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. +## Step 3: Define scoped subagents -Two useful roles for a coding session, both on Luna: +Cursor supports subagents: markdown files with YAML frontmatter, defined per-project in `.cursor/agents/` or globally in `~/.cursor/agents/`. Two useful roles for a coding session: a read-only researcher, and a test verifier that runs after a change. -**`.cursor/agents/explore.md`** +**`.cursor/agents/bill-the-explorer.md`** ```markdown --- -name: explore +name: bill-the-explorer description: Searches and reads the codebase to answer questions about existing code. Use proactively before implementing anything unfamiliar. -model: openai/gpt-5.6-luna +model: anthropic/claude-haiku-4-5 readonly: true --- @@ -82,41 +76,79 @@ 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`** +**`.cursor/agents/jill-the-test-runner.md`** ```markdown --- -name: test-runner +name: jill-the-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 +model: anthropic/claude-haiku-4-5 --- You run the project's test command, capture output, and report which tests passed or failed and why. Do not modify source files. ``` +**Name your subagents something that won't collide with one of Cursor's own built-in agents.** We first tried `explore`, and Cursor silently routed to its own built-in agent of the same name instead of ours, with no error to explain why nothing we specified was taking effect. `bill-the-explorer` and `jill-the-test-runner` avoid the collision. +
-
Creating the explore and test-runner subagents, both backed by openai/gpt-5.6-luna.
+
Creating the bill-the-explorer and jill-the-test-runner subagents.
-`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. +`readonly: true` on `bill-the-explorer` blocks file edits and state-changing shell commands, which fits a pure research role. `jill-the-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`. +**About that `model:` line.** It's valid, documented Cursor syntax, and we set both subagents to `anthropic/claude-haiku-4-5` expecting a cost-tier split from the main conversation. It didn't happen. Asked directly why, the agent running the session gave a precise answer: the Task tool it calls to run a subagent only accepts a `model` parameter from a fixed allowlist, currently `inherit` or Cursor's own `composer-2.5-fast`, and doesn't read the `model:` frontmatter from a custom agent file at all. With no valid custom value to pass, it defaults to `inherit`, meaning every subagent runs on whatever model the parent conversation is using, Sonnet 5 in this setup, not Haiku. `name`, `description`, and `readonly` are honored and do their job; `model` currently isn't, for any custom model, not just Haiku. This matches multiple independent reports on Cursor's own community forum, so it's a known, current limitation rather than something specific to this setup. + +That leaves subagents genuinely useful for scoping delegated work by role and permission, a read-only researcher versus a test-runner that only reports, invoked automatically (the main agent reads each `description` and decides when to hand off) or explicitly with `/bill-the-explorer` or `/jill-the-test-runner`. It just doesn't currently give you a cheaper model for that delegated work. 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 +## Step 4: Watch it implement a real feature + +With the provider, models, and subagents in place, Sonnet 5 can run an actual coding session end to end: research, implementation, and verification, delegating the read-only and verification steps along the way. + +We used [httpie](https://github.com/httpie/httpie), a real, moderately sized, well-tested open-source project, as the target. httpie's `--meta`/`-m` flag prints the request's elapsed time; it doesn't yet show the effective URL reached after following any redirects. That's a small, well-scoped, genuinely useful feature, the kind of task that needs a look at existing code before touching anything. + +Explicit invocation turned out to be the reliable way to trigger delegation. Asking in plain prose to "use the explore subagent" didn't actually hand off; the main agent just narrated doing so while working under its own context. Naming the subagent with a leading slash, as its own message, is what worked: + +**Message 1**, to delegate research: +``` +/bill-the-explorer find how elapsed time is computed and displayed in HTTPie's --meta output, and identify where to add the effective URL, the URL actually reached after following any redirects, alongside it. +``` + +**Message 2**, back to the main agent, once research comes back: +``` +Using what bill-the-explorer found, add the effective URL next to the existing elapsed time in HTTPie's --meta output. Add a test that confirms it works for both a redirected and a non-redirected request. +``` + +**Message 3**, to delegate verification: +``` +/jill-the-test-runner verify the new effective-URL test passes, along with the rest of the test suite. Report any failures separately from the two known pre-existing Big5 charset-detection failures in tests/test_encoding.py, which are unrelated to this change. +``` + +
+ +
Sonnet 5 delegating research to bill-the-explorer, implementing the change itself, then delegating verification to jill-the-test-runner, all through Token Station.
+
+ +Because subagent model routing isn't honored yet, the whole session bills as `anthropic/claude-sonnet-5` on the [Token Station dashboard](https://models.bytefuture.ai/dashboard), research and verification included, not the cost-tiered split we set out to show. What the video does show: `bill-the-explorer` running strictly read-only and reporting back before any code changes, and `jill-the-test-runner` running afterward to verify, distinct scoped roles doing distinct jobs in sequence, just not yet at distinct prices. + +## What works today + +Chat and Agent mode both work with Sonnet 5 and Haiku through Token Station in Cursor: real replies, real file edits, correctly billed to your Token Station key, visible on the dashboard. -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. +Subagents work for scoping and permissions, `name`, `description`, and `readonly` are all honored, and both automatic and explicit (`/name`) invocation trigger real delegation. Subagent-level model routing does not currently work for custom models: Cursor's Task tool only accepts `inherit` or its own `composer-2.5-fast`, so every subagent runs on the parent conversation's model regardless of what `model:` specifies in its frontmatter. That's a Cursor platform limitation, confirmed directly by the agent itself and matching independent reports elsewhere, not something specific to Token Station or to Haiku. -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. +Earlier testing with Token Station's GPT-5.6 routes (Sol, Terra, Luna) found that Agent mode could read and discuss code but consistently failed to apply actual file edits, a tool-call response format issue on Token Station's side rather than a hard Cursor limitation. Support for those routes is in progress. If you want a coding agent that reliably edits files in Cursor today, route it through `anthropic/claude-sonnet-5` and `anthropic/claude-haiku-4-5` rather than the GPT-5.6 family. -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. +Token Station's xAI route, `xai/grok-4.6`, is also supported in Cursor through the same custom-provider setup, if you'd rather try Grok for the main coding role. ## 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. +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 two 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 index 508c471..53fb2df 100644 --- a/src/content/writings/ja/route-cursor-through-token-station.md +++ b/src/content/writings/ja/route-cursor-through-token-station.md @@ -1,16 +1,16 @@ --- 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/ プレフィックスだ。" +title: "Cursor を Token Station に接続する：Claude Sonnet 5 と Haiku" +summary: "Cursor は Settings の Models パネルからカスタム OpenAI 互換プロバイダーに対応している。Token Station を指定すれば Claude Sonnet 5 と Haiku が選択可能なモデルとして現れ、Agent モードも完全にサポートする。チャットだけでなく実際のファイル編集ができ、調査と検証を任せる専用のサブエージェントも使える。" category: "tutorial" -date: "2026-08-13" +date: "2026-08-21" 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 は Settings → Models からカスタム OpenAI 互換プロバイダーに対応している。Token Station のエンドポイントを指定すれば、Claude Sonnet 5 と Haiku を選択可能なモデルとして追加でき、すべて自分の Token Station キーで課金される。Token Station 上の他のいくつかのモデルファミリーと違い、この二つは Cursor の Agent モードを完全にサポートする。チャットだけでなく、実際のファイル編集ができるということだ。ここでは設定を最初から最後まで説明する。実際にやってみて遭遇した命名上の落とし穴も含めて、最後には実際のコーディングセッションまで見せる。Sonnet 5 がオープンソースプロジェクトで実際の機能を実装し、調査と検証を二つの専用サブエージェントに委任する様子だ。 ## 始める前に必要なもの @@ -32,49 +32,43 @@ Cursor は Settings → Models からカスタム OpenAI 互換プロバイダ
Cursor の Models 設定で、Token Station をカスタム OpenAI 互換プロバイダーとして登録する。
-**知っておくべき既知のバグ**：現行の Cursor（3.15.x 系）では、この二つのフィールドがクリックしてもキーボード入力を受け付けないことがある。入力しても何も起きない場合は、まずパネル内の別の場所をクリックし、その後 **Tab** キーを繰り返し押してフォーカスを対象フィールドに移す。Tab でフォーカスが当たった後は、入力も **Ctrl+V** による貼り付けも問題なく動作する。これは公式に認められているリグレッションであり、あなたの環境固有の問題ではない。 - キーとURLが正しいことの確認を「Verify」ボタンに頼らないこと。常に表示されるわけではなく、表示されていてもすべての経路をカバーしているわけではない。信頼できる確認方法はステップ 2 だ。モデルを追加して、実際にメッセージを送ってみる。 -## ステップ 2：三つの GPT-5.6 ルートをカスタムモデルとして追加する +## ステップ 2：Claude Sonnet 5 と Haiku をカスタムモデルとして追加する -引き続き Models の設定で、**+ Add Custom Model** を三回クリックし、次を追加する。 +引き続き Models の設定で、**+ Add Custom Model** を二回クリックし、次を追加する。 ``` -openai/gpt-5.6-sol -openai/gpt-5.6-terra -openai/gpt-5.6-luna +anthropic/claude-sonnet-5 +anthropic/claude-haiku-4-5 ```
-
openai/gpt-5.6-sol、openai/gpt-5.6-terra、openai/gpt-5.6-luna をカスタムモデルとして追加する。
+
anthropic/claude-sonnet-5 と anthropic/claude-haiku-4-5 をカスタムモデルとして追加する。
-**ここが落とし穴**：ここで登録した名前を、Cursor はそのままリクエストの `model` フィールドとして送信する。Token Station の実際のルート名には `openai/` プレフィックスが含まれる。プレフィックスなしの `gpt-5.6-sol` として登録すると、すべてのリクエストが `Model 'gpt-5.6-sol' not found` というエラーで失敗する。プレフィックスなしのそのモデルは実際に存在しないからだ。プレフィックス付きで登録すればすぐに動作する。 +**ここが落とし穴**：ここで登録した名前を、Cursor はそのままリクエストの `model` フィールドとして送信する。Token Station の実際のルート名には `anthropic/` プレフィックスが含まれる。プレフィックスなしの `claude-sonnet-5` として登録すると、すべてのリクエストが `Model 'claude-sonnet-5' 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 を使うサブエージェントを定義する +| `anthropic/claude-sonnet-5` | メインのコーディングモデル。プランニング、実装、Agent モードでのファイル編集に。 | +| `anthropic/claude-haiku-4-5` | 軽い一往復の質問のためにメインのチャットを直接切り替える、より安価なモデル。なぜこれがまだサブエージェント用の低コスト階層になっていないかは、ステップ 3 を参照。 | -Cursor はサブエージェントに対応している。YAML フロントマター付きの markdown ファイルで、プロジェクトごとに `.cursor/agents/` に置くか、グローバルに `~/.cursor/agents/` に置くことができ、それぞれが独自の `model` フィールドを持つ。これにより、特定の範囲が明確なタスクの委任先を、メインのチャットより安いモデルに向けられる。 +## ステップ 3：範囲を絞ったサブエージェントを定義する -コーディングセッションで有用な二つの役割を、どちらも Luna で構成する。 +Cursor はサブエージェントに対応している。YAML フロントマター付きの markdown ファイルで、プロジェクトごとに `.cursor/agents/` に置くか、グローバルに `~/.cursor/agents/` に置くことができる。コーディングセッションで有用な二つの役割がある。読み取り専用の調査役と、変更後に検証だけを行うテスト実行役だ。 -**`.cursor/agents/explore.md`** +**`.cursor/agents/bill-the-explorer.md`** ```markdown --- -name: explore +name: bill-the-explorer description: Searches and reads the codebase to answer questions about existing code. Use proactively before implementing anything unfamiliar. -model: openai/gpt-5.6-luna +model: anthropic/claude-haiku-4-5 readonly: true --- @@ -82,41 +76,79 @@ 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`** +**`.cursor/agents/jill-the-test-runner.md`** ```markdown --- -name: test-runner +name: jill-the-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 +model: anthropic/claude-haiku-4-5 --- You run the project's test command, capture output, and report which tests passed or failed and why. Do not modify source files. ``` +**サブエージェントの名前は、Cursor 自身の組み込みエージェントと衝突しないものにすること。** 最初は `explore` という名前を使ったが、Cursor は何のエラーも出さないまま、こちらが定義したものではなく同名の組み込みエージェントに静かにルーティングしていた。何を指定しても反映されない理由が分からないままだった。`bill-the-explorer` と `jill-the-test-runner` ならこの衝突を避けられる。 +
-
explore と test-runner の二つのサブエージェントを作成する。どちらも openai/gpt-5.6-luna を使用。
+
bill-the-explorer と jill-the-test-runner の二つのサブエージェントを作成する。
-`explore` の `readonly: true` はファイル編集と状態を変更するシェルコマンドをブロックする。純粋な研究役にはこれが合っている。`test-runner` はテストコマンドを実際に実行する必要があるため、この制限は付けず、代わりに指示の中でソースファイルに触れないよう指定している。 +`bill-the-explorer` の `readonly: true` はファイル編集と状態を変更するシェルコマンドをブロックする。純粋な調査役にはこれが合っている。`jill-the-test-runner` はテストコマンドを実際に実行する必要があるため、この制限は付けず、代わりに指示の中でソースファイルに触れないよう指定している。 -チャットでサブエージェントを起動する方法は二つある。自動委任では、メインエージェントが `description` フィールドを読み、いつ委任するかを自分で判断する。もう一つは `/explore` や `/test-runner` による明示的な呼び出しだ。 +**あの `model:` の行について。** これは有効な、文書化された Cursor の構文であり、メインの会話とはコストの階層を分けられることを期待して、両方のサブエージェントを `anthropic/claude-haiku-4-5` に設定した。しかし、そうはならなかった。セッションを担当していたエージェントに直接理由を尋ねたところ、的確な答えが返ってきた。サブエージェントを実行するために呼び出す Task ツールは、固定された許可リストにある `model` パラメータしか受け付けず、現状では `inherit` か Cursor 自身の `composer-2.5-fast` のどちらかだけで、カスタムエージェントファイルの `model:` フロントマターはまったく読み込まないという。渡せる有効なカスタム値がないため、`inherit` にデフォルトされ、結果としてすべてのサブエージェントは親の会話が使っているモデル、この構成では Sonnet 5 で動作し、Haiku では動作しない。`name`、`description`、`readonly` はきちんと反映されて機能しているが、`model` は今のところ機能しない。それも Haiku だけの話ではなく、どのカスタムモデルでも同様だ。これは Cursor 自身のコミュニティフォーラムに寄せられた複数の独立した報告とも一致しており、この設定固有の問題ではなく、既知の現行の制限だと分かる。 + +そのため、サブエージェントは役割と権限によって委任作業を切り分けるという点では確かに有用だ。読み取り専用の調査役と、報告だけを行うテスト実行役を、自動委任(メインエージェントが各 `description` を読んで委任のタイミングを自分で判断する)でも、`/bill-the-explorer` や `/jill-the-test-runner` による明示的な呼び出しでも使える。ただ、その委任先の作業に対して今のところ安いモデルを使えるわけではない。 これらのファイルを、自分でターミナルから書く代わりにチャットでエージェントに書かせた場合、サイドバーに依然としてサブエージェントが表示されないなら、ウィンドウをリロードする（**Ctrl+Shift+P → "Reload Window"**）。Cursor は常にライブで `.cursor/agents/` を再スキャンするわけではない。 -## 今できること、まだできないこと +## ステップ 4：実際の機能を実装するところを見る + +プロバイダー、モデル、サブエージェントがそろえば、Sonnet 5 は調査、実装、検証まで含む実際のコーディングセッションを最初から最後まで実行できる。途中の読み取り専用ステップと検証ステップはそれぞれのサブエージェントに委任しながらだ。 + +対象には [httpie](https://github.com/httpie/httpie) を使った。実在する、規模もほどよく、テストも整った OSS プロジェクトだ。httpie の `--meta`/`-m` フラグはリクエストの経過時間を表示するが、リダイレクトをたどった後に実際に到達した URL はまだ表示しない。これは小さく、範囲が明確で、実際に役立つ機能であり、手を付ける前に既存のコードをひと目見る必要があるタイプのタスクだ。 + +委任を確実にトリガーする方法は、明示的な呼び出しだと分かった。地の文で「explore サブエージェントを使って」と頼んでも、実際には委任されない。メインエージェントは自分のコンテキストの中で作業しながら、そうしたかのように語るだけだった。サブエージェント名の先頭にスラッシュを付け、独立したメッセージとして送ることで、うまくいった。 + +**メッセージ 1**、調査を委任する。 +``` +/bill-the-explorer find how elapsed time is computed and displayed in HTTPie's --meta output, and identify where to add the effective URL, the URL actually reached after following any redirects, alongside it. +``` + +**メッセージ 2**、調査結果が戻ってきたら、メインエージェントに戻る。 +``` +Using what bill-the-explorer found, add the effective URL next to the existing elapsed time in HTTPie's --meta output. Add a test that confirms it works for both a redirected and a non-redirected request. +``` + +**メッセージ 3**、検証を委任する。 +``` +/jill-the-test-runner verify the new effective-URL test passes, along with the rest of the test suite. Report any failures separately from the two known pre-existing Big5 charset-detection failures in tests/test_encoding.py, which are unrelated to this change. +``` + +
+ +
Sonnet 5 が調査を bill-the-explorer に委任し、自分で変更を実装し、検証を jill-the-test-runner に委任する。すべて Token Station 経由。
+
+ +サブエージェントのモデルルーティングがまだ反映されないため、[Token Station のダッシュボード](https://models.bytefuture.ai/dashboard)上ではセッション全体が `anthropic/claude-sonnet-5` として課金される。調査や検証も例外ではなく、当初見せようとしていたコスト階層の分離にはなっていない。この動画が実際に示しているのは、`bill-the-explorer` が厳密に読み取り専用で動作し、コードを変更する前に結果を報告すること、そして `jill-the-test-runner` がその後に動作して検証すること。役割が明確に分かれた作業が順番どおりに行われているが、価格の面ではまだそうなっていない、ということだ。 + +## 今できること + +Chat モードと Agent モードのどちらでも、Sonnet 5 と Haiku は Token Station 経由で Cursor の中で使える。実際の返信、実際のファイル編集があり、正しく Token Station のキーに課金され、ダッシュボードにも表示される。 -Chat モードと Ask モードで Sol、Terra、Luna を使う分には、上に書いた通り動作する。実際の返信があり、正しく Token Station のキーに課金され、ダッシュボードにも表示される。 +サブエージェントは役割分担と権限管理の面では機能する。`name`、`description`、`readonly` はいずれもきちんと反映され、自動委任も明示的な呼び出し(`/name`)も実際の委任をトリガーする。一方、サブエージェント側でのモデルルーティングは、カスタムモデルに対しては今のところ機能しない。Cursor の Task ツールは `inherit` か自身の `composer-2.5-fast` しか受け付けないため、フロントマターの `model:` に何を指定していても、すべてのサブエージェントはメインの会話が使っているモデルで動作する。これは Cursor プラットフォーム自体の制限であり、エージェント自身によって直接確認され、他の場所での独立した報告とも一致している。Token Station や Haiku に固有の問題ではない。 -一方、完全な Agent モードの自律性、つまりモデルが自分でコードベースを読み、変更を直接書き込む部分は話が別だ。私たちのテストでは、Override Base URL 経由で追加したカスタム OpenAI 互換モデルは、Agent モードでコードを読み議論することはできたが、どの Cursor モードを試しても実際のファイル編集を適用することは一貫してできなかった。これは同じ壁にぶつかっている他のユーザーの報告とも一致する。Cursor の Agent ツール呼び出しの仕組みは特定のリクエストとレスポンスの形を期待しており、標準的な OpenAI 互換エンドポイントが Cursor 自身がホストするモデルと同じようにその形を正しくやり取りできる保証はない。これは Token Station 固有の問題ではない。同じ `openai/gpt-5.6-*` ルートは、Codex ではすでに実際の agentic なツール呼び出しを動かしており、モデルやエンドポイント自体がここでのボトルネックではないからだ。 +以前 Token Station の GPT-5.6 ルート(Sol、Terra、Luna)をテストしたところ、Agent モードでコードを読み議論することはできたが、実際のファイル編集を適用することには一貫して失敗した。これは Cursor 側の硬い制限ではなく、Token Station 側のツール呼び出しレスポンス形式の問題だった。これらのルートへの対応は現在進行中だ。今すぐ Cursor で確実にファイルを編集できるコーディングエージェントが必要なら、GPT-5.6 系ではなく `anthropic/claude-sonnet-5` と `anthropic/claude-haiku-4-5` を使ってほしい。 -実際にファイルを編集できるエージェントがワークフローに必要なら、Token Station の Codex、Claude Code、OpenClaw との連携が現時点で実証済みの選択肢だ。Cursor の BYOK による Agent モード対応が追いつくまでは、Cursor はエディタの中で Sol、Terra、Luna とチャットし、コスト階層の異なるサブエージェントでチャットベースの委任を行うための、堅実な手段だと言える。 +Token Station の xAI ルート `xai/grok-4.6` も、同じカスタムプロバイダーの設定で Cursor から使える。メインのコーディング役に Grok を試したい場合はこちらだ。 ## はじめよう -[models.bytefuture.ai](https://models.bytefuture.ai/signup) で登録する。1 ドル分の無料クレジット、クレジットカード不要。初回チャージで最大 50 ドルのボーナスも付く。キーをエクスポートし、Cursor の Models 設定に接続し、三つのルートを追加しよう。 +[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 index ae22832..2552f40 100644 --- a/src/content/writings/ko/route-cursor-through-token-station.md +++ b/src/content/writings/ko/route-cursor-through-token-station.md @@ -1,16 +1,16 @@ --- 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/ 접두사다." +title: "Cursor를 Token Station에 연결하기: Claude Sonnet 5와 Haiku" +summary: "Cursor는 Settings의 Models 패널에서 커스텀 OpenAI 호환 프로바이더를 지원한다. Token Station을 지정하면 Claude Sonnet 5와 Haiku가 선택 가능한 모델로 나타나며, Agent 모드까지 완전히 지원한다. 채팅뿐 아니라 실제 파일 편집이 가능하고, 조사와 검증을 맡기는 전용 서브에이전트도 쓸 수 있다." category: "tutorial" -date: "2026-08-13" +date: "2026-08-21" 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는 Settings → Models에서 커스텀 OpenAI 호환 프로바이더를 지원한다. Token Station의 엔드포인트를 지정하면 Claude Sonnet 5와 Haiku를 선택 가능한 모델로 추가할 수 있고, 모두 자신의 Token Station 키로 과금된다. Token Station에 있는 다른 몇몇 모델 계열과 달리, 이 둘은 Cursor의 Agent 모드를 완전히 지원한다. 채팅뿐 아니라 실제 파일 편집이 가능하다는 뜻이다. 여기서는 설정 과정을 처음부터 끝까지 다룬다. 직접 해보면서 만난 이름 관련 함정도 포함해서다. 마지막에는 실제 코딩 세션까지 보여준다. Sonnet 5가 오픈소스 프로젝트에서 실제 기능을 구현하고, 조사와 검증을 두 개의 전용 서브에이전트에 위임하는 과정이다. ## 시작하기 전에 필요한 것 @@ -32,49 +32,43 @@ Cursor는 Settings → Models에서 커스텀 OpenAI 호환 프로바이더를
Cursor의 Models 설정에서 Token Station을 커스텀 OpenAI 호환 프로바이더로 등록하는 과정.
-**알아두면 좋은 알려진 버그**: 현재 Cursor 빌드(3.15.x 계열)에서는 이 두 필드가 클릭해도 키보드 입력을 받지 않을 때가 있다. 입력해도 아무 반응이 없다면, 먼저 패널의 다른 부분을 클릭한 다음 **Tab** 키를 반복해서 눌러 포커스가 해당 필드로 오게 한다. Tab으로 포커스가 온 뒤에는 입력과 **Ctrl+V** 붙여넣기 모두 정상 작동한다. 이는 공식적으로 인정된 회귀 버그이며, 특정 사용자 환경의 문제가 아니다. - 키와 URL이 올바른지 확인할 때 "Verify" 버튼에 의존하지 말자. 항상 나타나는 것도 아니고, 나타나더라도 모든 경로를 커버하지는 않는다. 믿을 만한 확인 방법은 2단계다: 모델을 추가하고 실제로 메시지를 보내보는 것. -## 2단계: 세 가지 GPT-5.6 라우트를 커스텀 모델로 추가하기 +## 2단계: Claude Sonnet 5와 Haiku를 커스텀 모델로 추가하기 -여전히 Models 설정에서, **+ Add Custom Model**을 세 번 클릭해 다음을 추가한다. +여전히 Models 설정에서, **+ Add Custom Model**을 두 번 클릭해 다음을 추가한다. ``` -openai/gpt-5.6-sol -openai/gpt-5.6-terra -openai/gpt-5.6-luna +anthropic/claude-sonnet-5 +anthropic/claude-haiku-4-5 ```
-
openai/gpt-5.6-sol, openai/gpt-5.6-terra, openai/gpt-5.6-luna를 커스텀 모델로 추가하는 과정.
+
anthropic/claude-sonnet-5와 anthropic/claude-haiku-4-5를 커스텀 모델로 추가하는 과정.
-**여기가 함정이다**: 여기서 등록한 이름을 Cursor는 그대로 요청의 `model` 필드로 보낸다. Token Station의 실제 라우트 이름에는 `openai/` 접두사가 붙어 있다. 접두사 없이 `gpt-5.6-sol`로 등록하면 모든 요청이 `Model 'gpt-5.6-sol' not found` 오류로 실패하는데, 접두사가 없는 그 모델은 실제로 존재하지 않기 때문이다. 접두사를 붙여 등록하면 바로 작동한다. +**여기가 함정이다**: 여기서 등록한 이름을 Cursor는 그대로 요청의 `model` 필드로 보낸다. Token Station의 실제 라우트 이름에는 `anthropic/` 접두사가 붙어 있다. 접두사 없이 `claude-sonnet-5`로 등록하면 모든 요청이 `Model 'claude-sonnet-5' 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 기반 서브에이전트 정의하기 +| `anthropic/claude-sonnet-5` | 메인 코딩 모델. 플래닝, 구현, Agent 모드에서의 파일 편집에. | +| `anthropic/claude-haiku-4-5` | 가벼운 단발성 질문을 위해 메인 채팅을 직접 전환할 수 있는 더 저렴한 모델. 아직 서브에이전트용 저비용 등급이 되지 못하는 이유는 3단계 참고. | -Cursor는 서브에이전트를 지원한다. YAML 프론트매터가 있는 마크다운 파일로, 프로젝트별로 `.cursor/agents/`에 두거나 전역으로 `~/.cursor/agents/`에 둘 수 있으며, 각각 자체 `model` 필드를 가진다. 이를 통해 범위가 명확한 특정 위임 작업을 메인 채팅보다 저렴한 모델로 향하게 할 수 있다. +## 3단계: 범위가 명확한 서브에이전트 정의하기 -코딩 세션에 유용한 두 가지 역할을, 둘 다 Luna로 구성한다. +Cursor는 서브에이전트를 지원한다. YAML 프론트매터가 있는 마크다운 파일로, 프로젝트별로 `.cursor/agents/`에 두거나 전역으로 `~/.cursor/agents/`에 둘 수 있다. 코딩 세션에 유용한 두 가지 역할이 있다. 읽기 전용 조사 역할과, 변경 후 검증만 담당하는 테스트 실행 역할이다. -**`.cursor/agents/explore.md`** +**`.cursor/agents/bill-the-explorer.md`** ```markdown --- -name: explore +name: bill-the-explorer description: Searches and reads the codebase to answer questions about existing code. Use proactively before implementing anything unfamiliar. -model: openai/gpt-5.6-luna +model: anthropic/claude-haiku-4-5 readonly: true --- @@ -82,41 +76,79 @@ 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`** +**`.cursor/agents/jill-the-test-runner.md`** ```markdown --- -name: test-runner +name: jill-the-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 +model: anthropic/claude-haiku-4-5 --- You run the project's test command, capture output, and report which tests passed or failed and why. Do not modify source files. ``` +**서브에이전트 이름은 Cursor 자체의 내장 에이전트와 겹치지 않는 것으로 짓자.** 처음에는 `explore`라는 이름을 썼는데, Cursor가 아무 오류 메시지도 없이 우리가 정의한 것 대신 같은 이름의 내장 에이전트로 조용히 라우팅하고 있었다. 지정한 내용이 왜 전혀 반영되지 않는지 알 수 없는 상태였다. `bill-the-explorer`와 `jill-the-test-runner`는 이 충돌을 피한다. +
-
explore와 test-runner 두 서브에이전트를 만드는 과정. 둘 다 openai/gpt-5.6-luna를 사용한다.
+
bill-the-explorer와 jill-the-test-runner 두 서브에이전트를 만드는 과정.
-`explore`의 `readonly: true`는 파일 편집과 상태를 변경하는 셸 명령을 막는데, 순수 조사 역할에 딱 맞는다. `test-runner`는 테스트 명령을 실제로 실행해야 하므로 이 제한을 두지 않았고, 대신 지시문에서 소스 파일을 건드리지 말라고 명시했다. +`bill-the-explorer`의 `readonly: true`는 파일 편집과 상태를 변경하는 셸 명령을 막는데, 순수 조사 역할에 딱 맞는다. `jill-the-test-runner`는 테스트 명령을 실제로 실행해야 하므로 이 제한을 두지 않았고, 대신 지시문에서 소스 파일을 건드리지 말라고 명시했다. -채팅에서 서브에이전트를 실행하는 방법은 두 가지다. 자동 위임은 메인 에이전트가 `description` 필드를 읽고 언제 위임할지 스스로 판단하는 방식이고, `/explore`나 `/test-runner`로 명시적으로 호출하는 방법도 있다. +**저 `model:` 줄에 대해.** 이는 유효하고 문서화된 Cursor 문법이며, 메인 대화와 비용 등급이 나뉘길 기대하며 두 서브에이전트 모두 `anthropic/claude-haiku-4-5`로 설정했다. 하지만 그렇게 되지 않았다. 세션을 담당하던 에이전트에게 직접 이유를 물었더니 정확한 답이 돌아왔다. 서브에이전트를 실행하기 위해 호출하는 Task 도구는 고정된 허용 목록에 있는 `model` 파라미터만 받아들이는데, 현재는 `inherit` 아니면 Cursor 자체의 `composer-2.5-fast`뿐이고, 커스텀 에이전트 파일의 `model:` 프론트매터는 아예 읽지 않는다는 것이다. 전달할 수 있는 유효한 커스텀 값이 없으니 `inherit`로 기본 설정되고, 결과적으로 모든 서브에이전트는 부모 대화가 사용 중인 모델, 이 구성에서는 Sonnet 5로 동작하며 Haiku로는 동작하지 않는다. `name`, `description`, `readonly`는 제대로 반영되어 작동하지만, `model`은 현재 작동하지 않는다. 그것도 Haiku만이 아니라 어떤 커스텀 모델이든 마찬가지다. 이는 Cursor 자체 커뮤니티 포럼에 올라온 여러 독립적인 보고와도 일치하므로, 이 설정만의 문제가 아니라 알려진 현재 진행형 제약이라는 뜻이다. + +그래도 서브에이전트는 역할과 권한에 따라 위임 작업을 나누는 데는 확실히 유용하다. 읽기 전용 조사 역할과, 보고만 하는 테스트 실행 역할을, 자동 위임(메인 에이전트가 각 `description`을 읽고 언제 위임할지 스스로 판단하는 방식)으로도, `/bill-the-explorer`나 `/jill-the-test-runner`를 통한 명시적 호출로도 쓸 수 있다. 다만 그 위임 작업에 지금 당장 더 저렴한 모델을 쓸 수 있는 건 아니다. 이 파일들을 터미널에서 직접 만드는 대신 채팅에서 에이전트에게 작성해달라고 요청했는데도 사이드바에 여전히 서브에이전트가 표시되지 않는다면, 창을 새로고침한다(**Ctrl+Shift+P → "Reload Window"**). Cursor가 `.cursor/agents/`를 항상 실시간으로 다시 스캔하지는 않는다. -## 지금 되는 것과 아직 안 되는 것 +## 4단계: 실제 기능을 구현하는 과정 지켜보기 + +프로바이더, 모델, 서브에이전트가 모두 준비되면 Sonnet 5는 조사, 구현, 검증까지 포함하는 실제 코딩 세션을 처음부터 끝까지 실행할 수 있다. 그 사이 읽기 전용 단계와 검증 단계는 각각의 서브에이전트에 위임하면서다. + +대상으로는 [httpie](https://github.com/httpie/httpie)를 사용했다. 실제로 존재하고, 규모도 적당하며, 테스트도 잘 갖춰진 오픈소스 프로젝트다. httpie의 `--meta`/`-m` 플래그는 요청의 경과 시간을 출력하지만, 리다이렉트를 따라간 뒤 실제로 도달한 URL은 아직 보여주지 않는다. 이는 작고 범위가 명확하며 실제로 유용한 기능으로, 손대기 전에 기존 코드를 먼저 살펴봐야 하는 종류의 작업이다. + +위임을 확실하게 트리거하는 방법은 명시적 호출이었다. 그냥 문장으로 "explore 서브에이전트를 써서"라고 요청해서는 실제로 위임되지 않았다. 메인 에이전트는 자기 컨텍스트 안에서 작업하면서 그렇게 한 것처럼 말만 할 뿐이었다. 서브에이전트 이름 앞에 슬래시를 붙여 하나의 독립된 메시지로 보내는 방식이 효과가 있었다. + +**메시지 1**, 조사를 위임한다. +``` +/bill-the-explorer find how elapsed time is computed and displayed in HTTPie's --meta output, and identify where to add the effective URL, the URL actually reached after following any redirects, alongside it. +``` + +**메시지 2**, 조사 결과가 나오면 메인 에이전트로 돌아간다. +``` +Using what bill-the-explorer found, add the effective URL next to the existing elapsed time in HTTPie's --meta output. Add a test that confirms it works for both a redirected and a non-redirected request. +``` + +**메시지 3**, 검증을 위임한다. +``` +/jill-the-test-runner verify the new effective-URL test passes, along with the rest of the test suite. Report any failures separately from the two known pre-existing Big5 charset-detection failures in tests/test_encoding.py, which are unrelated to this change. +``` + +
+ +
Sonnet 5가 조사를 bill-the-explorer에 위임하고, 직접 변경 사항을 구현한 다음, 검증을 jill-the-test-runner에 위임한다. 전 과정이 Token Station을 통해 이루어진다.
+
+ +서브에이전트의 모델 라우팅이 아직 반영되지 않기 때문에, [Token Station 대시보드](https://models.bytefuture.ai/dashboard)에서는 조사와 검증을 포함한 세션 전체가 `anthropic/claude-sonnet-5`로 과금된다. 원래 보여주려던 비용 등급 분리는 아니다. 이 영상이 실제로 보여주는 것은 이렇다. `bill-the-explorer`는 철저히 읽기 전용으로 동작하며 코드를 바꾸기 전에 결과를 보고하고, `jill-the-test-runner`는 그 이후에 동작해 검증한다. 역할이 뚜렷이 나뉜 작업이 순서대로 이루어지고 있지만, 아직 가격까지 나뉘지는 않았다는 뜻이다. + +## 지금 되는 것 + +Chat 모드와 Agent 모드 모두에서 Sonnet 5와 Haiku는 Token Station을 통해 Cursor 안에서 사용할 수 있다. 실제 응답, 실제 파일 편집이 이루어지고, Token Station 키에 정확히 과금되며, 대시보드에서도 확인된다. -Chat 모드와 Ask 모드에서 Sol, Terra, Luna를 쓰는 것은 위에서 설명한 대로 작동한다. 실제 응답이 오고, Token Station 키에 정확히 과금되며, 대시보드에서도 확인된다. +서브에이전트는 역할 구분과 권한 관리 면에서는 작동한다. `name`, `description`, `readonly`는 모두 제대로 반영되고, 자동 위임과 명시적 호출(`/name`) 모두 실제 위임을 트리거한다. 다만 서브에이전트 단위의 모델 라우팅은 커스텀 모델에 대해서는 아직 작동하지 않는다. Cursor의 Task 도구는 `inherit`나 자체 `composer-2.5-fast`만 받아들이기 때문에, 프론트매터의 `model:`에 무엇을 지정하든 모든 서브에이전트는 부모 대화가 사용 중인 모델로 동작한다. 이는 Cursor 플랫폼 자체의 제약이며, 에이전트 스스로 직접 확인해준 내용이고 다른 곳의 독립적인 보고와도 일치한다. Token Station이나 Haiku에 국한된 문제가 아니다. -완전한 Agent 모드의 자율성, 즉 모델이 직접 코드베이스를 읽고 변경 사항을 써넣는 부분은 이야기가 다르다. 우리의 테스트에서는, Override Base URL을 통해 추가한 커스텀 OpenAI 호환 모델이 Agent 모드에서 코드를 읽고 논의할 수는 있었지만, 어떤 Cursor 모드를 시도하든 실제 파일 편집을 적용하는 데는 일관되게 실패했다. 이는 같은 벽에 부딪힌 다른 사용자들의 보고와도 일치한다. Cursor의 Agent 도구 호출 체계는 특정한 요청과 응답 형식을 기대하는데, 표준 OpenAI 호환 엔드포인트가 Cursor 자체 호스팅 모델과 똑같이 그 형식을 주고받는다는 보장은 없다. 이는 Token Station만의 문제가 아니다. 같은 `openai/gpt-5.6-*` 라우트가 Codex에서는 이미 실제 agentic 도구 호출을 구동하고 있으므로, 모델이나 엔드포인트 자체가 병목은 아니다. +이전에 Token Station의 GPT-5.6 라우트(Sol, Terra, Luna)를 테스트했을 때는, Agent 모드에서 코드를 읽고 논의할 수는 있었지만 실제 파일 편집을 적용하는 데는 계속 실패했다. 이는 Cursor 쪽의 고정된 제약이 아니라 Token Station 쪽의 도구 호출 응답 형식 문제였다. 이 라우트들에 대한 지원은 현재 진행 중이다. 지금 당장 Cursor에서 안정적으로 파일을 편집하는 코딩 에이전트가 필요하다면, GPT-5.6 계열 대신 `anthropic/claude-sonnet-5`와 `anthropic/claude-haiku-4-5`를 사용하자. -실제로 파일을 편집하는 에이전트가 워크플로에 필요하다면, Token Station의 Codex, Claude Code, OpenClaw 연동이 현재 검증된 방법이다. Cursor의 BYOK Agent 모드 지원이 따라잡을 때까지는, Cursor는 에디터 안에서 Sol, Terra, Luna와 대화하고 비용 등급이 다른 서브에이전트로 채팅 기반 위임을 하기에 좋은 방법이다. +Token Station의 xAI 라우트인 `xai/grok-4.6`도 같은 커스텀 프로바이더 설정으로 Cursor에서 사용할 수 있다. 메인 코딩 역할에 Grok을 써보고 싶다면 이 라우트를 쓰면 된다. ## 시작하기 -[models.bytefuture.ai](https://models.bytefuture.ai/signup)에서 가입하자. 1달러 무료 크레딧, 카드 불필요, 첫 충전 시 최대 50달러 보너스도 받을 수 있다. 키를 export하고 Cursor의 Models 설정에 연결한 다음, 세 가지 라우트를 추가하자. +[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 index b8e3ebc..b472f42 100644 --- a/src/content/writings/zh/route-cursor-through-token-station.md +++ b/src/content/writings/zh/route-cursor-through-token-station.md @@ -1,16 +1,16 @@ --- 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/ 前缀。" +title: "在 Cursor 中接入 Token Station：Claude Sonnet 5 和 Haiku" +summary: "Cursor 在设置里的 Models 面板支持自定义 OpenAI 兼容 provider。把它指向 Token Station，Claude Sonnet 5 和 Haiku 就会作为可选模型出现，并且完整支持 Agent 模式：真正的文件编辑，不只是聊天，还带有用于委派研究和验证的专门 subagent。" category: "tutorial" -date: "2026-08-13" +date: "2026-08-21" 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 在 Settings → Models 里支持自定义 OpenAI 兼容 provider。把它指向 Token Station 的端点，就能把 Claude Sonnet 5 和 Haiku 添加为可选模型，全部通过你自己的 Token Station key 计费。和 Token Station 上的其他一些模型家族不同，这两个模型完整支持 Cursor 的 Agent 模式：真正的文件编辑，不只是聊天。下面是完整的配置流程，包括我们自己踩过的一个命名坑，最后还会跑一次真实的编码会话：Sonnet 5 在一个开源项目里实现一个真实功能，把研究和验证工作委派给两个专门定制的 subagent。 ## 开始之前需要准备什么 @@ -32,49 +32,43 @@ Cursor 在 Settings → Models 里支持自定义 OpenAI 兼容 provider。把
在 Cursor 的 Models 设置里，把 Token Station 注册为自定义 OpenAI 兼容 provider。
-**值得了解的已知 bug**：在当前的 Cursor 版本（3.15.x）中，这两个字段有时点击后无法接受键盘输入。如果打字没反应，先点一下面板里的其他地方，然后连续按 **Tab** 键，直到焦点落在目标字段上。一旦通过 Tab 聚焦，打字和 **Ctrl+V** 粘贴都能正常工作。这是一个官方承认的回归问题，不是你的设置出了什么问题。 - 不要指望靠一个"Verify"按钮来确认密钥和地址是否正确。它不一定总会出现，即使出现了也不能覆盖所有路径。真正可靠的确认方式是步骤 2：添加一个模型，然后真的给它发一条消息。 -## 步骤 2：将三个 GPT-5.6 路由添加为自定义模型 +## 步骤 2：将 Claude Sonnet 5 和 Haiku 添加为自定义模型 -还是在 Models 设置里，点击 **+ Add Custom Model** 三次，依次添加： +还是在 Models 设置里，点击 **+ Add Custom Model** 两次，依次添加： ``` -openai/gpt-5.6-sol -openai/gpt-5.6-terra -openai/gpt-5.6-luna +anthropic/claude-sonnet-5 +anthropic/claude-haiku-4-5 ```
-
添加 openai/gpt-5.6-sol、openai/gpt-5.6-terra、openai/gpt-5.6-luna 三个自定义模型。
+
添加 anthropic/claude-sonnet-5 和 anthropic/claude-haiku-4-5 两个自定义模型。
-**这里的坑**：你在这里注册的名字，Cursor 会原样作为请求里的 `model` 字段发出去。Token Station 真实的路由名称里包含 `openai/` 前缀。如果你把模型注册成不带前缀的 `gpt-5.6-sol`，每个请求都会失败，报错 `Model 'gpt-5.6-sol' not found`，因为不带前缀的这个模型确实不存在。带上前缀注册，立刻就能用。 +**这里的坑**：你在这里注册的名字，Cursor 会原样作为请求里的 `model` 字段发出去。Token Station 真实的路由名称里包含 `anthropic/` 前缀。如果你把模型注册成不带前缀的 `claude-sonnet-5`，每个请求都会失败，报错 `Model 'claude-sonnet-5' 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 +| `anthropic/claude-sonnet-5` | 主力编码模型：规划、实现，以及 Agent 模式下的文件编辑。 | +| `anthropic/claude-haiku-4-5` | 一个更便宜的模型，可以直接把主对话切换过去处理较轻量的单轮问题。至于为什么它目前还不能作为 subagent 的低成本档位，见步骤 3。 | -Cursor 支持 subagent：带 YAML frontmatter 的 markdown 文件，可以按项目放在 `.cursor/agents/` 下，也可以全局放在 `~/.cursor/agents/` 下，每个都有自己的 `model` 字段。这让你可以把特定的、范围明确的委派任务指向比主对话更便宜的模型。 +## 步骤 3：定义范围明确的 subagent -对编码场景来说，有两个角色很实用，都用 Luna： +Cursor 支持 subagent：带 YAML frontmatter 的 markdown 文件，可以按项目放在 `.cursor/agents/` 下，也可以全局放在 `~/.cursor/agents/` 下。对编码场景来说，有两个角色很实用：一个只读的研究者，一个在改动之后负责验证的测试执行者。 -**`.cursor/agents/explore.md`** +**`.cursor/agents/bill-the-explorer.md`** ```markdown --- -name: explore +name: bill-the-explorer description: Searches and reads the codebase to answer questions about existing code. Use proactively before implementing anything unfamiliar. -model: openai/gpt-5.6-luna +model: anthropic/claude-haiku-4-5 readonly: true --- @@ -82,41 +76,79 @@ 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`** +**`.cursor/agents/jill-the-test-runner.md`** ```markdown --- -name: test-runner +name: jill-the-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 +model: anthropic/claude-haiku-4-5 --- You run the project's test command, capture output, and report which tests passed or failed and why. Do not modify source files. ``` +**给 subagent 起名时，避免和 Cursor 自带的某个 agent 撞名。** 我们最初用的是 `explore`，结果 Cursor 悄悄路由到了它自己同名的内置 agent，而不是我们定义的这个，也没有任何报错来解释为什么我们指定的东西完全不起作用。`bill-the-explorer` 和 `jill-the-test-runner` 避免了这个撞名问题。 +
-
创建 explore 和 test-runner 两个 subagent，都使用 openai/gpt-5.6-luna。
+
创建 bill-the-explorer 和 jill-the-test-runner 两个 subagent。
-`explore` 上的 `readonly: true` 会阻止文件编辑和会改变状态的 shell 命令，这正好符合纯研究角色的定位。`test-runner` 需要真正执行测试命令，所以没有加这个限制，而是在指令里告诉它不要碰源代码文件。 +`bill-the-explorer` 上的 `readonly: true` 会阻止文件编辑和会改变状态的 shell 命令，这正好符合纯研究角色的定位。`jill-the-test-runner` 需要真正执行测试命令，所以没有加这个限制，而是在指令里告诉它不要碰源代码文件。 -在对话里触发 subagent 有两种方式：自动委派，即主 agent 读取 `description` 字段自行判断何时该交给它；或者用 `/explore`、`/test-runner` 显式调用。 +**关于那一行 `model:`。** 这是有效的、文档化的 Cursor 语法，我们把两个 subagent 都设成了 `anthropic/claude-haiku-4-5`，本来预期它们的计费能和主对话分出档位。但并没有发生。直接问负责这次会话的 agent 为什么，它给出了一个很精确的答案：它用来运行 subagent 的 Task 工具，只接受来自一个固定白名单的 `model` 参数，目前是 `inherit` 或者 Cursor 自己的 `composer-2.5-fast`，根本不会读取自定义 agent 文件里的 `model:` frontmatter。既然没有可用的自定义值可传，它就默认用 `inherit`，也就是说每个 subagent 都运行在主对话当前所用的模型上，在这套配置里就是 Sonnet 5，而不是 Haiku。`name`、`description` 和 `readonly` 都会被正确识别并生效；`model` 目前不会，而且不只是 Haiku，任何自定义模型都是如此。这和 Cursor 自己社区论坛上的多份独立反馈是一致的，所以这是一个已知的、当前存在的限制，不是这套设置特有的问题。 + +这样一来，subagent 依然对按角色和权限划分委派任务很有用：一个只读的研究者，一个只负责报告的测试执行者，既可以自动委派（主 agent 读取每个 `description` 字段自行判断何时该交给它），也可以用 `/bill-the-explorer` 或 `/jill-the-test-runner` 显式调用。只是目前它还不能给这部分委派工作带来更便宜的模型。 如果你是在对话里让 agent 帮你写这两个文件，而不是自己在终端里写，写完后侧边栏依然显示没有 subagent，重新加载一下窗口（**Ctrl+Shift+P → "Reload Window"**）：Cursor 不会总是实时重新扫描 `.cursor/agents/`。 -## 目前能用的，和目前还不能用的 +## 步骤 4：看它实现一个真实功能 + +有了 provider、模型和 subagent，Sonnet 5 就能跑一次完整的编码会话：研究、实现、验证，中间的只读和验证步骤都交给对应的 subagent。 + +我们用 [httpie](https://github.com/httpie/httpie) 作为目标，一个真实的、规模适中、测试完善的开源项目。httpie 的 `--meta`/`-m` 参数会打印请求的耗时，但目前还不会显示跟随重定向后实际到达的 URL。这是一个很小、范围明确、真正有用的功能，也正是那种需要先看一眼现有代码，再动手实现的任务。 + +事实证明，显式调用才是触发委派的可靠方式。用大白话说"用 explore subagent 来做"并不会真的发生委派；主 agent 只是一边在自己的上下文里干活，一边口头上说自己委派了。把 subagent 名字加上斜杠前缀、作为独立的一条消息发出去，这样才管用： + +**消息 1**，委派研究工作： +``` +/bill-the-explorer find how elapsed time is computed and displayed in HTTPie's --meta output, and identify where to add the effective URL, the URL actually reached after following any redirects, alongside it. +``` + +**消息 2**，研究结果出来后，回到主 agent： +``` +Using what bill-the-explorer found, add the effective URL next to the existing elapsed time in HTTPie's --meta output. Add a test that confirms it works for both a redirected and a non-redirected request. +``` + +**消息 3**，委派验证工作： +``` +/jill-the-test-runner verify the new effective-URL test passes, along with the rest of the test suite. Report any failures separately from the two known pre-existing Big5 charset-detection failures in tests/test_encoding.py, which are unrelated to this change. +``` + +
+ +
Sonnet 5 把研究工作委派给 bill-the-explorer，自己实现改动，再把验证工作委派给 jill-the-test-runner，全程通过 Token Station。
+
+ +由于 subagent 的模型路由目前还不会被遵循，整场会话在 [Token Station 控制台](https://models.bytefuture.ai/dashboard) 上都计费为 `anthropic/claude-sonnet-5`，研究和验证也不例外，而不是我们最初想展示的那种成本分层。这段视频真正展示出来的是：`bill-the-explorer` 严格只读地运行，在任何代码改动之前先汇报情况；`jill-the-test-runner` 在改动之后运行来验证结果；两个角色分工明确、依序执行，只是暂时还没有体现在价格上。 + +## 目前能用的 + +Chat 模式和 Agent 模式下，Sonnet 5 和 Haiku 通过 Token Station 在 Cursor 里都能用：真实的回复、真实的文件编辑，正确计入你的 Token Station 密钥，并显示在控制台里。 -Chat 和 Ask 模式下用 Sol、Terra、Luna，效果和上面描述的一致：真实的回复，正确计入你的 Token Station 密钥，并显示在控制台里。 +subagent 在角色划分和权限控制上是能用的，`name`、`description` 和 `readonly` 都会被正确识别，自动委派和显式调用（`/name`）也都能触发真正的委派。但目前 subagent 层面的模型路由对自定义模型不起作用：Cursor 的 Task 工具只接受 `inherit` 或它自己的 `composer-2.5-fast`，所以不管 frontmatter 里的 `model:` 写的是什么，每个 subagent 都运行在主对话所用的模型上。这是 Cursor 平台本身的限制，由 agent 本身直接证实，也和其他地方的独立反馈一致，并不是 Token Station 或 Haiku 特有的问题。 -完整的 Agent 模式自主性，也就是模型直接读取你的代码库并写入改动，则是另一回事。在我们的测试中，通过 Override Base URL 添加的自定义 OpenAI 兼容模型，在 Agent 模式下可以读取和讨论代码，但无论我们试过哪种 Cursor 模式，都始终无法真正应用任何文件编辑。这和其他用户遇到同一堵墙的反馈是一致的：Cursor 的 Agent 工具调用机制需要特定的请求和响应格式，而标准的 OpenAI 兼容端点不一定能像 Cursor 自家托管的模型那样完整地往返这套格式。这不是 Token Station 特有的问题：同样的 `openai/gpt-5.6-*` 路由已经在 Codex 里驱动真实的 agentic 工具调用，模型和端点本身都不是这里的瓶颈。 +早些时候对 Token Station 的 GPT-5.6 路由（Sol、Terra、Luna）的测试发现，Agent 模式下它们能读取和讨论代码，但始终无法真正应用文件编辑，这是 Token Station 一侧的工具调用响应格式问题，而不是 Cursor 的硬性限制。对这几个路由的支持正在推进中。如果你现在就需要一个能在 Cursor 里可靠编辑文件的编码 agent，请使用 `anthropic/claude-sonnet-5` 和 `anthropic/claude-haiku-4-5`，而不是 GPT-5.6 系列。 -如果你的工作流需要一个真正能编辑文件的 agent，Token Station 在 Codex、Claude Code 和 OpenClaw 上的集成是目前已验证可行的路径。在 Cursor 的 BYOK Agent 模式支持跟上之前，Cursor 是一个在编辑器里和 Sol、Terra、Luna 对话、并用分成本档位的 subagent 做对话式委派的可靠方式。 +Token Station 的 xAI 路由 `xai/grok-4.6`，也可以通过同样的自定义 provider 设置在 Cursor 里使用，如果你想让 Grok 来担任主力编码模型的话。 ## 开始使用 -前往 [models.bytefuture.ai](https://models.bytefuture.ai/signup) 注册：1 美元免费额度，无需信用卡，首次充值最高可再获得 50 美元奖励。导出你的密钥，接入 Cursor 的 Models 设置，添加这三个路由。 +前往 [models.bytefuture.ai](https://models.bytefuture.ai/signup) 注册：1 美元免费额度，无需信用卡，首次充值最高可再获得 50 美元奖励。导出你的密钥，接入 Cursor 的 Models 设置，添加这两个路由。 [试用 Token Station](https://models.bytefuture.ai/intro.html)