Use Claude Code with OceanBase MaaS|OceanBase Cloud |docs|OceanBase Documentations

This topic describes how to use Claude Code through the OceanBase MaaS gateway.

Configuration instructions

Claude Code is an AI coding agent developed by Anthropic. The OceanBase MaaS gateway is fully compatible with the Anthropic Messages API. You do not need to modify Claude Code. After configuring ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN, you can route Claude Code requests to the MaaS gateway and access Claude models using an API key issued by OceanBase MaaS.

Item	Value
Gateway URL	`https://ai-api-g.oceanbase.com/api`
Authentication method	The API key issued by MaaS (`sk_` prefix). For more information, see Manage AI API keys
Protocol	Compatible with Anthropic Messages API

Note

Important change in Claude Code v2.0.7x: The env configuration in ~/.claude/settings.json may not be loaded reliably during the initial sign-in or after signing out and signing in again. Therefore, it is recommended to configure environment variables in a shell configuration file, such as ~/.zshrc or ~/.bashrc, to ensure that both authentication and requests are routed through the MaaS gateway.

Install and use from command-line

VS Code extension

Install, configure, and start Claude Code from a terminal. This method is suitable for developers who prefer command-line operations.

Install Claude Code

Note

We recommend using a native installation method, such as curl or Homebrew, for better compatibility and automatic updates. You can still install Claude Code using npm or pnpm, but you may encounter Node.js version compatibility issues. We recommend migrating to a native installation later.

Uninstall earlier version (if installed)

If you installed Claude Code using npm or pnpm, you can migrate it to a native installation.

claude install

To uninstall an earlier version, run one of the following commands based on the installation method.

npm uninstall -g @anthropic-ai/claude-code
# Or
pnpm uninstall -g @anthropic-ai/claude-code

Installation methods

You can install Claude Code using the installation script or Homebrew.

Use installation script (Recommended)

curl -fsSL https://claude.ai/install.sh | bash

Use Homebrew (manual upgrades require brew upgrade claude-code)

brew install --cask claude-code

After installation, run claude doctor to check the installation status.

Configuration steps

Obtain MaaS API key

Apply for an API key in the OceanBase MaaS console or through your internal process. The API key typically follows the format sk_xxxx. Store the API key securely and never commit it to a code repository. For specific procedures, see Manage AI API Keys.

Configure shell environment variables (Recommended)

Configure environment variables in a shell configuration file so that Claude Code can automatically read the MaaS gateway URL and API key each time you open a terminal.

Identify the shell you are using.
```
echo "$SHELL"
```
- If the output is /bin/zsh, open ~/.zshrc in an editor, such as by running nano ~/.zshrc or vim ~/.zshrc.
- If the output is /bin/bash, open ~/.bashrc in an editor, such as by running nano ~/.bashrc or vim ~/.bashrc.

Open the shell configuration file. The following example uses zsh. Append the following content to the end of the file.

Note

Replace sk_xxxx with the actual API key obtained from the MaaS console. For information about how to obtain API Key, see Manage AI API keys.

# ============= OceanBase MaaS + Claude Code configuration =============
# Route Claude Code requests to the MaaS gateway instead of the official Anthropic service

# Core configuration: Gateway URL and authentication credentials
export ANTHROPIC_BASE_URL="https://ai-api-g.oceanbase.com/api"
export ANTHROPIC_AUTH_TOKEN="sk_xxxx"   # Replace with your MaaS API key

# Avoid conflicts: Explicitly clear ANTHROPIC_API_KEY if it is already set
export ANTHROPIC_API_KEY=""

# Performance optimization (strongly recommended): Disable non-essential traffic and experimental features to reduce latency
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"

# Optional: API request timeout in milliseconds
export API_TIMEOUT_MS="30000000"

# Optional: Specify the default model for each tier. See "Model configuration" below
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"

Apply the configuration.

source ~/.zshrc   # zsh
# Or
source ~/.bashrc  # bash
# Alternatively, restart the terminal

Environment variables

Variable	Requirement	Description
`ANTHROPIC_BASE_URL`	Required	MaaS endpoint compatible with the Anthropic API.
`ANTHROPIC_AUTH_TOKEN`	Required	MaaS API key.
`ANTHROPIC_API_KEY`	Recommended	Set this variable to an empty string, that is `""`, to avoid conflicts with earlier configurations.
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	Recommended	Disables non-essential traffic to reduce request latency.
`API_TIMEOUT_MS`	Optional	API request timeout in milliseconds.
`ANTHROPIC_DEFAULT_*_MODEL`	Optional	Customizes the default Haiku, Sonnet, and Opus models.

Start Claude Code

cd /path/to/your/project
claude

Upon first startup, Claude Code will:

Read the ANTHROPIC_AUTH_TOKEN from environment variables.
Complete authentication through the MaaS gateway pointed to by ANTHROPIC_BASE_URL.
Be available for use without additional login steps.

If command not found: claude is prompted, ensure global installation has been completed as described above.

Verify connection

Enter /status at the Claude Code prompt. Claude Code should display output similar to the following.

Auth token: ANTHROPIC_AUTH_TOKEN
Anthropic base URL: https://ai-api-g.oceanbase.com/api

Auth token displays ANTHROPIC_AUTH_TOKEN, indicating that the authentication credentials were read from the environment variable.
Anthropic base URL displays the MaaS gateway URL.

Model configuration

If ANTHROPIC_DEFAULT_*_MODEL is not configured, Claude Code uses its built-in default Claude model mappings.

Use Claude model aliases (Recommended)

For official Claude models, we recommend using model aliases recognized by Claude Code, such as claude-sonnet-4-6, to correctly enable native features such as the 1M context window and effort controls.

export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"    # Fast tier
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"  # Balanced tier
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"      # Powerful tier

Note

Claude Code identifies model names to enable features such as the 1M context window. Using a full model ID with a provider prefix, such as anthropic/claude-sonnet-4.6, may cause model-name matching to fail and prevent related features from being enabled correctly.

After modifying the configuration, run source ~/.zshrc and restart Claude Code.

During a session, use the /model command to view or switch the current model.

Install the Claude Code extension in VS Code and use it through the IDE. This method is suitable for developers who prefer a graphical interface.

Claude Code extension for VS Code

In addition to the command line, you can install Claude Code Extension in VS Code.

Configure settings.json

In VS Code settings, click Edit in settings.json and add the following configuration:

{
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": "https://ai-api-g.oceanbase.com/api"
    },
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value": "sk_xxxx"
    },
    {
      "name": "ANTHROPIC_API_KEY",
      "value": ""
    },
    {
      "name": "API_TIMEOUT_MS",
      "value": "30000000"
    },
    {
      "name": "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC",
      "value": "1"
    }
  ]
}

Configuration precedence: Environment variables in the VS Code settings.json file take precedence over the shell configuration. When using the extension, we recommend maintaining the configuration in only one location to avoid conflicts.

Usage tips:

When using the extension for the first time, trust the workspace by selecting Trust This Folder.
Use /model to switch models and /status to view the connection status.
After modifying the configuration, completely exit and restart VS Code.

Troubleshooting

Invalid API key or authentication failure

Confirm that the API key begins with sk_ and does not contain extra spaces or newline characters.
Confirm that the API key is enabled in the MaaS console.
Verify that the environment variables are loaded.

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN
echo $ANTHROPIC_API_KEY   # This should be empty

If the output is not as expected, run source ~/.zshrc again or restart the terminal.

Authentication failure after switching from another platform

An earlier configuration may cause an authentication conflict. Clear the earlier configuration and configure Claude Code again.

rm -f ~/.claude/settings.json
source ~/.zshrc
claude

Connection failure

Check whether your network can access ai-api-g.oceanbase.com.
Confirm that ANTHROPIC_BASE_URL is set to https://ai-api-g.oceanbase.com/api.
Check whether a firewall or proxy is blocking outbound connections.

1M context window is not enabled

Confirm that you are using the model alias claude-sonnet-4-6 instead of a full model ID with a provider prefix.

# 1M context window may not be enabled
export ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic/claude-sonnet-4.6"

# Correct
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"

VS Code extension authentication issues

Open Settings > Claude Code > Edit in settings.json and verify claudeCode.environmentVariables.
Avoid setting ANTHROPIC_AUTH_TOKEN in both the Shell and settings.json.
View detailed logs in the View > Output > Claude Code channel.
Enter /status in the chat interface to confirm the endpoint and authentication method.