> For the complete documentation index, see [llms.txt](https://docs.nexos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexos.ai/gateway-api/integrations/claude-code.md). # Claude Code Integration Learn how to connect Claude Code to the nexos.ai API Gateway using environment variables, and set default models per task. Connecting Claude Code to nexos.ai lets you route every prompt through the gateway instead of authenticating directly with Anthropic, giving you access to any model in your workspace. This guide walks through installation, connection, model configuration, and troubleshooting. ## What is Claude Code? Claude Code is an AI-powered coding assistant designed to help developers write, understand, and improve code more efficiently. Built on Anthropic's Claude models, it provides interactive coding support directly within your development workflow. Claude Code can generate code, explain existing logic, refactor functions, create tests, and assist with debugging through natural-language interactions. It is commonly used to accelerate development, improve code quality, and support engineers in navigating complex codebases. ### **Claude Code key features** * **Intelligent Code Generation** Produces high-quality code snippets, functions, and modules based on natural-language prompts, helping developers move faster. * **Code Explanation & Understanding** Provides clear explanations of complex code blocks, libraries, or architectural patterns to improve comprehension and onboarding. * **Refactoring & Optimization** Suggests cleaner, more efficient, or more idiomatic implementations while preserving existing functionality. * **Automated Test Creation** Generates unit tests, integration tests, and edge-case scenarios to improve code reliability and coverage. * **Debugging Assistance** Helps identify potential bugs, logic issues, or problematic patterns and proposes fixes. * **Documentation Support** Creates or updates documentation, docstrings, READMEs, and comments directly from code. * **Multi-Language Support** Works across a wide range of programming languages, adapting to ecosystem conventions and best practices. * **Context-Aware Development** Uses project context files, codebase structure, and error logs to deliver highly relevant responses. * **Interactive Cooperative Workflow** Works like a coding partner. Developers can iterate, review, and refine code through conversational interactions. ## How to Connect Claude Code and nexos.ai API nexos.ai now exposes an endpoint compatible with the Anthropic Messages API, so Claude Code talks to the gateway directly. You no longer need a local proxy or the Claude Code Router. To connect your nexos.ai **API** and **Claude Code**, follow these steps: ### 1. Install Claude Code **macOS, Linux, WSL:** ```bash curl -fsSL https://claude.ai/install.sh | bash ``` **Windows PowerShell:** ```powershell irm https://claude.ai/install.ps1 | iex ``` Or install it with npm: ```bash npm install -g @anthropic-ai/claude-code ``` ### 2. Connect Claude Code to nexos.ai Instead of logging in with Anthropic directly, point Claude Code at the nexos.ai gateway. This is done with a few environment variables. **Requirements:** 1. Use `https://api.nexos.ai` as the base URL. Claude Code appends `/v1/messages` automatically. 2. Provide your API key as the auth token. 3. **Important:** Explicitly blank out the Anthropic API key to avoid conflicts. Add these lines to your shell profile such as `~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish`: ```bash export ANTHROPIC_BASE_URL="https://api.nexos.ai" export ANTHROPIC_AUTH_TOKEN="{YOUR_API_KEY}" export ANTHROPIC_API_KEY="" # Important: must be explicitly empty ``` After saving, restart your terminal so the changes take effect. {% hint style="warning" %} Do not put these values in a project-level `.env` file. The native Claude Code installer does not read standard `.env` files. {% endhint %} ### 3. Clear any cached Anthropic login If you were previously logged in to Claude Code with an Anthropic account, run `/logout` once to remove the cached session. Then quit and relaunch `claude`. A leftover cached login together with `ANTHROPIC_AUTH_TOKEN` can cause confusing model-not-found errors on startup. ``` > /logout ``` If you have never logged in to Claude Code with Anthropic, skip this step. ### 4. Start your session ```bash cd /path/to/your/project claude ``` You are now connected. Every prompt is routed through nexos.ai. ### 5. Verify Run `/status` inside Claude Code to confirm the connection: ``` > /status Auth token: ANTHROPIC_AUTH_TOKEN Anthropic base URL: https://api.nexos.ai ``` ## Configuring models Claude Code uses several environment variables to decide which model to use for each task. Point each role at any model available in your nexos.ai workspace. Use either the model UUID or model name. ```bash export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-1-20250805" export ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic.claude-sonnet-4@20250514" export ANTHROPIC_DEFAULT_HAIKU_MODEL="c958982f-4301-4576-bfd8-b5a83f1f4232" export CLAUDE_CODE_SUBAGENT_MODEL="claude-opus-4-1-20250805" ``` | Variable | Description | | -------------------------------- | ---------------------------------------------------------- | | `ANTHROPIC_DEFAULT_OPUS_MODEL` | Model used for Opus-class tasks such as complex reasoning | | `ANTHROPIC_DEFAULT_SONNET_MODEL` | Model used for Sonnet-class tasks such as general coding | | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Model used for Haiku-class tasks such as quick completions | | `CLAUDE_CODE_SUBAGENT_MODEL` | Model used for sub-agent tasks spawned by Claude Code | Add these to the same shell profile where you set `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN`. Claude Code is optimized for Anthropic models and may not behave correctly with other providers. ## Troubleshooting * **Model-not-found errors:** Usually this is a credential conflict. If you have a cached Anthropic OAuth login, run `/logout`, then quit and relaunch `claude`. If your shell still has a real `ANTHROPIC_API_KEY` set, `/logout` will not help. Make sure `ANTHROPIC_API_KEY=""` is set as shown above and restart your terminal. Verify with `/status`. * **Auth errors:** Ensure `ANTHROPIC_API_KEY` is set to an empty string `""`. If it is unset, Claude Code may fall back to authenticating against Anthropic's servers. * **Context length errors:** Break the task into smaller chunks or start a new session. ## FAQ ### Which other integrations are available in nexos.ai Gateway? nexos.ai Gateway supports integrations with the following coding tools: * [CrewAI](https://docs.nexos.ai/gateway-api/integrations/crewai) * [Codex CLI](https://docs.nexos.ai/gateway-api/integrations/codex-cli) * [OpenCode](https://docs.nexos.ai/gateway-api/integrations/opencode) * [Claude Cowork](https://docs.nexos.ai/gateway-api/integrations/claude-cowork) * [Bubble](https://docs.nexos.ai/gateway-api/integrations/bubble) * [GitLab CI](https://docs.nexos.ai/gateway-api/integrations/gitlab-ci) * [OpenAI Agents SDK](https://docs.nexos.ai/gateway-api/integrations/openai-agents-sdk) * [Vercel AI SDK](https://docs.nexos.ai/gateway-api/integrations/vercel-ai-sdk) * [Streamlit](https://docs.nexos.ai/gateway-api/integrations/streamlit) * [ProxyAI](https://docs.nexos.ai/gateway-api/integrations/proxyai) * [Langfuse](https://docs.nexos.ai/gateway-api/integrations/langfuse) * [LangGraph](https://docs.nexos.ai/gateway-api/integrations/langgraph) * [LangChain](https://docs.nexos.ai/gateway-api/integrations/langchain) * [Roo Code](https://docs.nexos.ai/gateway-api/integrations/roo-code) * [n8n](https://docs.nexos.ai/gateway-api/integrations/n8n) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.nexos.ai/gateway-api/integrations/claude-code.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.