Kimi Code

kimi_local runs Moonshot's Kimi Code CLI (kimi) on the same machine as Paperclip. Use it when you want a local coding agent that streams a structured live transcript, resumes sessions across heartbeats, and gets your Paperclip skills injected without polluting your own Kimi skills home.

Kimi Code runs on the same shared ACP engine as Claude, Codex, and Gemini by default, and falls back to a headless CLI lane when ACP prerequisites are missing.

When To Use

• You already run the Kimi Code CLI on the host machine.
• You want session continuity across heartbeats (-r <session_id>).
• You want Paperclip skills injected into the Kimi skills home without touching the agent workspace.

When Not To Use

• The runtime lives behind a webhook or remote API. Use HTTP or OpenClaw Gateway.
• You only need a shell command or script. Use Process.
• Kimi Code CLI is not installed or cannot be executed from the Paperclip host.

Common Fields

Note: The adapter sets a headless-safe environment (CI=1, NO_COLOR=1, KIMI_CODE_NO_AUTO_UPDATE=1) so unattended runs never wait on an interactive prompt or an update preflight.

ACP Engine

Kimi Code runs through one of two lanes, selected by the engine field:

• ACP (the default). Paperclip runs Kimi through the Agent Client Protocol (kimi acp), giving you a structured live transcript — session identity, status with context-window usage, assistant and thinking token deltas, and tool-call updates that fold into a single card as they progress. This is the same machinery Claude, Codex, and Gemini use.
• CLI (the fallback). When ACP prerequisites are unavailable, the adapter automatically falls back to the headless CLI lane. It runs kimi -p with --output-format stream-json for non-interactive execution; the prompt is passed as an argument, not on stdin.

Leave engine unset to get ACP with automatic CLI fallback. Set engine: "acp" to require ACP (a failed prerequisite stops the run), or engine: "cli" to always use the headless CLI lane.

Models

Pick a Kimi model alias in the model field. The known options are:

• kimi-code/kimi-for-coding — K2.7 Coding (the adapter default)
• kimi-code/kimi-for-coding-highspeed — K2.7 Coding Highspeed
• kimi-code/k3 — K3

You can also type a model alias that is not in this list; Paperclip passes an unrecognized value straight through to the Kimi CLI.

Thinking Effort

The effort field maps a Paperclip effort value onto Kimi's supported thinking-effort tiers. Kimi exposes low, high, and max — there is no medium tier, so medium maps onto high.

Effort is honored on the CLI lane only (engine: cli, or the automatic CLI fallback), where it is forwarded as KIMI_MODEL_THINKING_EFFORT for effort-capable models — currently only kimi-code/k3. It is ignored for models that do not advertise effort support, and it is not forwarded on the default ACP engine lane. If you need effort control, pin engine: "cli".

Session Persistence

Kimi sessions resume with -r <session_id> when the stored session's working directory matches the current cwd. The session id is captured from the trailing session.resume_hint meta event.

The session codec also preserves these location hints when present:

• cwd
• workspaceId
• repoUrl
• repoRef

If the working directory changes, the adapter starts a fresh session instead of reusing the old one.

Skills Injection

For local runs, Paperclip delivers the desired skills through --skills-dir pointing at a per-run managed directory, so skills load reliably without polluting your own ~/.kimi-code/skills home. Remote runs sync skills into the remote skills home instead.

The Kimi skills home defaults to ~/.kimi-code/skills, or $KIMI_CODE_HOME/skills when you set KIMI_CODE_HOME. When you install Paperclip skills through the CLI for manual use, that is the directory they land in.

Authentication

Kimi Code authenticates in one of three ways:

• kimi login — the OAuth device flow, the same login you use for Kimi Code outside Paperclip.
• Providers configured in Kimi's config.toml.
• The KIMI_MODEL_NAME + KIMI_MODEL_API_KEY environment pair — set these in the adapter's env to run against a specific model and key directly.

Environment Test

The Test Environment button checks that the Kimi Code CLI is installed and executable, that the working directory is usable, and that authentication is ready before you try a real heartbeat. Fix the command or auth path if the probe fails.

Example

{
  "adapterType": "kimi_local",
  "adapterConfig": {
    "cwd": "/Users/me/projects/paperclip-workspace",
    "model": "kimi-code/kimi-for-coding",
    "instructionsFilePath": "/Users/me/projects/paperclip-workspace/INSTRUCTIONS.md",
    "env": {
      "KIMI_MODEL_API_KEY": {
        "type": "secret_ref",
        "secretId": "secret-id",
        "version": "latest"
      }
    },
    "timeoutSec": 300,
    "graceSec": 15
  }
}

Next Steps

• Creating an Adapter
• Adapter UI Parser Contract
• External Adapters