arkcli-helper

arkcli helper — configure Plan / Platform Endpoint / inject MCP for local AI Agents

Prerequisite: First use Read to read ../arkcli-shared/SKILL.md to obtain shared security rules and the authentication gate.

CRITICAL — arkcli helper The entire command domain does not support --dry-run。 Helper is intended for TTY/local harness configuration, not an API request preview. Any helper command with --dry-run should fail-fast as an unknown flag; the Agent must not generate that combination, nor treat it as write-operation protection. Real configure/reset/mcp/supabase must still first show the target and path and obtain explicit confirmation.

Command selection (choose the most specific subcommand first)

• When the user wants to view or configure an Agent's model/provider, Plan, Platform Endpoint, or verify --with-mcp / --with-supabase / --with-routing and other non-interactive options, you must choose arkcli helper configure; even to just view usage, you must run arkcli helper configure --help, and must not fall back to the parent-level arkcli helper --help。
• When the user only wants Harness tools and does not change model/provider, choose arkcli helper mcp [target]. If --capability is not passed, configure the entire Agent Plan MCP group; when only the professional dataset, Doubao Search, or Agent memory is wanted, pass --capability datapro|web-search|agent-memoryrespectively; when only Cloud Computer is wanted, pass --capability cua. After selecting Doubao Search, the target client's native WebSearch/web_searchis disabled by default; when the user requests to keep it, add --keep-native-websearch. When a disable occurs, immediately output the scope, configuration file, and the complete reset command. To only view usage, run arkcli helper mcp --help。
• arkcli-auth Only handle actual authentication blockers. When the user only asks to view the helper's --help , do not switch to login,init-volc , or other authentication commands.

Applicable scenarios / invocation signals

• The user wants to configure the model/provider for the Volcano Ark Plan or Platform Endpoint for local Claude Code / Codex / OpenCode / OpenClaw / Hermes / ZCode.
• The user wants to configure Doubao Search, the professional dataset, or OpenViking MCP for a supported target Agent, install only the Cloud Computer CUA Skill, or configure byted-supabase.
• The user asks about arkcli helper 's installation state, configuration state, file locations, reload method, or the Agent Plan Harness deduction/overage postpaid matrix.

Anti-invocation signals / should not be invoked

• When only querying/purchasing/renewing a plan or managing team seats, switch to arkcli-plans。
• When only searching foundation models, querying usage, or prices, switch to arkcli-models、arkcli-usage、arkcli-pricing。
• When installing arkcli's embedded Skills into an Agent, switch to arkcli-connect; do not misjudge "install arkcli skill" as configuring Harness.
• When only troubleshooting login, 401, or profile override issues, switch to arkcli-auth / arkcli-config, and do not repeatedly rewrite the Agent configuration.

TTY Harness capability matrix (Agent Plan / Agent Plan Team)

When a real person directly runs arkcli helper , the wizard order is fixed as: select Agent Plan profile → select model → select AI Agent → write model/provider → enter the Harness capability selection page. Each row simultaneously displays:

1. whether to reconfigure this time ([✓] selected,[ ] not selected,[-] currently not configurable);
2. whether plan deduction is enabled;
3. whether overage postpaid is enabled;
4. the local configuration status of the currently selected AI Agent.

This selection is independent of the current state: by default, all configurable capabilities are checked; capabilities already shown as "Configured" must still be reconfigured after proceeding to the next step. Only remote capabilities, those not supported by the current Agent, and Agent Memory not provided by the Team edition are shown as [-], and cannot be selected. The user may uncheck any capability; after unchecking all, selecting "Proceed to Configuration" will be blocked, and the user may also explicitly select "Skip Capability Configuration".

Known local adaptations are exact mappings and do not make fuzzy guesses based on server-side names:

Harness Capability	Local Delivery Form	Determination of "Configured"
Professional Dataset	MCP	dataPro-search Injected and using a real Plan Key
Doubao Search	MCP + Skill	Search MCP uses a real Plan Key,byted-web-search Skill is installed, and the Skill root directory .env contains a usable WEB_SEARCH_API_KEY
Agent Memory	MCP	OpenViking control-plane is injected and using a real Plan Key
AI Native Application Development Foundation	CLI + Skill	byted-supabase CLI、Skill、ark_login Agent Plan login states are all ready
Agent Evolution	CLI + Skill	Official Evolve CLI,evolve-setup Skill, workspace configuration, and credentials are all ready

The server-side catalog is the source of truth for remote entitlement status: the five known capabilities above are always displayed; when the current plan does not return a mapping, it is marked as having no remote entitlement and remote switching is not enabled, but local configuration can still be viewed or supplemented. Harnesses newly added on the server side but not yet adapted by arkcli are displayed after the five known items, marked as "Remote Capability Only", and only allow viewing/switching server-side entitlements, without providing speculative local configuration actions.

• The Personal edition directly manages the account switch.
• In the Team edition, regular members manage the current seat; when an administrator also has a seat, the current seat is the default, and the enterprise account scope can also be selected. When the account master switch is off, the seat switch is shown as not enabled and the higher-level restriction is explained in the details.
• Enabling overage post-payment is a real billing write operation: the CLI must display confirmation text, with "Cancel" selected by default. When the server delivers a protocol/purchase link, display it as well. Do not use --dry-run in place of confirmation.
• Agent Evolution only detects the official installation layout; it currently does not automatically execute remote latest/install.shwith an unpinned version. The details page provides the official command for a human to execute manually and then refresh.
• During the Doubao Search Skill download, a Spinner is continuously displayed; a human may press Ctrl+C to immediately cancel the current download and skip only the remaining Doubao Search configuration. At this point, the already injected Search MCP is retained, no Skill credentials are written, native WebSearch is not modified, and configuration continues for subsequent capabilities such as the Agent Memory checked in this session. This key belongs only to the TTY matrix and does not change the semantics of non-interactive commands.
• Forced routing is confirmed only after capability configuration is complete. The Helper re-detects the real Providers from disk and dynamically lists the capabilities that can be authorized; with zero Providers, it can only return to continue configuration or exit without enabling, and cannot install an empty authorization route.
• helper configure/mcp/supabase/list/reset The non-interactive contract does not change because of the matrix; Agent automation should still choose the most specific subcommand and must not attempt to manipulate the TTY menu.

Agent Plan Forced Retrieval Routing (Configuration and Runtime Protocol)

This Skill is responsible for the classification and invocation protocol; the actual enforcement comes from the UserPromptSubmit / PreToolUse gate installed by the Helper into the Harness. It injects a new turn_id, and block erroneous or unauthorized Providers before managed Provider execution. Native WebSearch, WebFetch, and WebExtract are not managed Providers and do not enter this gate.

Only Volc agent-plan / agent-plan-team can be configured with officially supported Claude Code, Codex, OpenCode, and OpenClaw:

arkcli helper configure <claude-code|codex|opencode|openclaw> \
  --profile <agent-plan-profile> \
  --with-routing

--with-routing implies business MCP; Supabase must explicitly add --with-supabase, and only after actual configuration succeeds does it enter the Provider set. When Hermes/Trae lacks a verifiable hook + MCP closed loop, it must fail and keep the Harness configuration unchanged; Platform, Coding Plan, and non-Volc products are not supported.

When ARKCLI ROUTING ENFORCEMENT (routing.v1) appears in the context, each round must:

1. Read this round's turn_id and Available providersas-is; do not forge or reuse the previous round's ID.
2. Split mixed questions into acceptable tasks, and select the unique Provider according to the fixed mapping:latest_public_web -> doubao_search、structured_dataset -> datapro、persistent_knowledge -> openviking、application_data -> supabase, local computation, or needs clarification -> none。
3. Call exactly once before any managed business Provider arkcli-agentplan-search-router.submit_route_plan, submitting the complete routing.v1 plan; when only calling native Web tools, do not submit a plan.
4. After the plan is accepted, only call authorized and actually available Providers; when the correct Provider is unavailable, explain what is missing and wait for the user to reconfigure; do not fall back.

The lead Skill / current Agent is responsible for understanding user intent;arkcli-agentplan-search-router only receives the plan and has authorization executed by the gate; it is not a search service, nor does it read the Prompt itself. Only when Doubao Search, DataPro, OpenViking, or Supabase is selected does it enter routing.v1; when the user explicitly requests native WebSearch/WebFetch/WebExtract, they can be called directly; they do not consume or inherit managed Provider authorization.

The same-Provider entry order for Doubao Search is fixed: when already loaded, call byted-web-search Skill first; when the Skill is not installed, the user explicitly requests MCP, or the Skill fails due to a local command/configuration errorbefore the business request is sent, preserve the original error and switch to mcp-server-askecho-search-infinityonly once. If authentication, timeout, or service errors occur after the business request has already been sent, it must stop and must not switch entries to retry. Do not extract, print, or manually pass the API Key to tools on your own.

Managed Providers must not substitute for one another, call first and submit the plan later, nor treat routing MCP as a search Provider. Native WebSearch/WebFetch/WebExtract are outside this constraint; however, when the user explicitly specifies a managed Provider, it must not silently switch to native tools after that Provider fails. For the Route Plan schema, mixed requests, and authorization lifecycle, see references/arkcli-helper.md。

helper mcp isa non-interactive Harness tool entry that does not change the model. When --capability is not passed, the existing whole-group MCP behavior is preserved: personal edition agent-plan injects four, team edition agent-plan-team injects only Doubao Search + DataPro. When --capability is passed, only the selected single item is configured, without bringing in other enabled tools.

Platform Endpoint Configuration

The Platform profile is only responsible for configuring the Agent's model/provider:model is written as the Endpoint ID selected by the user, the base URL uses Platform's /api/v3, and the protocol continues to follow each harness's existing behavior (Chat or Responses).

• Only displayEndpoints created by the current SSO sub-user、Running, whose model is explicitly verified to betext output; VLM (image-text input, text output) is available.
• Image generation, video generation, 3D generation, audio, Embedding, content generation, or unknown models are never displayed, and cannot be used through --model bypass.
• In the Agent configuration, model still writes the Endpoint ID; the context window, max completion tokens, and input/output modalities follow the base model name bound to the Endpoint, reusing the existing ArkModels metadata enrichment rules of Agent Plan / Coding Plan. When the metadata query fails, the extension fields are likewise omitted on a best-effort basis, without blocking the Endpoint that has already passed eligibility validation.
• Hermes Agent supports writing the Platform Endpoint as volcengine-platform model/provider; MCP injection is still not supported.
• This integration only adds a metadata caller for Platform; it does not modify the Plan model list, default model, metadata query, MCP, or Supabase behavior.
• When there is no Endpoint created by yourself, the wizard opens https://ark.volcengine.com/region:cn-beijing/endpoint/create?agentMode=close; after creation is complete, select "Refresh list". An existing but not running Endpoint must be started before refreshing.
• Platform Not supported MCP, OpenViking, Supabase, or forced routing;--with-mcp、--with-supabase、--with-routing will report an error.

Non-interactive invocation:

arkcli helper configure codex \
  --profile <platform-profile> \
  --endpoint <ep-id>

After successful configuration, the Endpoint can be invoked through the OpenAI-compatible entry point:/responses or /chat/completions, the requested model all use that <ep-id>。

Which MCPs are injected (hardcoded, do not hallucinate)

server	Transport	key source
mcp-server-askecho-search-infinity(Doubao Search)	stdio(uvx)	Agent Plan's API Key(env ASK_ECHO_SEARCH_INFINITY_API_KEY, the same one as dataPro / control planesame one plan key); if unavailable, write a placeholder
dataPro-search	http(streamable)	Agent Plan's API Key(header X-Agent-Plan-Key, bare key)
openviking-dataplane（Personal edition agent-plan only）	http(streamable)	Access key for the OpenViking library(data plane; header Authorization: Bearer <key>); obtained via vikingdb in two steps: list libraries → get key by library. When the account has multiple libraries, a library must be selected (see below). Skip when the account has 0 libraries
openviking-controlplane（Personal edition agent-plan only）	stdio(uvx)	Agent Plan's API Key(control plane; env AGENTPLAN_API_KEY); does not depend on the OV library list, and is injected as long as the personal edition has Agent Plan

Personal edition vs team edition: In the table above, the two OpenViking entries arePersonal edition agent-plan exclusive.Team edition agent-plan-team has nothing to do with OpenViking — only the two entries Doubao Search + dataPro are injected,openviking-dataplane / openviking-controlplane are not configured, and vikingdb will not be queried either.

Native WebSearch selection after Doubao Search succeeds

Only when the Doubao Search MCP is selected,byted-web-search Skill is installed successfully, and the same API Key of the selected Agent Plan has been written to the Skill root directory .env 's WEB_SEARCH_API_KEY ,helper does it handle the target client's native WebSearch/web_search. TTY will let the user choose "disable (recommended) / keep"; non-interactive commands disable by default, and keep when --keep-native-websearch is passed. Ordinary model/provider configuration, Platform, Coding Plan, explicitly skipping Doubao Search, MCP injection failure, Skill installation failure, or Skill credential write failure do not trigger it. The Helper does not modify third-party Skill source code, nor may it print that Key.

• The scope is strictly limited to WebSearch/web_search；will notdisable webfetch、web_extract、x_search, browser, or other tools.
• Project-level configuration searches upward from the current directory for .git(the worktree's .git files are also supported); if not found, the current directory is used.
• After successful configuration, the command immediately outputs: client, scope, configuration path, and arkcli helper reset <harness>. This reset is afull rollback, which also removes the model/provider/MCP written by ArkCLI; it is not "only restoring search".
• ArkCLI only restores fields that it owns and that have not been modified again by the user. If the user had already disabled search, it does not take over; if the same field is externally modified after configuration, reset keeps the user's current value and warns.
• After TRAE writes .trae/hooks.json , you must also enable the current project in TRAE Settings > Hooks ; the command will clearly prompt "pending activation", and you must not claim that it has taken effect merely by writing the file.

host ≠ target (the most critical concept)

• host = where you (this AI Agent) are running right now — the command reads environment variables to detect it automatically, so you do not need to determine it.
• target = whose configuration the MCP should be written into — it can be the host itself, or another agent.
• The two are decoupled: a person in OpenCode can also configure MCP for Claude Code.

→ The user in the promptnamed a certain agent(such as "configure for opencode / codex"): run arkcli helper mcp opencode / arkcli helper mcp codex → The user says "current / this Agent" or did not name one: run arkcli helper mcp(automatically detect the current host)

Exhaustive subcommands

Call	Description
arkcli helper mcp [target] [--capability <datapro|web-search|agent-memory|cua>] [--profile P] [--ov-resource <库名>] [--scope project] [--keep-native-websearch] [--codex-config-scope profile|global] [--codex-profile <name>] [--dsh-config-scope home|profile] [--dsh-profile <name>]	If --capability is not passed, the entire group of MCP retains the old behavior; when explicitly selecting, only one item is configured,does not change model。web-search will also install the Skill and handle native WebSearch according to the original rules;agent-memory is personal edition only, for multiple repositories use --ov-resource；cua is personal edition Large/Max only, installs only byted-util-ark-cua Skill for the target, and does not write any MCP; Codex's MCP is written by default to profile ~/.codex/arkcli.config.toml; DSH is written by default to the home layer, and the profile layer requires specifying two DSH flags at the same time
arkcli helper configure <harness> [--profile P] [--model M|--endpoint ep-id] [--with-mcp] [--keep-native-websearch] [--with-supabase] [--with-routing] [--codex-config-scope profile|global] [--codex-profile <name>]	Plan uses model/provider; Platform must use --endpoint to select the text Endpoint. Only Plan can add MCP/Supabase; forced routing is available only for Agent Plan.--keep-native-websearch It only affects Doubao search configuration and does not change the routing gate.
arkcli helper list	Check supported agents + installation/configuration status (read-only)
arkcli helper supabase [--profile P]	Non-MCP: installs byted-supabase-cli + skill + injects Volcengine login state (enabling byted-supabase database capabilities); unrelated to harness. Agent Plan only (all personal edition tiers + all team edition tiers)
arkcli helper reset <harness>	Completely removes the model/provider/MCP/managed routing hook/tool/plugin injected by arkcli, and restores the native search fields owned by ArkCLI and not externally modified
arkcli helper	TTY interactive wizard (requires a terminal; for non-interactive scenarios use the above); before entering the wizard, login state is checked, and when not logged in / SSO has expired, SSO is launched according to the current login context (Volcengine uses volc-sso; when a brand-new user has no clear context, the auth login menu is used), and after success the wizard continues; Agent Plan/Team proceeds by profile→model→Agent→capability multi-select→item-by-item configuration, then dynamically confirms forced routing based only on the verified real Provider

⚠️ If you want to "only add MCP" → helper mcp; if you want to "connect the agent to the plan, together with the model" → helper configure --with-mcp. Do not use configure to only add MCP (it will also (re)write model).

🎯 The user says "configure the whole set of harness tools (for my plan) / set them all up for me"(MCP + Supabase in one step) → arkcli helper configure <harness> --with-mcp --with-supabase. This is the only path where an agent can set up the MCP trio + Supabase with a single command (the interactive wizard arkcli helper requires a TTY, so an agent can't run it; its automatic SSO only serves a real human terminal);--with-mcp only configures MCP, without Supabase; if you want to include Supabase, you must explicitly add --with-supabase(if not eligible / on failure, it only warns and does not block harness configuration).

🧭 The user explicitly asks for "forced managed Provider routing / routing.v1 / preventing Doubao Search, DataPro, OpenViking, and Supabase from cross-routing" → use this Skill's "Agent Plan forced retrieval routing" protocol and execute helper configure <harness> --with-routing. This flag implies business MCP; Supabase still needs to be explicitly added --with-supabase; native Web tools are not managed by this flag.

byted-supabase database capability (helper supabase;non-MCP)

arkcli helper supabase and the MCP injection above aretwo different categories of capability: itdoes not write the agent's mcp.json, but insteadinstalls byted-supabase-cli + skill and uses the current Volcengine Agent Plan login stateinjects the login state(connecting to the byted-supabase / Volcengine Supabase database platform).It is independent of which harness is chosen — what it configures is the byted-supabase-cli standalone tool itself.

• Eligibility: Agent Plan only — Personal edition agent-plan all tierssupported (including small/medium/large/max), Team edition agent-plan-team all tierssupported. Ineligible commands report an error directly with an explanation.
• Actions: install the CLI (npx -y @byted-supabase/cli@latest install, together with the matching byted-supabase agent skill) → assemble Console Login credentials using the STS + refresh_token of the selected Agent Plan identity → byted-supabase-cli login --credential-file(Personal edition with --is-agent-plan, Team edition additionally --agent-plan-seat-id <实时反查>) inject into the fixed profile ark_login。
• Triggers: the user says "configure byted-supabase / connect the database / install supabase cli / connect supabase / connect to the database with my plan".
• Three configuration entry points(same core supabase.Configure): ① dedicated configuration arkcli helper supabase; ② non-interactive/agent incidental configuration arkcli helper configure <h> --with-supabase(no confirmation dialog, on failure only warns, does not block harness configuration); ③ the interactive wizard arkcli helper optional step at the end (only for eligible plans).helper mcp / configure --with-mcp does not include Supabase — if you want to configure it incidentally you must explicitly use --with-supabase。
• ⚠️ v3 ve handoff identity (source=ve) cannot configure supabase: helper supabase the core gatherInputs strongly depends on LoadIdentityTokenFull(key) reading the refresh_token from identity_store token.json to assemble Console Login credentials; whereas a source=ve identitydoes not write token.json (the refresh_token is managed internally by volcengine-go-sdk, and the arkcli side cannot obtain the plaintext), and will report 读 identity token: .... When you hit this error, tell the user: to configure supabase you need to log in once via arkcli's native SSO (skipping ve handoff); the specific approach is to first ve logout (or leave ve in a logged-out state) and then run arkcli auth login to obtain source="arkcli" 's identity.

Scope boundaries (manage well, don't overstep)

• model/provider configurable target:claude-code / codex / deepseek-harness / pi / opencode / openclaw / hermes / zcode / workbuddyAmong them, Hermes and Pi support Plan and Platform Endpoint, but neither supports MCP; DSH supports Plan / Platform / Coding Plan and MCP injection; ZCode and WorkBuddy support model + MCP.
• There are 8 targets that can inject MCP:claude-code / codex / opencode / openclaw / trae / deepseek-harness / zcode / workbuddy. CUA is a Skill rather than an MCP, and can also be precisely installed for hermes / pi; the command passes only a single target, and does not scan or modify other Agents.
• This skill will be arkcli +connect installed into many agents (cursor / gemini-cli / codex …40+), but MCP injection only supports the 8 targets listed in the previous item. When the host is another agent: either the user names one of them as the target, or the command reports "please specify explicitly" —— never silently configure the wrong target。
• codex supports model/provider + MCP. By default profile modewrites ~/.codex/arkcli.config.toml, and requires codex --profile arkcli to be used to start the terminal/TUI for it to take effect; passing --codex-config-scope global only writes ~/.codex/config.toml, and that scope may be shared and read by Codex CLI/TUI, Codex App, and IDE extension.
• trae(AI IDE) is MCP-only: does not configure model/provider;no runtime host detection(will not be automatically treated as a host), it can only explicitly arkcli helper mcp trae. By default writes user-level ~/.trae/mcp.json, adding --scope project writes project-level ./.trae/mcp.json(project-level requires enabling the "Enable project-level MCP" switch in Trae "Settings → MCP" + reopening the project). After Doubao search succeeds, it additionally writes to the project root .trae/hooks.json, and it also needs to be enabled in TRAE Settings > Hooks for the current project.
• hermes supports model/provider configuration for Plan / Platform Endpoint, but does not yet support MCP injection → when an MCP request hits, just say "not yet supported".
• deepseek-harness (DSH): default home scope, can directly run arkcli helper configure deepseek-harness --profile <plan> or arkcli helper mcp deepseek-harness; to write profile scope, pass --dsh-config-scope profile --dsh-profile <name>, and the Helper will ensure the profile directory exists. DSH provider/model configuration lands in $DSH_HOME/settings.yaml the llm-pi-ai.providers.arkcli-<planType>: section (independent provider,does not overwrite llm-deepseek: the official DeepSeek models under it; the user can switch between official DeepSeek and arkcli Volcano models within DSH); the default model is written to agent-default-model:; the API key is written to $DSH_HOME/.credentials.yaml of the version 1 document refs.ARKCLI_<PLAN>_API_KEY, resolved by the DSH credentials service according to apiKeyEnv (does not overwrite the user's DEEPSEEK_API_KEY). This is a breaking change: when the old-version ArkCLI's llm-deepseek: fingerprint, pure flat credentials, or legacy credential keys remaining at the top level of the version 1 document are detected,configure does not automatically migrate, but instead refuses to write and requires running first arkcli helper reset deepseek-harness；reset to clean up these old formats for compatibility, but any custom apiKeyEnv is still regarded as user configuration. settings and credentials are updated as a rollbackable transaction;reset only deletes entries that still retain the ArkCLI provider fingerprint, the corresponding credentials, and the default model that still points to it. MCP / native WebSearch disabling lands in $DSH_HOME/profiles/<name>/cordis.patch.yml(profile scope) or $DSH_HOME/cordis.patch.yml(home scope). DSH does not export env marker,helper mcp not passing a target will not automatically select DSH. Native WebSearch uses a patch layer to add to @deepseek-ai/dsh-tool-web plus disabled: true(trae-style hook fallback, precisely affecting the current profile, restored by marker on reset).
• pi(minimal terminal coding harness,npm i -g --ignore-scripts @earendil-works/pi-coding-agent) supports model/provider configuration for Plan / Platform Endpoint, buthas no native MCP host capability → If a DataPro / Doubao Search / Agent memory request hits, just say "not supported yet".helper mcp pi --capability cua is an exception, because CUA only installs Skills and does not inject MCP; it is still subject to the Personal Edition Large/Max eligibility gate. The provider/model list is written to ~/.pi/agent/models.json(openai-completions provider, key = plan type), and the default provider/model is written to ~/.pi/agent/settings.json in the same directory, defaultProvider / defaultModel(bare model id); the directory can be overridden by $PI_CODING_AGENT_DIR .
• zcode supports model/provider configuration and MCP injection for Plan / Platform Endpoint. The model configuration is written to $ZCODE_HOME/v2/config.json(default ~/.zcode/v2/config.json); ZCode will not hot-reload the provider registry. After configuring, you must fully exit the ZCode main process, reopen it, and create a new session; you cannot just switch models or reuse an old session. When encountering Coding Plan InvalidParameter / token limit 400, do not manually change the fixed value of a certain model; rerun helper configure zcode, and the Helper will write the authoritative limit.context and convert limit.output to the decimal token limit accepted by the Ark gateway; see the reference for details.
• workbuddy(CodeBuddy IDE, VSCode family): supports both model + MCP,no runtime host detection(will not be automatically treated as a host), can only be explicitly arkcli helper configure workbuddy / arkcli helper mcp workbuddy. model and MCP are written simultaneously to thethree locations ~/.workbuddy-ai/(the runtime directory that the IDE actually reads),~/.workbuddy/ and ~/.codebuddy/: the model lists go into their respective models.json(OpenAI-compatible,url is the full path containing /chat/completions , and arkcli-written entries are marked with the arkcliManaged marker for precise reset), and MCP goes into their respective mcp.json(mcpServers.*, with the schema isomorphic to claude-code).Native WebSearch disabling is not supported(no hook seam); the Doubao Search configuration only injects MCP and does not take over native search.
• Forced routing officially supports claude-code / codex / opencode / openclaw; Hermes/TRAE go through the capability gate. When the hook + MCP closed loop is missing, zero Harness configuration is written and an error is reported; no prompt downgrade is performed.
• Plan's model can be configured as the routing model ark-code-latest(the interactive wizard will first ask "smart routing (ark-code-latest) vs specifying a concrete model"; in non-interactive mode, directly --model ark-code-latest)。Switching the routing target of ark-code-latest (Auto intelligent scheduling / locking to a certain underlying model) is not in this skill — go to arkcli plans model-apply --plan <plan> --model <目标>(see ../arkcli-plans/), write the control plane, and interact with the console.

Prerequisite

• Must have an Agent Plan subscription(Doubao Search / dataPro require an Agent Plan key; the two OpenViking ones are exclusive to the Personal Edition). The command automatically locates the Agent Plan profile under the account,regardless of the current active profile; both Personal Edition agent-plan and Team Edition agent-plan-team can be injected, butthe two are not equivalent: the Personal Edition injects four,Team Edition agent-plan-team is unrelated to OpenViking and only injects Doubao Search + dataPro, the two. If there is none, guide arkcli auth login activation; when the account has multiple Agent Plan profiles at the same time (such as Personal Edition + Team Edition), the command will list the profile names detected this time; use the structured selection capability provided by the host to let the user choose one, and after selection, rerun with --profile <name> ; do not arbitrarily favor the Personal Edition, Team Edition, or active profile.
• After injection, agent needs to be restartedwill only then load the new MCP. For the Codex profile mode, you still need to use codex --profile <name> to start; for Trae, you also need to go to the "Settings → MCP" panel to confirm that the MCP is enabled (project-level files additionally require turning on the "Enable project-level MCP" switch), and in Settings > Hooks enable the current project before reopening the project.

Selection of the OpenViking repository (specific to openviking-dataplane;personal edition only agent-plan)

This section applies only toPersonal edition agent-plan。Team edition agent-plan-team is unrelated to OpenViking. For the team edition, the command directly skips the entire repository listing/selection process below and only injects Doubao Search + dataPro.

openviking-dataplane 's key is bound to a certain OpenViking repository (repository name ↔ ResourceID 1:1). The command first lists the repositories under the account and branches by count:

• 0 repositories → automatically skip openviking-dataplane (still inject the other three, including openviking-controlplane), and prompt to go to https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing/create to create a repository and rerun. You can directly accept the skip.
• 1 repository → use it directly, no selection needed.
• Multiple repositories → the command errors out and lists all repository names (in the form 检测到多个 OpenViking 库,请用 --ov-resource <库名> 指定其一:[a, b, c]). Hand the real repository names returned in this error to the structured selection capability provided by the host; do not hardcode any host tool name, and do not fill in repositories from memory. After obtaining the selected repository name, rerun the same command with --ov-resource <库名> ; if the host has no structured selection capability, fall back to a concise numbered list.
• Failed to obtain key (non-0 repositories) → openviking-dataplane writes the placeholder Bearer <OPENVIKING_KEY>, prompting the user to replace it manually.
• openviking-controlplane is unaffected by the above: the personal edition always injects it as long as there is an Agent Plan (the team edition does not inject it, see above).

Routing judgment / counter-triggering

• "Configure MCP / Doubao Search / web search / dataPro / web search for the Agent" → arkcli helper mcp
• "Configure only a certain Harness capability for Codex" → arkcli helper mcp codex --capability <datapro|web-search|agent-memory>; configure only Cloud PC → arkcli helper mcp codex --capability cua
• "Point the agent to my plan (including the model)" → arkcli helper configure
• "Open the helper to view the Harness deduction/overage switches and the local configuration matrix" → run in a real-person TTY arkcli helper; the Agent does not drive this menu automatically
• "Configure the full set of harness tools / configure MCP + Supabase all at once" → arkcli helper configure <h> --with-mcp --with-supabase
• "Enable forced managed Provider routing / routing.v1 / prevent Doubao Search, DataPro, OpenViking, and Supabase from cross-routing" → use this Skill's forced retrieval routing protocol to execute arkcli helper configure <h> --with-routing
• "Configure byted-supabase / connect the database / install supabase cli / connect supabase" → arkcli helper supabase(not MCP, install CLI + skill + inject login state); or incidentally configure --with-supabase
• install the arkcli skills installinto the agent → go through arkcli-connect, unrelated to this skill
• 401 / login / authentication failure → go through arkcli-auth
• image generation / video generation → go through arkcli-gen

For detailed flags, output examples, error codes, and edge cases, see references/arkcli-helper.md。

References / detailed reference

• references/arkcli-helper.md: complete flags, MCP/Skill/CLI placement, Harness matrix state machine, and error handling.
• references/evals.md: Trigger, counter-trigger, write-operation guards, and regression cases.
• ../arkcli-shared/SKILL.md: authentication, output, and security constraints shared by all arkcli Skills.