---
title: "Use Autohand models in Codex"
source: https://docs.autohand.ai/integrations/coding-agents/codex
---

# Use Autohand models in Codex

Run Codex on Autohand Fantail and Moa through a local proxy that translates the Responses API to Chat Completions.

Quick answer

## How do I use Autohand models in Codex?

Run a local LiteLLM proxy that turns Codex Responses API requests into Autohand Chat Completions requests. Then add an `autohand` model provider to `~/.codex/config.toml` that points at the proxy, and set `model = "fantail"`.

Status

Works through a local proxy

Requires

An Autohand account, an Autohand API key, Codex CLI, and uv to run LiteLLM.

Configure with

`~/.codex/config.toml`: `model_providers.autohand` with `wire_api = "responses"`.

Subagents

`[agents] default_subagent_model = "fantail"`

**Know before you start:** Current Codex releases send requests only to the Responses API. Codex 0.154 rejects `wire_api = "chat"`, and the Autohand API serves Chat Completions, so Codex needs the proxy in this guide.

## Prerequisites

-   An Autohand account. [Sign up or sign in to Console](https://console.autohand.ai/). The Free plan includes Fantail. Moa requires the Pro plan or above.
-   An Autohand API key. The first step shows how to create one.
-   Codex CLI. Run `codex --version` to check the installed version. This guide was tested with Codex CLI 0.154.0.

## Step 1: Create an Autohand API key

1.  Sign in to [Autohand Console](https://console.autohand.ai/).
2.  Open [API Keys](https://console.autohand.ai/api-keys) and select **Create API Key**.
3.  Enter a name that identifies the agent and machine, for example `codex-laptop`.
4.  Select **Create Key** and copy the value. Console shows the key only once.

## Step 2: Store the key

Store the key in the `AUTOHAND_API_KEY` environment variable. Add the line to your shell profile so new terminals keep it. Do not commit the key to a repository.

```bash
# macOS or Linux: add to ~/.zshrc or ~/.bashrc
export AUTOHAND_API_KEY="your-autohand-api-key"
```

```powershell
# Windows PowerShell: saves the variable for new sessions
[Environment]::SetEnvironmentVariable("AUTOHAND_API_KEY", "your-autohand-api-key", "User")
```

Confirm that the key works before you configure the agent. The request lists the models your plan can use.

```bash
curl https://api.autohand.ai/v1/models \
  -H "Authorization: Bearer $AUTOHAND_API_KEY"
```

## Step 3: Run a local LiteLLM proxy

The proxy accepts Responses API requests on `/v1/responses` and forwards them to the Autohand Chat Completions API. It uses the `custom_openai` provider in LiteLLM, which translates each request to Chat Completions.

1.  Install [uv](https://docs.astral.sh/uv/) if you do not have it. The `uvx` command runs LiteLLM without a permanent install.
2.  Save the following file as `~/.config/autohand/litellm.yaml`:

    ```yaml
    model_list:
      - model_name: fantail
        litellm_params:
          model: custom_openai/fantail
          api_base: https://api.autohand.ai/v1
          api_key: os.environ/AUTOHAND_API_KEY
          additional_drop_params: ["client_metadata"]
      - model_name: moa
        litellm_params:
          model: custom_openai/moa
          api_base: https://api.autohand.ai/v1
          api_key: os.environ/AUTOHAND_API_KEY
          additional_drop_params: ["client_metadata"]

    litellm_settings:
      drop_params: true

    general_settings:
      master_key: os.environ/LITELLM_MASTER_KEY
    ```

3.  Start the proxy in a separate terminal and leave it running:

    ```bash
    # Choose a local key for the proxy. It must start with sk-.
    export LITELLM_MASTER_KEY="sk-autohand-local"

    # Start the proxy on this machine only
    uvx --from 'litellm[proxy]' litellm \
      --config ~/.config/autohand/litellm.yaml \
      --host 127.0.0.1 --port 4000
    ```

The `--host 127.0.0.1` option keeps the proxy off your network, and `master_key` rejects requests that do not send the local key. The `additional_drop_params` entry removes the `client_metadata` field that Codex sends, which the Chat Completions client does not accept. We tested this configuration with LiteLLM 1.102.1.

## Step 4: Add Autohand as a Codex model provider

Open `~/.codex/config.toml` and add the provider. If the file already sets `model` or `model_provider`, replace those lines.

```toml
model = "fantail"
model_provider = "autohand"

[model_providers.autohand]
name = "Autohand"
base_url = "http://127.0.0.1:4000/v1"
env_key = "LITELLM_MASTER_KEY"
wire_api = "responses"
```

| Key | Value | Purpose |
|---|---|---|
| base_url | http://127.0.0.1:4000/v1 | The local LiteLLM proxy |
| env_key | LITELLM_MASTER_KEY | The variable that holds the proxy key. The proxy holds your Autohand key. |
| wire_api | responses | The only request format current Codex releases support |

## Step 5: Choose Fantail or Moa

| Model ID | Use it for | Context | Max output | Plans |
|---|---|---|---|---|
| fantail | Fast agent loops, quick fixes, reviews, and subagents | 256K tokens | 16K tokens | Free and above |
| moa | Planning, large refactors, and repository-wide changes | 1M tokens | 262,144 tokens | Pro and above |

The `model` setting chooses the default. Use the `-m` option to pick a model for one session.

```bash
# Plan a larger change with Moa
codex -m moa "Map the payment flow and propose a refactor plan"
```

## Step 6: Run a test prompt

Keep the proxy running, open a new terminal in a project folder, and run a one-time prompt.

```bash
codex exec "Summarize what this repository does in three sentences"
```

A reply means the full path works: Codex, the proxy, and the Autohand API. The proxy terminal shows each `POST /v1/responses` request.

## Subagents and Fantail

Codex can start subagents for parallel work. Set a default model for them in the `[agents]` section of `~/.codex/config.toml`. Subagents use the same Autohand provider as the main session.

```toml
[agents]
default_subagent_model = "fantail"
```

To give one custom agent its own model, create a file in `~/.codex/agents/` or in the project folder `.codex/agents/`.

```toml
# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviews a change and lists risks before it merges."
model = "fantail"
sandbox_mode = "read-only"
developer_instructions = "Read the diff, list concrete risks, and cite each file and line."
```

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| wire_api = "chat" is no longer supported | The provider uses the removed Chat Completions setting. | Set wire_api = "responses" and point base_url at the proxy. |
| 404 for https://api.autohand.ai/v1/responses | base_url points at Autohand directly. | Point base_url at http://127.0.0.1:4000/v1 and start the proxy. |
| 500 with unexpected keyword argument 'client_metadata' | The proxy config does not drop the Codex metadata field. | Add additional_drop_params: ["client_metadata"] to each model. |
| Codex reconnects and then stops | The proxy is not running, or it uses a different port. | Start the proxy and match the port in base_url. |
| 401 with Credential not recognised | The key is wrong, revoked, or not set in the environment the agent reads. | Create a new key in Console, set AUTOHAND_API_KEY again, and open a new terminal. |
| 401 with Missing Autohand credential | The request reached Autohand without an Authorization header. | Check that the agent reads the variable name shown in this guide. |
| Model not found | The model ID is misspelled, or your plan does not include it. | Use fantail or moa in lowercase. Moa requires the Pro plan or above. |
| Context or output limit errors | The agent uses default limits for a model it does not recognize. | Set the limits for Fantail (262,144 context, 16,000 output) or Moa (1,048,576 context, 262,144 output). |

## Next steps

-   [Use Autohand models in other coding agents](https://docs.autohand.ai/integrations/coding-agents/)
-   [Compare Autohand models](https://docs.autohand.ai/models/)
-   [Fantail model reference](https://docs.autohand.ai/models/fantail/)
-   [Moa model reference](https://docs.autohand.ai/models/moa/)
-   [Create and protect an API key](https://docs.autohand.ai/agent-sdk/api-key-setup)

Common questions

## Codex and Autohand FAQ

### Why does Codex need a proxy for Autohand?

Current Codex releases send requests only to the Responses API, and the Autohand API serves Chat Completions. The LiteLLM proxy translates between them.

### Can Codex subagents use Fantail?

Yes. Set `default_subagent_model = "fantail"` in the `[agents]` section, or set `model` in a custom agent file.

### Does the proxy send my Autohand key to Codex?

No. The proxy reads `AUTOHAND_API_KEY`, and Codex sends only the local proxy key.