# Connect a user's tools to CoreCode

Instructions for an AI coding agent (Claude Code, Codex, Cursor, or another agent) that is setting up CoreCode for the person it works for. Follow them in order. CoreCode (https://corecode.live) is an API relay: Claude Code requests are answered by official Anthropic Claude accounts, and the same key calls GPT and Grok through an OpenAI-compatible API. It is reachable directly from mainland China, without a proxy.

中文用户：这是给 AI 编程助手看的接入步骤，人看的版本在 https://corecode.live/docs/claude-code/ 。

## Rules for the agent

- **Ask the user for the API key. Never guess, invent, or reuse a key from another provider.** A CoreCode key starts with `sk-`. If the user has none, tell them to create one (step 1) and wait.
- Never print the full key back, never write it into a file inside a git repository, and never commit it.
- Edit configuration files by merging: keep every setting already there and change only the keys named below.
- Do not sign in to a claude.ai account and do not set `ANTHROPIC_API_KEY`; both conflict with the relay key.
- Do not set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` or `ENABLE_TOOL_SEARCH=false`. CoreCode passes Anthropic's beta headers through unchanged; the first breaks the one-hour cache, MCP tool search and auto mode's server-side review, the second breaks the cache whenever MCP tools change.

## 1. The user gets a key

The user does this in a browser; the agent cannot.

1. Sign in at https://corecode.live/sign-in (Google, LinuxDO, or an email code).
2. Top up at https://corecode.live/wallet (Alipay, WeChat Pay, a Visa or Mastercard card, or USDT or USDC). Without credit, requests return `403`.
3. Create a key at https://corecode.live/keys and choose its group by the tool it will be used in:

| Tool | Group |
| --- | --- |
| Claude Code CLI, its VS Code or JetBrains plugin, Claude Desktop | Claude Full (Claude Code only) — Chinese console: Claude 满血（仅限CC） — the cheapest |
| Claude from an SDK, curl, Magpie or another tool | Claude Full (any client) — Claude 满血（可外接） |
| Codex | GPT |
| Several vendors with one key | auto |

A Claude Full (Claude Code only) key refuses anything that is not Claude Code with `403`. The group can be changed later under "Edit" without replacing the key. Details: https://corecode.live/docs/en/groups/.

## 2. Claude Code

Check that Claude Code is installed:

```bash
claude --version
```

If it is not, install it (macOS, Linux, WSL: `curl -fsSL https://claude.ai/install.sh | bash`; Windows PowerShell: `irm https://claude.ai/install.ps1 | iex`; or `npm install -g @anthropic-ai/claude-code` with Node.js 22 or later, never with `sudo`).

Merge this `env` section into `~/.claude/settings.json` (on Windows, `%USERPROFILE%\.claude\settings.json`), creating the file if it does not exist. Replace `sk-your-key` with the key the user gave you:

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://corecode.live",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-key"
  }
}
```

If the user is in mainland China, also add `"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"` to `env` (it turns off auto-update, telemetry and other requests to Anthropic's own services, which are unreachable there; upgrade with `claude update`), and add `"hasCompletedOnboarding": true` at the top level of `~/.claude.json` so the first launch does not hang contacting Anthropic.

Then check for conflicts in the user's shell: `echo $ANTHROPIC_API_KEY` (PowerShell: `$env:ANTHROPIC_API_KEY`) must print nothing. If the user signed in to Claude Code with a claude.ai account before, ask them to run `/logout` inside Claude Code.

The VS Code extension and the JetBrains plugin read the same `~/.claude/settings.json`; the user must quit the editor completely and reopen it. Guide: https://corecode.live/docs/en/ide/.

## 3. Verify

Claude Code reads its settings at startup, so run this in a new terminal:

```bash
claude -p "reply ok"
```

A reply of `ok` means it is connected. Inside Claude Code, `/status` shows the Base URL `https://corecode.live`. The request and its cost appear in the console's usage logs at https://corecode.live/usage-logs.

## 4. Codex (GPT), if the user wants it

The key must be in the GPT or auto group. Put this in `~/.codex/config.toml` (on Windows, `%USERPROFILE%\.codex\config.toml`); if the file has content, the `model` and `model_provider` lines go at the top, before any table header. A project's `.codex/config.toml` cannot define providers.

```toml
model = "gpt-6.1-sol"
model_provider = "corecode"

[model_providers.corecode]
name = "CoreCode"
base_url = "https://corecode.live/v1"
env_key = "CORECODE_API_KEY"
wire_api = "responses"
```

Set `CORECODE_API_KEY` to the key in the user's shell profile (or `setx CORECODE_API_KEY …` on Windows), then verify in a new terminal with `codex exec "reply ok"`. Guide: https://corecode.live/docs/en/codex/.

## 5. OpenAI-compatible tools and SDKs, if the user wants them

- Base URL: `https://corecode.live/v1` (some clients append `/v1` themselves and want `https://corecode.live`; if requests return 404, try the other form)
- Header: `Authorization: Bearer sk-your-key`
- APIs: Chat Completions (`/v1/chat/completions`) and Responses (`/v1/responses`), for every model
- Model names: as listed on https://corecode.live/pricing, without a vendor prefix

Test with curl, using a key in the GPT, Grok or auto group:

```bash
curl https://corecode.live/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.7", "messages": [{"role": "user", "content": "reply ok"}]}'
```

For Claude from an SDK, prefer the Anthropic SDK with base URL `https://corecode.live` and a key in Claude Full (any client) or auto. Per-tool guides: https://corecode.live/docs/en/openai/.

## Errors

| Symptom | Cause and fix |
| --- | --- |
| `Unable to connect to Anthropic services` on first launch | Onboarding contacts Anthropic. Add `"hasCompletedOnboarding": true` at the top level of `~/.claude.json` and run `claude` again. |
| `Invalid API key · Please run /login` | Claude Code did not find the relay key. Put both variables in `env` in `~/.claude/settings.json`, check their spelling, and restart Claude Code. Do not run `/login`. |
| `Both a token and an API key are set` | Remove `ANTHROPIC_API_KEY`; keep only `ANTHROPIC_AUTH_TOKEN`. |
| `401` | The key is incomplete, deleted, or from another provider. Ask the user to copy it again from https://corecode.live/keys. |
| `403` insufficient quota | The balance is used up; the user tops up at https://corecode.live/wallet. No setup change is needed. |
| `403` only requests from Claude Code are accepted | The key is in Claude Full (Claude Code only) and the caller is not Claude Code. Use a key in Claude Full (any client) or auto. |
| `403 Request not allowed` | The request went to Anthropic directly, not through CoreCode. Check the Base URL with `/status`. |
| `429` | The key's rate or concurrency limit; Claude Code retries by itself. Run fewer sessions at once. |
| `529 overloaded_error` | Anthropic is temporarily overloaded; Claude Code retries by itself. Check https://corecode.live/status/. |
| Model does not exist, or no available channel | The model name must match https://corecode.live/pricing, and the key's group must serve it. |
| No output for minutes | Extended thinking can go minutes without text; CoreCode's gateway read timeout is 10 minutes. |

Every error: https://corecode.live/docs/en/errors/. If the user is behind a global proxy or VPN, a DIRECT rule for `corecode.live` avoids a detour.

## More

- Guide for AI assistants: https://corecode.live/llms.txt
- All Chinese and English docs as Markdown: https://corecode.live/llms-full.txt
- Check that a relay serves genuine Claude: https://corecode.live/docs/en/verify/
- Support: the console's Feedback page (https://corecode.live/feedback), or WeChat `LianGZiJian_JJ`
