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, 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~/.zshrcin an editor, such as by runningnano ~/.zshrcorvim ~/.zshrc. - If the output is
/bin/bash, open~/.bashrcin an editor, such as by runningnano ~/.bashrcorvim ~/.bashrc.
- If the output is
Open the shell configuration file. The following example uses zsh. Append the following content to the end of the file.
Note
Replace
sk_xxxxwith 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_TOKENfrom 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 tokendisplaysANTHROPIC_AUTH_TOKEN, indicating that the authentication credentials were read from the environment variable.Anthropic base URLdisplays 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
/modelto switch models and/statusto view the connection status. - After modifying the configuration, completely exit and restart VS Code.
Troubleshooting
API Key invalid or authentication failed
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 -rf ~/.claude/settings.json
source ~/.zshrc
claude
Connection failure
- Check whether your network can access
ai-api-g.oceanbase.com. - Confirm that
ANTHROPIC_BASE_URLis set tohttps://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_TOKENin both the Shell andsettings.json. - View detailed logs in the View > Output > Claude Code channel.
- Enter
/statusin the chat interface to confirm the endpoint and authentication method.